> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Automating Multi-Step Agent Workflows

> Design and run durable multi-step pipelines where each step invokes an AI agent, with async execution, Human-in-the-Loop pausing, and workflow cloning.

Workflows let you chain agent actions into repeatable, multi-step pipelines. Each step in a workflow triggers an agent run, passing input forward through the sequence. Workflows execute asynchronously — you receive a job ID immediately and poll for progress — making them suitable for long-running automation tasks like content pipelines, research flows, and multi-stage data processing.

## What is a workflow?

A workflow is a named, ordered sequence of steps. Each step references an agent ID and optional configuration. When you execute a workflow, Agent Manager runs each step in order, feeding the output of one step as the input to the next. The state of every run is persisted to the database, so workflows survive restarts and can be resumed after a human approval pause.

<CardGroup cols={3}>
  <Card title="Content pipelines" icon="newspaper">
    Research a topic with `web_agent`, summarize with `procurator_assistant`, then draft a post.
  </Card>

  <Card title="Research flows" icon="magnifying-glass">
    Gather data across multiple sources, analyze findings, and produce a structured report.
  </Card>

  <Card title="Data processing" icon="database">
    Extract, transform, and validate data across agents with different tool sets.
  </Card>
</CardGroup>

## Creating a workflow

```bash theme={null}
POST /api/v1/workflows
```

**Request body (`WorkflowDTO`):**

<ParamField body="name" type="string" required>
  A human-readable name for the workflow.
</ParamField>

<ParamField body="description" type="string">
  Optional description of what the workflow does.
</ParamField>

**Example:**

```json theme={null}
{
  "name": "Tech News Briefing",
  "description": "Searches for tech news, summarizes it, and drafts a newsletter section."
}
```

**Response** — the created workflow with its generated ID:

```json theme={null}
{
  "id": "wf-3a7bc9",
  "name": "Tech News Briefing",
  "description": "Searches for tech news, summarizes it, and drafts a newsletter section."
}
```

## Adding steps

After creating a workflow, add steps to define what each agent should do. Steps execute in the order they are added (by `stepOrder`).

```bash theme={null}
POST /api/v1/workflows/{id}/steps
```

**Request body (`WorkflowStepDTO`):**

<ParamField body="agentId" type="string" required>
  The ID of the agent to invoke for this step.
</ParamField>

<ParamField body="action" type="string" required>
  The prompt or instruction sent to the agent for this step.
</ParamField>

<ParamField body="stepOrder" type="number">
  The position of this step in the sequence, starting from 1. Steps execute in ascending order.
</ParamField>

**Example — three-step content pipeline:**

<Steps>
  <Step title="Step 1: Search">
    ```json theme={null}
    {
      "agentId": "web_agent",
      "action": "Search for the latest news about artificial intelligence in healthcare",
      "stepOrder": 1
    }
    ```
  </Step>

  <Step title="Step 2: Summarize">
    ```json theme={null}
    {
      "agentId": "procurator_assistant",
      "action": "Summarize the search results into 3 bullet points",
      "stepOrder": 2
    }
    ```
  </Step>

  <Step title="Step 3: Draft">
    ```json theme={null}
    {
      "agentId": "procurator_assistant",
      "action": "Turn these bullet points into a 2-paragraph newsletter section",
      "stepOrder": 3
    }
    ```
  </Step>
</Steps>

## Executing a workflow

Trigger an asynchronous run of the workflow:

```bash theme={null}
POST /api/v1/workflows/{id}/run
```

**Request body:**

<ParamField body="input" type="string" required>
  The initial input passed to the first step.
</ParamField>

<ParamField body="sessionId" type="string">
  Optional session ID for context continuity. A new session is created if omitted.
</ParamField>

**Example:**

```json theme={null}
{
  "input": "artificial intelligence in healthcare 2025",
  "sessionId": "session-news-001"
}
```

**Response** — returned immediately with `202 Accepted`:

```json theme={null}
{
  "jobId": "job-f9a44e",
  "workflowId": "wf-3a7bc9",
  "sessionId": "session-news-001"
}
```

<Note>
  The workflow runs asynchronously. The `jobId` in the response is an internal queue job identifier. Use the workflow runs endpoint (below) to track execution progress by `workflowId`.
