Skip to main content
POST
Run an Agent as an external user, streaming AG-UI events (SSE)

Authorizations

Authorization
string
header
required

Developer Platform Project credential, minted via POST /api/v1/projects/{projectId}/credentials. Send as Authorization: Bearer <keyId>.<secret>. Optionally pair with the x-persona-external-user-id header to act on behalf of one of the Project's own external users. This credential is a server-side secret — see the Integration Guide.

Headers

x-agent-id
string
required
x-persona-external-user-id
string
required
x-thread-id
string

A Thread id from the Developer Thread CRUD API — resumes that conversation instead of the implicit deterministic one.

Body

application/json
messages
object[]
resume
object

Resume data for a Thread paused on a human-in-the-loop interrupt (e.g. an agent-management tool the Agent's interruptOn config requires confirming). Pass { type: "decision", decision: "continue" | "reject" } to approve/deny a pending tool call, or an object shaped for the specific clarification the interrupted run is waiting on.

Response

A text/event-stream SSE stream of AG-UI protocol events (the standard @ag-ui/core EventType values): RUN_STARTED once at the start of the run; TEXT_MESSAGE_CHUNK for streamed assistant text deltas; REASONING_MESSAGE_START/CONTENT/END for models that expose reasoning; TOOL_CALL_CHUNK/TOOL_CALL_RESULT for tool invocations and their results; STATE_SNAPSHOT for full-state updates; CUSTOM for Persona-specific side-channel events (e.g. subagent traces, MCP structured content); and RUN_FINISHED once at the end. Each event is a JSON object sent as one data: line per SSE convention.