Workflows – ProteusAI Reference

🚫

Internal use only!

A workflow is a series of steps executed in a specific order to complete a task. The steps in a workflow are of different types, from user messages to AI prompts and MCP server tools. A workflow is a blueprint of steps to be taken. To perform useful work, a workflow must be executed. The execution of a workflow may take up to a year to reach completion.

Use Cases

Workflows are foundational to an AI agent's ability to think and plan. When an AI agent thinks or plans, it is creating a workflow to help it achieve the task at hand.
Workflow makes agent-human collaboration possible by including steps that require human intervention. For instance, human confirmation may be needed to complete an AI-driven checkout process on an e-commerce platform.
The transition of a workflow from one step to another is autonomous. Consequently, businesses can leverage workflows to automate business processes. For instance, a business may leverage a workflow to automate the generation of monthly reports or the dispatching of reminders every morning.
Todo apps and similar apps can also leverage workflows to transform from dumb lists to smart personal assistants.

Create Workflow

POST /api/workflows

curl https://management-api.useproteus.ai/api/workflows \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Onboarding Checklist",
            "description": "This workflow runs during the onboarding of a user",
            "inputsSchema": {
                "type": "object",
                "properties": {
                    "assignee": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the assignee"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the assignee"
                            }
                        }
                    },
                    "created_by": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the user who created the checklist"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the user who created the checklist"
                            }
                        }
                    }
                },
                "required": [ "assignee" ]
            },
            "orgId": "6816330b6f46b5afc080fbf7"
        }'

You can also create workflows via the orgs API POST: /api/orgs/:orgId/workflows. You will not be able to supply an orgId field in the request body.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/workflows \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Onboarding Checklist",
            "description": "This workflow runs during the onboarding of a user",
            "inputsSchema": {
                "type": "object",
                "properties": {
                    "assignee": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the assignee"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the assignee"
                            }
                        }
                    },
                    "created_by": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the user who created the checklist"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the user who created the checklist"
                            }
                        }
                    }
                },
                "required": [ "assignee" ]
            }
        }'

Get Workflow

GET /api/workflows/:workflowId

This endpoint returns a workflow.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

You have to be a member of an organization to view a workflow in that organization.

List Org Workflows

GET /api/orgs/:orgId/workflows

This endpoint fetches the workflows in an organization.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/workflows \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

If the current user is not a member of this organization, an error response is returned.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/workflows \
    -H "Authorization: Bearer user-73dd22b0c07a542d080d48a2.9e0ac60c1472a5f2949f8978e82d2582.dfbaf5a25782b0608e173d295e977259.2a52f18cf2ce3d84872ae7fc73c60822ad6fe0ad7dc21f58"

Add Event Handler to Workflow

POST /api/workflows/:workflowId/event-handlers

This endpoint adds a plugin instance as an event handler for a workflow. The response of the API is the plugin instance.

An event handler is a plugin instance that listens for workflow events. These event handlers may also receive tokens that allow them to read or update the workflows to which they are attached.

Let's create a event handler plugin for our use cases.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/plugins \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Workflow Events Processor",
            "description": "This plugin processes workflow events",
            "events": [
                "WORKFLOW_EXECUTION_STARTED",
                "WORKFLOW_EXECUTION_COMPLETED",
                "WORKFLOW_STEP_CREATED",
                "WORKFLOW_STEP_EXECUTION_SCHEDULED",
                "WORKFLOW_STEP_EXECUTION_STARTED",
                "WORKFLOW_STEP_EXECUTION_COMPLETED",
                "WORKFLOW_STEP_EXECUTION_REMINDER"
            ],
            "isPublic": true,
            "scopes": ["WORKFLOW_WRITE"],
            "tags": ["workflow", "checklist", "task", "reminders"],
            "type": "WORKFLOW_EVENT_HANDLER",
            "webhookUrl": "https://myplugins.com/workflow-event-handlers/default-handler/webhook"
        }'

Remember to verify your plugin's webhook.

