Skip to main content
POST
Invoke Agent (Stream)
Invoke an agent with real-time streaming via Server-Sent Events (SSE). Events fire as the agent works, so you can render progress, chunks, tool activity, and the final result in an interactive UI.

Path Parameters

string
required
Agent ID (UUID)

Request Body

The request body is identical to Invoke Agent (Sync). Only input.text is required.
object
required
string
Task/thread ID for multi-turn conversations. Pass the id from a previous task response to continue the same conversation. Continued turns keep using that same ID.
boolean
default:"false"
When true, files in input.files are not injected into the LLM context window. See Invoke Sync: Processing Files.
string
default:"default"
default or harder. Controls reasoning depth.
string
Additional instructions appended to the system prompt for this invocation only.
string
Extra context appended to the agent’s system prompt for this invocation only. Unlike instructions_override (which adds behavioral instructions), this supplies supplementary facts or context the agent should consider for this run — e.g. relevant background data, the current state of an external system, or a user’s recent activity.
string
Natural-language description of desired output
string
Per-execution LLM provider override. See Invoke Sync: Per-Execution LLM Override.
string
Per-execution model override. See Invoke Sync: Per-Execution LLM Override.
string
default:"medium"
Per-execution reasoning-effort override (low | medium | high | xhigh). See Invoke Sync: Per-Execution LLM Override.

Query Parameters

string
Agent version to invoke. Defaults to latest deployed. Use "draft" to test undeployed changes.

Response Format

Returns Content-Type: text/event-stream. Each SSE line is prefixed with data: and contains a JSON object with this top-level shape:
For chunk events, data is a string fragment. For task lifecycle events, data is the task object snapshot at that moment.
If you continue a conversation by sending id: "<previous-task-id>", the stream keeps emitting that same task_id. Use Get Task for the latest turn state and Get Task Thread or Get Task Thread (Full) for the full message history.

Event Types

Events are emitted in this order during a typical invocation:
event
Fired immediately. Contains the task object with status: "pending". This is emitted for both brand-new threads and follow-up turns on an existing task/thread ID.
event
Fired when the task status changes, usually to executing. Contains the updated task object.
event
Agent’s internal reasoning step. Contains the thought process as a string.
event
Agent’s analysis step before tool selection.
event
Agent is calling a tool. Contains tool name, parameters, and reasoning.
event
Tool returned a result. Contains the output from the tool.
event
A piece of the agent’s final response. Accumulate these to build the full result.
event
Task is done. Contains the final task object with status, result, and finished_at.
event
A sub-agent was triggered (multi-agent workflows).
event
Deep planning step was updated (when deep_planning is enabled on the agent).
event
MCP connector requires authentication. Contains an auth URL the user must visit.

Basic Example

Use --no-buffer (or -N) for real-time output.

Real Event Stream

Here’s what the actual SSE output looks like from a live invocation:

Consuming the Stream (Node.js)

Consuming the Stream (Python)

Notes

  • Use curl --no-buffer or curl -N for real-time terminal output
  • The stream ends after the task_finished event — close the connection at that point
  • chunk events contain raw text fragments; concatenate them for the full response
  • tool_call_request and tool_call_result events let you show tool usage in your UI
  • think and analyze events show the agent’s reasoning (useful for debugging and transparency)
  • For multi-turn conversations, wait for task_finished before sending the next message with the same id
  • Reusing id continues the same task/thread; it does not mint a new top-level task ID for the follow-up turn
  • Get Task shows the latest turn state for that ID, while Get Task Thread and Get Task Thread (Full) show the accumulated conversation

See Also

Authorizations

x-api-key
string
header
required

API Key for authentication

Path Parameters

agent_id
string
required

Query Parameters

version
string | null

The agent/workflow version to invoke. default = latest

Body

application/json
input
AgentExecutionInput · object
required
id
string | null
payload_extension
Payload Extension · object | null
parent_execution_id
string | null
worker_id
string | null
source
string | null
output_format
enum<string> | null
Available options:
text,
markdown,
json,
voice
output_schema
Output Schema · object | null
run_locally
boolean | null
default:false
additional_context
string | null
instructions_override
string | null
test_run_node_id
string | null
expected_output
string | null
events_streaming
boolean | null
default:false
mcp_servers
Mcp Servers · object[] | null
triggering_agent_id
string | null
title
string | null
think_mode
enum<string> | null
default:default
Available options:
default,
harder
disable_attachment_injection
boolean | null
default:false
user_tokens
User Tokens · object | null
user_oidc_token
string | null
return_metrics
boolean | null
default:false
llm_model_provider
string | null

Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.

llm_model_name
string | null

Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.

llm_reasoning_effort
enum<string> | null

Per-execution override for reasoning effort on reasoning-capable models.

Available options:
low,
medium,
high,
xhigh
source_node_type
enum<string> | null

Surface that created this execution (mirrored to AgentExecutionHistory.source_node_type). Falls back to SourceNodeType.SDK at persist time when unset.

Available options:
workbench,
sdk,
task,
assistant,
webhook,
mcp,
a2a,
telegram,
slack,
email,
api
is_app
boolean | null
default:false
is_steering
boolean | null
default:false
sub_tasks_mode
enum<string> | null

Forces gateway sub-task dispatch: 'sync' runs all downstream sub-tasks inline, 'async' queues them all, 'auto' restores the computed per-sub-task decision.

Available options:
sync,
async,
auto

Response

Successful Response