Chats

get_chat

Get a chat’s current state — status, full message history, recorded outcomes, cost, and any pending human-input request. Poll this until status is no longer “running”.

The messages history holds only user/assistant text turns. Human input requests and the answers they got are NOT messages — they come back in hitl_requests (every request for the chat, with its response_text), while pending_hitl_request holds only the one still waiting. When the request offered ui (buttons/choice/text/info — the same shape request_human_input accepts), it’s included on both so you can see exactly what a human would be asked to pick from before calling respond_to_hitl.

When the agent recorded an outcome, its summary IS the answer, and the last assistant message carries it (tagged kind: "outcome_summary") even if the model’s own closing turn was empty — so messages alone is enough to read the result. outcomes remains the graded record.

stop_reason says why a chat is no longer moving: “cost_limit” (raise the agent’s per-chat budget and start again), “awaiting_input” (a human must answer), or “no_outcome” — the agent replied and stopped without calling goal_complete, so outcomes is empty and nothing was declared. It is idle, not running: stop polling and treat the result as unverified.

Pass include_trace=true to also get a trace array of the underlying events (tool calls + results with name/args/result preview), oldest first — useful to see why the agent did something or which tool failed.

Parameter	Type	Required	Description
chat_id	string	yes
include_trace	boolean	no
org	string	no

list_chats

List recent chats for an agent (by id or slug), newest first.

Paged: the response carries total, has_more and next_offset — pass next_offset back as offset to walk the rest.

Parameter	Type	Required	Description
agent	string	yes
limit	integer	no	Max rows to return (1–200).
offset	integer	no	Rows to skip — pass the previous response’s next_offset.
org	string	no

respond_to_hitl

Answer a pending human-input request (from a paused chat) and resume the agent. Use action (“approve”/“reject”, or one of the request’s ui buttons) for approvals and button choices, selection for one of the ui choice options, text for a free-text answer. At least one is required.

When the request declared buttons/choice in its ui (see get_chat’s pending_hitl_request.ui), action/selection must be one of the offered options — a value that isn’t gets rejected with the valid options listed. Requests with no such ui (plain approvals, free-text questions) accept anything.

Parameter	Type	Required	Description
action	string	no
org	string	no
request_id	string	yes
selection	string	no
text	string	no

send_message

Send a user message to an existing chat and dispatch the agent turn. A message to a paused chat resumes it. Runs asynchronously — poll get_chat for the result.

To attach files, first use create_upload_url to get presigned upload URLs, PUT your files to those URLs, then pass the returned upload_ids in attachment_upload_ids.

Parameter	Type	Required	Description
attachment_upload_ids	string[]	no
chat_id	string	yes
message	string	yes
org	string	no

start_chat

Start a new chat with an agent (by id or slug) and send the first message. Returns the chat_id; the turn runs asynchronously — poll get_chat for the result.

By default the chat runs the agent’s published (active) revision. To test an unpublished instruction without deploying it, pass use_draft=true (pins the agent’s current draft revision) OR revision_version=N (pins a specific past version). The pin holds for the chat’s whole life. The two options are mutually exclusive.

Pass sandbox_enabled=true to run the chat in a Cloud Workspace — an isolated Linux sandbox with a real filesystem + network that persists across the conversation. Enable it for substantial coding, data, or file-heavy work; it only ever adds capability on top of the agent’s own sandbox setting.

To attach files, first use create_upload_url to get presigned upload URLs, PUT your files to those URLs, then pass the returned upload_ids in attachment_upload_ids.

Parameter	Type	Required	Description
agent	string	yes
attachment_upload_ids	string[]	no
message	string	yes
org	string	no
revision_version	integer	no
sandbox_enabled	boolean	no
title	string	no
use_draft	boolean	no