</Note>

## Checking run status

List all historical runs for a workflow, newest first:

```bash theme={null}
GET /api/v1/workflows/{workflowId}/runs
```

Supports pagination via `?page=0&size=20`.

**Run response fields:**

<ResponseField name="id" type="string">
  Unique identifier for this workflow run.
</ResponseField>

<ResponseField name="workflowId" type="string">
  ID of the parent workflow.
</ResponseField>

<ResponseField name="sessionId" type="string">
  The session used for this run.
</ResponseField>

<ResponseField name="status" type="string">
  Current run status: `RUNNING`, `COMPLETED`, `FAILED`, or `PAUSED`.
</ResponseField>

<ResponseField name="currentStepOrder" type="number">
  The step number currently being executed (or last executed if the run is paused or complete).
</ResponseField>

<ResponseField name="durationMs" type="number">
  Total elapsed time in milliseconds (computed from `createdAt` to `updatedAt`).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the run was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the last status change.
</ResponseField>

**Example response:**

```json theme={null}
{
  "content": [
    {
      "id": "wr-55cd12",
      "workflowId": "wf-3a7bc9",
      "sessionId": "session-news-001",
      "status": "COMPLETED",
      "currentStepOrder": 3,
      "durationMs": 14320,
      "createdAt": "2026-05-06T10:00:00Z",
      "updatedAt": "2026-05-06T10:00:14Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1
}
```

## Resuming a paused workflow

If a step involves an agent tool that requires human approval, the workflow pauses at that step and the run enters `PAUSED` status. Resume it with the approved output:

```bash theme={null}
POST /api/v1/workflows/runs/{runId}/resume
```

**Request body:**

<ParamField body="output" type="string" required>
  The human-approved content to inject as the output of the paused step. This value is passed as input to the next step in the sequence.
</ParamField>

**Example:**

```json theme={null}
{
  "output": "Approved summary: AI is transforming diagnostics and drug discovery."
}
```

**Response** — returned immediately with `202 Accepted`:

```json theme={null}
{
  "jobId": "job-cc8812",
  "runId": "wr-55cd12"
}
```

<Warning>
  A paused workflow run does not time out automatically. Ensure your application monitors for `PAUSED` runs and provides a mechanism for operators to review and resume them.
</Warning>

## Cloning a workflow

Create an independent copy of an existing workflow with all its steps:

```bash theme={null}
POST /api/v1/workflows/{id}/clone
```

No request body is required. The cloned workflow is created with the suffix ` (Copy)` appended to its name and a new unique ID.

**Example response:**

```json theme={null}
{
  "id": "wf-7d1ee2",
  "name": "Tech News Briefing (Copy)",
  "description": "Searches for tech news, summarizes it, and drafts a newsletter section."
}
```

<Tip>
  Use cloning to create environment-specific variants of a workflow (e.g., staging vs. production) without rebuilding steps from scratch.
</Tip>

## Workflow management endpoints

| Method   | Endpoint                                | Description                          |
| -------- | --------------------------------------- | ------------------------------------ |
| `GET`    | `/api/v1/workflows`                     | List all workflows (paginated).      |
| `GET`    | `/api/v1/workflows/{id}`                | Get workflow by ID.                  |
| `POST`   | `/api/v1/workflows`                     | Create a new workflow.               |
| `PATCH`  | `/api/v1/workflows/{id}`                | Update workflow name or description. |
| `DELETE` | `/api/v1/workflows/{id}`                | Delete a workflow and its steps.     |
| `GET`    | `/api/v1/workflows/{id}/steps`          | List steps for a workflow.           |
| `POST`   | `/api/v1/workflows/{id}/steps`          | Add a step to a workflow.            |
| `DELETE` | `/api/v1/workflows/{id}/steps/{stepId}` | Remove a step.                       |
| `POST`   | `/api/v1/workflows/{id}/clone`          | Clone a workflow with all its steps. |
| `POST`   | `/api/v1/workflows/{id}/run`            | Execute a workflow asynchronously.   |
| `GET`    | `/api/v1/workflows/{workflowId}/runs`   | List run history for a workflow.     |
| `POST`   | `/api/v1/workflows/runs/{runId}/resume` | Resume a paused workflow run.        |