Skip to main content
POST
Run Conversation Turn (Stream)
Send one message and receive the turn as Server-Sent Events. A connected event arrives at once, then task_created with the conversation record (its id is the conversation_id, its input your message), turn_started with the turn number, the reply text as chunk events as the agent writes it, each skill call as tool_call_request and tool_call_result, and finally turn_finished with the full reply in result. A task_finished event may arrive just before or after turn_finished; settle on turn_finished. To continue the conversation, pass id = your conversation_id; omit it to start a new one. If the connection drops, reconnect with the Last-Event-ID header set to the last event id you received and the stream resumes after it. The sub_tasks query parameter sets how sub-tasks the agent creates for other agents run inside this turn: sync inline, async in the background, auto per the agent’s own choice. The setting sticks to the conversation until you change it. See the Conversations overview for the full event order and the conversation record.

Authorizations

x-api-key
string
header
required

API Key for authentication

Path Parameters

agent_id
string
required

Query Parameters

version
string | null

Agent version to run.

sub_tasks
enum<string> | null

How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed.

Available options:
sync,
async,
auto

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