Executions & Streaming
How agent and flow runs are triggered, tracked, and streamed in real time.
Both agents and flows are run through the same Consumer API call shape — the
API doesn't distinguish between them beyond the resource in the path. Every run
is recorded as an execution with its own id.
Running an execution
POST /v1/agents/{agent_id}/execute
POST /v1/flows/{flow_id}/execute
{
"input": { "message": "Hello!" },
"session_id": "<optional>",
"stream": true,
"version": 3,
"attachment_ids": []
}stream: true(the default) makes the response the live event stream described below. The response headersX-Execution-IdandX-Session-Idname the run and its session before the first event, so you can cancel the run or continue the session without waiting fordone.stream: falsewaits for the run to finish and returns one JSON object:execution_id,session_id,status,output,reasoning,usage(input_tokens,output_tokens,estimated_cost_usd),sourcesanderror(nullwhen the run completed).- Background tasks for flows:
POST /v1/flows/{flow_id}/tasksanswers202with atask_id; read the result withGET /v1/tasks/{task_id}. session_id— omit it to start a new session; pass the one you got back to continue it. A session that does not exist, or belongs to another project, is a404.versionruns a saved version of the flow or agent instead of the current one (see Flows).attachment_idssends files uploaded beforehand (see Files & Attachments).
Past runs are listed with GET /v1/agents/{agent_id}/executions and
GET /v1/flows/{flow_id}/executions, and one run is read with GET /v1/executions/{id}.
An agent reads the user's message only from input.message: a non-empty string of at
most 100,000 characters. Text under any other key (input, text, prompt, ...) is not
read, and a missing, empty, null or non-string message is refused with 422
(message_required, invalid_message, message_too_long) before anything runs and
before any token is billed. An agent with no LLM provider is refused the same way
(422 no_llm_provider). The same rules apply to every way of running an agent, including the MCP execute_agent tool.
The flow's Input step makes the user's message available as input.message. A request that sends it
as input or user_input instead is accepted and read the same way.
Streaming over SSE
With stream: true the execute call itself answers with a text/event-stream connection — there is no
separate stream endpoint to open. Event types:
Event type | Emitted by | Meaning |
|---|---|---|
token | agent + flow | An incremental chunk of the model's response |
reasoning | agent + flow | An incremental chunk of the model's extended-thinking/reasoning text (opt-in, see below) |
step | agent only | An inference step (phase: "thinking", "guardrail" when a guardrail blocked the request or changed the response, with action and guardrails naming it, "groundedness" for the evidence-based check, etc.) — see below |
tool_call | agent only | The model is invoking a tool (name + input) |
observation | agent only | The result returned from a tool call |
summary | agent only | The agent's Layer 1 running summary was updated this turn (see below) |
sources | agent + flow | The knowledge-base passages the answer was built from (see Sources). Always sent (an empty list when nothing was retrieved), after the last token and before summary/done |
flow_step | flow only | One flow node started/finished — carries node_id, its status, and the current uo_data envelope |
done | agent + flow | The execution finished; carries the same sources list. Always the last event of a successful run: an agent's sources and summary events come before it, so a client may close the connection on done |
error | agent + flow | The execution failed; detail explains why |
cancelled | agent + flow | The execution was cancelled (see Cancelling an execution). Always the last event of a cancelled run; no done follows. Whatever was produced before the cancel was already streamed |
A flow run traces its progress only through flow_step events: a Tool/MCP Tool
node inside a flow is reported as a flow_step, not as a tool_call/observation
pair. Those two events belong to agent executions.
Each flow_step also carries duration_ms, how long that node took to run (milliseconds, backend-measured), so a slow turn can be traced to the node responsible. An Agent step adds ttft_ms (node start until its first answer token; null when it produced none, e.g. it only asked for a tool), llm_ms (model time) and tool_ms (time in tools the agent ran itself, via its own MCP servers). Flow Tool nodes are separate steps with their own duration_ms. The public Web Widget stream never forwards these fields.
The LLM flow node has a stream config toggle (default true) controlling whether its
output arrives as incremental token events or as a single chunk once the full response is
ready; the Agent flow node always streams incrementally. Nodes whose emit_to_output
is turned off are silenced for token/reasoning — their text never reaches the caller —
but their flow_step trace is still emitted, so the run stays fully observable.
Sources
When an agent (or a flow's RAG / Agent step) answers from a knowledge base, the run reports the passages it used. Every surface that returns a result carries the field — it is always present, an empty list when nothing was retrieved:
- the
sourcesanddonestream events (above); GET /v1/executions/{id}and the execution lists (GET /v1/agents/{id}/executions,GET /v1/flows/{id}/executions);POST /v1/agents/{id}/executeandPOST /v1/flows/{id}/executewithstream: false,GET /v1/tasks/{id}, and the MCPexecute_agent/execute_flowtools.
"sources": [
{
"index": 1,
"kind": "chunk",
"document_id": "…", "document_name": "emergency-policy.pdf",
"chunk_id": "…", "kb_id": "…", "kb_name": "Handbook",
"similarity": 0.87,
"snippet": "Emergency line: 0850 000 1122. …"
}
]indexis the number of the[n]citation marker in the answer text:[1]in the answer is the source withindex: 1. A marker that points at no listed source is removed from the text. When an agent searches several times in one run (on-demand retrieval), numbering continues across the searches, so a number never means two passages.kindischunkfor a document passage,entityorcommunityfor a graph knowledge base (theirdocument_nameis the entity name or the knowledge base name).snippetis the start of the passage, trimmed to 300 characters. With the agent's PII redaction or data leakage guardrails on, it is redacted the same way the answer is.- Document names are resolved only inside the knowledge bases the passage came from.
- Public surfaces (Web Widget, flow share link) receive
index,kind,document_name,kb_name,similarityandsnippet— never document, chunk or knowledge-base ids. - In a flow, the RAG step and the Agent step (with "Use Agent Knowledge") output
sources; the run's list merges them in the order they ran, without repeating a passage, and renumbers the merged list.
Cancelling an execution
POST /v1/executions/{exec_id}/cancel
→ 200: { "exec_id": "...", "status": "cancelled" }Works for agent and flow runs, whether they are streamed, run with stream: false, or started as a
background task (POST /v1/flows/{id}/tasks). The execution id comes from the X-Execution-Id header of a
stream, the stream: false response (execution_id), the task creation response, or the execution lists. The run is stopped for real: the model call or tool call
in flight is aborted, so nothing keeps running (or billing) behind a stopped run. An open event stream
ends with a cancelled event.
- Idempotent. Cancelling a run that is already
cancelledis a200with the same body. A run that already finished (completedorfailed) answers409with{"detail": {"code": "execution_finished", ...}}. - What is kept. The execution ends with
status: "cancelled"; the output produced so far, the step trace and the token usage of the model calls that had completed stay on the record. A model call that was cut off mid-way is not counted, because the provider only reports usage at the end of a call. - Who may cancel. Stopping a run needs the right to start it: the
agents:execute/flows:executescope matching what ran. An execution of another project is a404. A503(cancel_unavailable) means the request could not be delivered; nothing changed, try again. - Timing. The runner notices the cancel within about a second, also when it runs in another process
(a background worker). Cancelling a run that has not started yet makes it start as cancelled, and a
cancelled execution can no longer be streamed (
409). - Closing the connection. A client that closes the SSE connection before
donealso stops the run: the server tears it down and records it ascancelled(the output produced so far is kept). A client that closes ondoneorerroris not affected. A run started withstream: falseor as a background task has no connection to close, so the cancel endpoint is the way to stop it.
Multi-turn conversations
Agent conversation state is client-driven, not persisted server-side: each
execute call is stateless from the API's perspective, so the
caller resends the conversation on every turn via input.history (a flat
list of {"role": "human"|"assistant", "content": "<text>"}, oldest first).
A history that is not such a list, or an entry with another role or a
non-string content, is refused with 422 invalid_history; input.summary
(below) must be {"summary": "<text>", "token_count": <int>} or the call is
refused with 422 invalid_summary.
An Agent step inside a flow reads input.history (and input.summary,
input.recalled_memories) from the run input too, but it also has its own session memory
(on by default, see Flows): it remembers the user messages, the tool calls and
tool results, and the answers of earlier turns of the same session, including turns that ended in a
tool step without ever returning to the agent. While that memory holds anything, input.history is
ignored (the two are not merged). Turn the memory off on the step to carry the conversation yourself
with input.history. A plain agent run (no flow) has no such memory: sending the
same session_id again does not give it one.
Once a conversation grows past the agent's max_tokens_before_summary
(Layer 1 running summary, see Context Management),
the backend compacts older messages into a rolling summary and emits it as a
summary event ({"type": "summary", "content": {"summary": "...", "token_count": N}}).
token_count is the size of the recent messages kept verbatim next to the summary, not the
length of the summary text (that one is capped by the agent's max_summary_tokens).
Callers should capture the latest summary event and resend it as
input.summary on the next call, alongside only the most recent few
messages in input.history — otherwise the backend has no persisted
summary to build on and recomputes one from scratch from the full raw
history every time the threshold is crossed again, which works but wastes
an extra LLM call per turn.
Inference steps
UnderOcean surfaces the agent's internal thought → action → observation
loop directly to the UI as step events, rather than only showing the final
answer. This is core to the platform's "visibility into agent reasoning"
principle — users can watch an agent decide to call a tool, see the tool's
output, and see how that changes its next step, as it happens.
Reasoning / extended thinking (opt-in)
Agents, and the Agent/LLM flow nodes, support an optional reasoning_effort
setting (none | low | medium | high, default none). An Agent flow node
whose setting is left unset uses the agent's own value; a value set on the node
overrides it. When enabled on
a model that supports it (e.g. Anthropic extended thinking, OpenAI/DeepSeek/
Grok reasoning models), the model's reasoning/thinking text is
streamed as reasoning events alongside token events, and persisted to the
execution's reasoning field once the run completes. Models that don't
support reasoning silently ignore the setting (no error).
Structured output (JSON Schema)
An agent can require its answers to follow a JSON Schema: set response_format on the agent
({"type": "json_schema", "json_schema": {"name": "answer", "schema": {...}, "strict": true}}), or
send it with one run to override the agent's own for that run (POST /v1/agents/{id}/execute, or
POST /api/v1/executions for an agent run). {"type": "text"} on a run switches the agent's format off.
Flows cannot take it per request; set it on the Agent or LLM step instead (an Agent step uses its agent's
format unless the step sets its own).
- The format is handed to the provider unchanged and is sent on every model call of the run, tool rounds included. The platform never edits or repairs the answer.
- The answer still streams as
tokenevents: join them, then parse oncedonearrives. A run cut off bymax_tokensleaves incomplete JSON (the run reports the truncation). - The default "answer in Markdown" instruction is not added when a schema is set.
- Providers differ in what they enforce; a provider that does not support structured output answers with an error instead of free text. Strict mode follows the OpenAI rules.
- Answer post-processing still applies: numbered knowledge-base citations (
[n]) and the output guardrails (for example PII redaction) can change text inside the JSON, so combine them with a schema deliberately.
Output normalization
The text of every answer is normalized once, in the same way on every channel (agent
API streamed or not, flow LLM/Agent steps, widget, share links, gates, MCP tools, the in-app
assistant): token events carry the normalized text and so do the stored output and the
synchronous response, so a streamed and a non-streamed run of the same model reply are identical.
- Model control tokens never reach the user. For models that speak the
OpenAI Harmony format, the
analysischannel (the model's chain of thought) is removed from the answer — it is delivered asreasoningevents when reasoning is on and dropped otherwise — thefinalchannel and tool-lesscommentarypreambles are the answer, and stray or truncated tokens such as<|channel|>are deleted. - Invisible characters. Narrow and no-break spaces (U+202F, U+00A0, U+2007, U+2009, U+200A, U+3000 …) become a plain space; zero-width characters (U+200B, U+2060, U+FEFF) are removed, and text is Unicode NFC. Zero-width joiners inside emoji sequences and in Arabic/Indic scripts are kept.
- Citations. An agent that answers from an Evidence Based knowledge base cites with
[n]. Full-width【1】/[1]and【1†L1-L2】become[1], and a[n]that points past the numbered sources is removed. - Code blocks and inline code, tool-call arguments and JSON/structured output are never changed.
A turn that leaves no answer text after this — for example the model produced only control tokens
because it hit max_tokens — ends with an error event (and a failed run, or a failed LLM/Agent
step) instead of completing with an empty reply.
Checkpointing
Execution state is checkpointed as it runs, which enables:
- Resuming long-running flows after a pause (human-in-the-loop steps)
- Recovering execution state after a transient failure