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

# Flow Agent Tools

> Operate and publish flow agents over MCP at the intent level — the Flow Designer graph is never exposed to an agent key.

Flow agents are Sapot Chat's AI conversation agents. Over MCP you operate them at the **intent level** — list them, inspect their live settings, attach inboxes, and publish. The Flow Designer graph (`graph_data`, `graph_snapshots`, `designer_history`) is stripped server-side before any response reaches an agent key, and there is no build-from-scratch, export, import, or restore tool. Design happens in the dashboard's Flow Designer; you drive the *outcome* here.

<Info>
  Two scopes gate this domain: **`flows:manage`** for the read + wiring tools, and **`flows:publish`** for going live. A key granted `flows:manage` but not `flows:publish` can attach inboxes but cannot flip an agent live. See [Authentication & Scopes](/ai-agents/authentication) and [Safety & Boundaries](/ai-agents/safety-boundaries).
</Info>

## The intent-level view

Every flow-agent tool returns the same agent shape — never the graph:

| Field                    | Meaning                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `id`                     | Flow agent id                                                                      |
| `name`, `description`    | Human-readable identity                                                            |
| `status`                 | `draft` or `published`                                                             |
| `conversational_mode`    | Whether the agent keeps answering after the flow completes (park mode) vs restarts |
| `reply_delay_seconds`    | Per-agent send delay before each reply                                             |
| `handoff_pause_duration` | How long the agent stays paused after a hand-off to a human                        |
| `inbox_ids`              | The inboxes this agent is connected to                                             |
| `inbox_settings`         | Per-inbox runtime rules (see `set_flow_agent_inboxes`)                             |

<Warning>
  You will never receive the flow's internal graph. Don't ask for or expect raw graph JSON — it's IP, stripped at the API boundary. To change how an agent behaves node-by-node, open the Flow Designer in the dashboard.
</Warning>

## flows:manage

### list\_flow\_agents

List the account's flow agents. Takes no arguments.

Returns a list of agents in the intent-level shape above. The underlying flow graph is intentionally not included.

### get\_flow\_agent

Fetch one flow agent by id (intent-level view, no graph).

| Argument        | Type | Required | Description     |
| --------------- | ---- | -------- | --------------- |
| `flow_agent_id` | int  | yes      | The agent's id. |

Returns the same fields as `list_flow_agents`, for one agent.

### get\_flow\_agent\_metrics

Runtime metrics across the account's flow agents — conversations handled, hand-offs, and so on.

| Argument | Type | Required | Description                                                         |
| -------- | ---- | -------- | ------------------------------------------------------------------- |
| `days`   | int  | no       | Look-back window in days. Defaults to the server's standard window. |

Returns the aggregated metrics object.

### set\_flow\_agent\_inboxes

Set which inboxes a flow agent is connected to. **This REPLACES the current set** — it is not additive.

| Argument         | Type   | Required | Description                                                                                                           |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `flow_agent_id`  | int    | yes      | The agent's id.                                                                                                       |
| `inbox_ids`      | int\[] | yes      | The complete list of inbox ids the agent should handle. Replaces current membership. Pass `[]` to detach all inboxes. |
| `inbox_settings` | object | no       | Per-inbox rules keyed by inbox id **as a string** (see below).                                                        |

Returns the updated agent (intent-level view).

<Warning>
  `inbox_ids` is the full desired set, and an inbox belongs to exactly one flow agent. Adding an inbox here **moves it off whatever other agent it was on**. To add one inbox without dropping the rest, read the current `inbox_ids` first and send the union. Sending `[]` detaches every inbox from this agent.
</Warning>

**Per-inbox `inbox_settings`.** Keyed by inbox id as a string, each value carries the runtime rules for that inbox:

| Setting                  | Type      | Effect                                                                 |
| ------------------------ | --------- | ---------------------------------------------------------------------- |
| `ignore_whatsapp_groups` | bool      | Skip WhatsApp group chats on this inbox.                               |
| `excluded_labels`        | string\[] | Don't let the agent act on conversations carrying any of these labels. |
| `pause_on_human_reply`   | bool      | Pause the agent when a human agent replies.                            |

```json theme={null}
{
  "12": {
    "ignore_whatsapp_groups": true,
    "excluded_labels": ["vip"],
    "pause_on_human_reply": true
  }
}
```

## flows:publish

### publish\_flow\_agent

Publish a flow agent so it goes live on its connected inboxes.

| Argument        | Type | Required | Description     |
| --------------- | ---- | -------- | --------------- |
| `flow_agent_id` | int  | yes      | The agent's id. |

The graph is **validated server-side first**. If it's invalid, the call fails and the error is **opaque** — it tells you the graph didn't pass, not which node is broken (the graph itself stays private). On success, returns the published agent (intent-level view).

<Tip>
  If publish reports the graph is invalid, there's nothing to fix from the MCP side — open the agent in the Flow Designer, resolve the validation errors there, then call `publish_flow_agent` again.
</Tip>

## Typical flow

<Steps>
  <Step title="Find the agent">
    `list_flow_agents` → note the `id` and current `inbox_ids` / `status`.
  </Step>

  <Step title="Attach inboxes">
    `set_flow_agent_inboxes(flow_agent_id, inbox_ids=[…])` with the full desired inbox set, plus any per-inbox `inbox_settings`.
  </Step>

  <Step title="Go live">
    `publish_flow_agent(flow_agent_id)` (needs `flows:publish`). If it reports an invalid graph, fix it in the Flow Designer and retry.
  </Step>
</Steps>

## What's deliberately absent

There is **no** `create`, `export`, `import`, or `restore_snapshot` tool for flow agents. Building a graph is an intent-level path reserved for the dashboard's Flow Designer. This isn't a gap in the tool catalog — it's a locked product boundary. See [Safety & Boundaries](/ai-agents/safety-boundaries) for the full rationale, and the in-app Help Center for a no-code walkthrough of the Flow Designer.

## Connect

```bash theme={null}
claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"
```