Running & observability
These tools close the loop between designing an agent and seeing it work: run_agent triggers a real execution, and the remaining tools let you inspect what happened — the same data behind the Executions view in Flows.
Running an agent
run_agent — { agentId | agentSlug, message, target? }
Triggers a real, billable run of an agent — the same execution path the chat interface, playground, and external API all use. Resolve the agent by either agentId or agentSlug.
targetdefaults todraft— deliberately different from other run surfaces, so testing an agent you're actively revising withupdate_agent_specdoesn't accidentally re-run the old live version. Passtarget: "live"explicitly to run the promoted version instead.- The tool call returns as soon as it can meaningfully report a result: a completed answer, an awaiting_approval status if the agent paused on a permission check, or a running status with an execution id if the agent is still working past the tool's wait budget. A
runningresult is never aborted — pollget_workflow_executionorget_session_historywith the returned id to get the eventual outcome. - Only one
run_agentcall runs per agent at a time — a second call for the same agent while one is in flight returns analready_runningstatus instead of piling up concurrent runs.
This is a real run
run_agent consumes LLM tokens and executes any tools the agent has attached, subject to its
permission mode, exactly like a run started from the chat interface. It is not a dry run or
simulation.
Reading back results
| Tool | What it returns |
|---|---|
get_workflow_execution | Status, timing, and metadata for one execution, by execution id |
get_session_history | The full conversation history for a session — every message exchanged |
list_agent_conversations | A summary per conversation for a given agent — one row per distinct conversation |
list_conversation_executions | Every execution that belongs to one specific conversation |
Understanding what you see
get_runtime_semantics_guide — { topics?: [...] }
A reference for interpreting execution data: the ReAct execution model, transfer vs. delegation between sub-agents, the routing-event glossary, permission modes, and how memory persists across a session. Call it with no arguments for a compact index of topics, or pass specific topic keys for the full detail on just those.
Reading a multi-agent trace
If a run routes across several sub-agents and the trace isn't self-explanatory, call
get_runtime_semantics_guide with the routing_events_reference topic — it's a glossary for
every event type you'll see in get_workflow_execution's routing timeline.