curl https://management-api.useproteus.ai/api/plugins/68720400d3b7d6b2ea45fd69/verify-webhook \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Now, we add the plugin as an event handler for the workflow.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/event-handlers \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Workflow Event Handler",
            "pluginId": "68720400d3b7d6b2ea45fd69",
            "events": [
                "WORKFLOW_EXECUTION_STARTED",
                "WORKFLOW_EXECUTION_COMPLETED",
                "WORKFLOW_STEP_CREATED",
                "WORKFLOW_STEP_EXECUTION_SCHEDULED",
                "WORKFLOW_STEP_EXECUTION_STARTED",
                "WORKFLOW_STEP_EXECUTION_COMPLETED",
                "WORKFLOW_STEP_EXECUTION_REMINDER"
            ],
            "scopes": ["WORKFLOW_WRITE"]
        }'

This API call dispatches the PLUGIN_INSTALLED event to the webhook of the plugin as a HTTP POST request.

Execute a Workflow

POST /api/workflows/:workflowId/executions

This endpoint executes a workflow. This creates an object of type WorkflowExecution which represents a specific execution of a workflow.

Creating a workflow is like defining a function in typical programming languages. Executing a workflow is like calling a function at runtime. Continuing with that analogy, workflows can be created with inputsSchema just like functions can be defined with input parameters. To execute a workflow with inputsSchema, you need to supply an inputs field that can be validated against the inputsSchema.

Executing a workflow without the expected inputs field results in an error response.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/executions \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/executions \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "inputs": {
                "created_by": {
                    "name": "Jane Doe",
                    "email": "jane.doe@email.com"
                }
            }
        }'

Executing a workflow with the expected inputs field results in a WorkflowExecution being created.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/executions \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "inputs": {
                "assignee": {
                    "name": "John Doe",
                    "email": "john.doe@email.com"
                },
                "created_by": {
                    "name": "Jane Doe",
                    "email": "jane.doe@email.com"
                }
            }
        }'

From the response above, certain things are worth noting.

Every workflow execution has a context object which contains, amongst other things, the inputs with which the workflow execution was created. This context object can be accessed programmatically, as will be shown later in this document.
The status of the workflow execution is COMPLETED. This is because the workflow that was executed has no steps. Consequently, the execution is completed shortly after it is started.

When a workflow is successfully executed, the WORKFLOW_EXECUTION_STARTED event is dispatched. The status of the workflow execution is RUNNING at this time.

If the workflow has no steps, the workflow execution terminates. The WORKFLOW_EXECUTION_COMPLETED event is dispatched. The status of the workflow execution becomes COMPLETED.

Workflow events are dispatched to the webhooks of the plugins installed as the workflow event handlers and to agents that are attached to the workflow.

Add Step to Workflow

POST /api/workflows/:workflowId/steps

A workflow without steps is like an empty function; it's not very useful. A typical workflow has at least one step, with a step clearly marked as the starting point or first step.

A step represents a unit of work that needs to be done. There are different types of steps.

It's possible to create a workflow's steps at the same time the workflow is being created.

curl https://management-api.useproteus.ai/api/workflows \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Onboarding Checklist",
            "description": "This workflow runs during the onboarding of a user",
            "inputsSchema": {
                "type": "object",
                "properties": {
                    "assignee": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the assignee"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the assignee"
                            }
                        }
                    },
                    "created_by": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "The name of the user who created the checklist"
                            },
                            "email": {
                                "type": "string",
                                "description": "The email of the user who created the checklist"
                            }
                        }
                    }
                },
                "required": [ "assignee" ]
            },
            "orgId": "6816330b6f46b5afc080fbf7",
            "steps": [{
                "name": "introduction",
                "description": "The assignee introduces themselves",
                "type": "USER_MESSAGE",
                "inputsTemplate": {
                    "message": "Hi {{inputs.assignee.name}}, please introduce yourself in the #general channel on Slack"
                }
            }, {
                "name": "signature",
                "description": "The assignee signs the relevant docs",
                "type": "USER_MESSAGE",
                "inputsTemplate": {
                    "message": "Hi {{inputs.assignee.name}}, please sign all the relevant docs"
                }
            }]
        }'

