Installing the SDK

This page provides instructions for installing the SDK and configuring your development environment for the Ebbot Integrations SDK.

Workflow servers are the way the Ebbot platform can be extended by exposing actions that the Ebbot platform can take, and triggers that activate the Ebbot platform when certain events happen.

Installation

We recommend that you use uv when developing with the SDK. uv is a package manager and virtualenv built into one.

Start by creating a new project:

uv init workflow_server_demo

Then install the integrations_sdk:

uv add integrations_sdk git+https://github.com/ebbot-ai/integrations_sdk.git@main

Create the server

Add the following to a Python file, for example in the root of your project:

from pydantic import BaseModel
from integrations_sdk.server import start_workflow_server


class Options(BaseModel):
    notSecret: str


class Secrets(BaseModel):
    secret: str

app = start_workflow_server(
    "fns",
    "http://localhost:9000",
    "engine-api-key",
    Options,
    Secrets,
    install_instructions="Docs on point, README magic",
    docs="My docs",
    auth_token="optional-shared-token",
)

Arguments:

• module_name: module path containing workflow actions and triggers (e.g. "fns"). This should be the path of a Python module that will be scanned for triggers and actions.

• engine_base_url: base URL for the Ebbot workflow engine. You can set this to any URL when testing your server.

• engine_api_key: bearer token used when the server calls the Ebbot workflow engine. You can set this to any value when testing.

• Options/Secrets: Pydantic models describing required connection data.

• validator: optional function to validate the Options and Secrets payload.

• install_instructions: This is shown when installing the workflow server. Markdown is allowed.

• docs: Provide documentation for this workflow server. This will be added as a documentation page on the ebbot platform docs. Markdown is allowed.

• auth_token: optional server auth; if set, requests must include Authorization: Bearer <token>.

• dev_mode: The Ebbot platform takes care of storing options and secrets for you in production. That is not available when testing the server locally, so we provide a dev_mode that stores your information in a local SQLite database. Set this to true when testing your server.

• post_install_instructions: This is a callback that you can specify in order to provide post install instructions after a connection is created. It will be displayed in the UI after a connection has been established.

Setting up the server for development

In this example, actions and triggers that you create will be located in the fns folder. Change this to your liking.

When developing and the engine_base_url and engine_api_key do not matter, you should also set dev_mode=True to allow you to store options and secrets locally.

from pydantic import BaseModel
from integrations_sdk.server import start_workflow_server


class Options(BaseModel):
    notSecret: str


class Secrets(BaseModel):
    secret: str

app = start_workflow_server(
    "fns",
    "http://localhost:9000", # can be anything
    "engine-api-key", # can be anything
    Options,
    Secrets,
    dev_mode=True # Set to true.
)

Starting the server

You can start the server locally by running the Python file you created with FastAPI. For example, if you named the file main.py:

[uv run] fastapi dev endeavour/main.py

What the server exposes

The workflow server exposes a REST API that the Ebbot platform uses to interact with it. You can check the API by navigating to http://localhost:8000/docs

Setting up your server for production

When hosting your server with Ebbot you need to provide a correct engine URL and API key. If we take care of hosting, we will provide those for your server through environment variables. Starting a production server should look like:

from pydantic import BaseModel
from integrations_sdk.server import start_workflow_server
from os import getenv

class Options(BaseModel):
    notSecret: str


class Secrets(BaseModel):
    secret: str

app = start_workflow_server(
    "fns",
    getenv("CONNECTION_SERVER_URL"),
    getenv("CONNECTION_SERVER_KEY"),
    Options,
    Secrets,
    dev_mode=False
)

Congratulations on your good work so far. Start learning about how to develop locally through the link below.

Developing