Concepts

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 headers X-Execution-Id and X-Session-Id name the run and its session before the first event, so you can cancel the run or continue the session without waiting for done.
  • stream: false waits 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), sources and error (null when the run completed).
  • Background tasks for flows: POST /v1/flows/{flow_id}/tasks answers 202 with a task_id; read the result with GET /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 a 404.
  • version runs a saved version of the flow or agent instead of the current one (see Flows).
  • attachment_ids sends 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 typeEmitted byMeaning
tokenagent + flowAn incremental chunk of the model's response
reasoningagent + flowAn incremental chunk of the model's extended-thinking/reasoning text (opt-in, see below)
stepagent onlyAn 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_callagent onlyThe model is invoking a tool (name + input)
observationagent onlyThe result returned from a tool call
summaryagent onlyThe agent's Layer 1 running summary was updated this turn (see below)
sourcesagent + flowThe 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_stepflow onlyOne flow node started/finished — carries node_id, its status, and the current uo_data envelope
doneagent + flowThe 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
erroragent + flowThe execution failed; detail explains why
cancelledagent + flowThe 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 sources and done stream events (above);
  • GET /v1/executions/{id} and the execution lists (GET /v1/agents/{id}/executions, GET /v1/flows/{id}/executions);
  • POST /v1/agents/{id}/execute and POST /v1/flows/{id}/execute with stream: false, GET /v1/tasks/{id}, and the MCP execute_agent / execute_flow tools.
"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. …"
  }
]
  • index is the number of the [n] citation marker in the answer text: [1] in the answer is the source with index: 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.
  • kind is chunk for a document passage, entity or community for a graph knowledge base (their document_name is the entity name or the knowledge base name).
  • snippet is 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, similarity and snippet — 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 cancelled is a 200 with the same body. A run that already finished (completed or failed) answers 409 with {"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:execute scope matching what ran. An execution of another project is a 404. A 503 (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 done also stops the run: the server tears it down and records it as cancelled (the output produced so far is kept). A client that closes on done or error is not affected. A run started with stream: false or 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 token events: join them, then parse once done arrives. A run cut off by max_tokens leaves 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 analysis channel (the model's chain of thought) is removed from the answer — it is delivered as reasoning events when reasoning is on and dropped otherwise — the final channel and tool-less commentary preambles 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

On this page