# POST /agent-ops/dispatch

**Resource:** [Agent Ops](./agent-ops.md)  
**MCP tool:** `dispatch_agent_run`  
**Scopes:** `agent-ops:write`  
**Write operation:** yes

Dispatch a workflow-agent run on the Cloudflare engine and return its run id. The agent runs as durable, cheap-model steps (routed per role); poll get_agent_run for the per-step trace + cost. mode:"test" (default) runs in Demo Company only; mode:"live" runs in the current workspace. Steps, tool_catalog, and routing fall back to the agent's saved configuration when omitted; omit everything to fire a one-step engine health check.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `agent_id` | body | string | yes | agent_registry id to run. |
| `mode` | body | string | no | test = Demo Company only (default); live = current workspace. |
| `input` | body | object | no | Run input, threaded into the first step. |
| `steps` | body | array | no | Optional StepSpec[]; falls back to the agent's configuration.steps, else a one-step health check. |
| `task_type` | body | string | no | Label shown as the Sessions row Task. |
| `tool_catalog` | body | array | no | Optional tool definitions for tool_loop / gather steps (falls back to configuration.tool_catalog). |
| `routing` | body | object | no | Optional role->model routing override { byRole, byStepId } (falls back to configuration.routing). |
| `require_approval` | body | boolean | no | Optional. Set true to route this write into the approval queue for human review instead of executing it immediately (returns 202 + an approval_id). Works even when your key/token has permission to execute directly. |

## Request example

```bash
curl -X POST   "https://api.trustpager.com/functions/v1/api/v1/agent-ops/dispatch"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"agent_id":"...","mode":"...","input":"..."}'
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`