A step can also be added to an existing workflow.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/steps \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "worktools",
            "description": "The assignee collects their work tools",
            "type": "USER_MESSAGE",
            "inputsTemplate": {
                "message": "Hi {{inputs.assignee.name}}, reach out to the Ops team for your official work tools"
            }
        }'

Adding a step to a workflow dispatches the WORKFLOW_STEP_CREATED event.

List Steps in Workflow

GET /api/workflows/:workflowId/steps

This endpoint fetches the steps in a workflow.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/steps \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

From the response above, certain things are worth noting.

Only the first step added to the workflow has the field isFirstStep set to true.
The nextId of each step tells you the next step to be executed.
There is no need to explicitly specify isFirstStep or nextId when creating a step.

Execute a Workflow with Steps

POST /api/workflows/:workflowId/executions

Now that the workflow has some steps, it can be executed in order to observe how it transitions from one step to another.

curl https://management-api.useproteus.ai/api/workflows/686fe2f7e793712ff1dd876d/executions \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "inputs": {
                "assignee": {
                    "name": "John Doe",
                    "email": "john.doe@email.com"
                },
                "created_by": {
                    "name": "Jane Doe",
                    "email": "jane.doe@email.com"
                }
            }
        }'

The status of the workflow execution is RUNNING. This is because the workflow that was executed has some steps that need to be processed before the workflow execution can be completed.

When a workflow is successfully executed, the WORKFLOW_EXECUTION_STARTED event is dispatched.

When the execution of a step is started, the WORKFLOW_STEP_EXECUTION_STARTED event is dispatched.

Get Workflow Execution

GET /api/workflows/executions/:workflowExecutionId

This endpoint returns a workflow execution.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2 \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

From the response above, notice how context.steps now contains the inputs with which the step name introduction was executed.

Also, the pointer points to the id of the current workflow step being processed.

A workflow execution may take as long as a year to reach completion. However, it is advised that workflow executions reach completion in less than a year. Workflow executions may be automatically deleted one year after they are created.

Get Workflow Execution Stack

GET /api/workflows/executions/:workflowExecutionId/stack

This endpoint returns the stack of a workflow execution. The stack is an array of WorkflowStepExecution objects showing the flow of execution.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/stack \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Get Workflow Execution Logs

GET /api/workflows/executions/:workflowExecutionId/logs

This endpoint returns the logs of a workflow execution. This is an array of WorkflowLog objects for the current workflow execution.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/logs \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Complete a Step Execution

POST /api/workflows/executions/:workflowExecutionId/complete-step

This endpoint completes the execution of a workflow step. This operation advances the workflow execution to the next step or completes it if there is no subsequent step.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/complete-step \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "stepName": "introduction"
        }'

When the execution of a step is completed, the WORKFLOW_STEP_EXECUTION_COMPLETED event is dispatched.

If there is a next step, the execution of that step is started and the WORKFLOW_STEP_EXECUTION_STARTED event is dispatched.

If you were to query the workflow execution, you'd see that its pointer has moved from the introduction step (with ID 6872d4307a58be780bfc9bd8) to the signature step (with ID 6872d4807a58be780bfc9bd9).

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2 \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

You can also take a look at the stack of the workflow execution to see the progression from the introduction step to the signature step.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/stack \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Let's proceed with completing the remaining two steps in the workflow.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/complete-step \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "stepName": "signature"
        }'

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2/complete-step \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "stepName": "worktools"
        }'

When the execution of the last step is completed, the WORKFLOW_STEP_EXECUTION_COMPLETED event is dispatched.

Seeing that there is no next step, the execution of that workflow is completed and the WORKFLOW_EXECUTION_COMPLETED event is dispatched.

If you were to query the workflow execution, you'd see that its pointer is now null and the status of the workflow execution is now COMPLETED.

curl https://management-api.useproteus.ai/api/workflows/executions/687371ff828ee21b2bfafec2 \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Workflow Triggers

Step Types

USER_MESSAGE

This step represents a message or prompt to be sent to a user. The workflow is stuck on this step until the step is explicitly marked as completed (or cancelled).

Messages Events