Skip to main content
POST
Send tool results
Sends results for pending custom tool calls. When the agent calls a custom tool, the session waits on awaiting_tool_results until you post a result for every pending call. The SDK run helpers call this endpoint for you. Results are relayed to the agent as-is: the API doesn’t check tool_req.id against the pending calls, so echo the request faithfully. Settling a call on a paused session leaves it paused, so resume it separately. Returns 202 Accepted. The agent resumes once every pending call has a result.

Path parameters

string
required
The session ID.

Request body

Send either a single settled call or a batch. A single call is a tool_result on success or an error_event on failure, discriminated by kind. Each call echoes back the full pending tool_req from pending_tool_calls ({ tool_name, args, id }), not only its id.

Tool result (success)

string
required
"tool_result".
object
required
The pending tool call this answers, echoed back from pending_tool_calls: { tool_name, args, id }.
JSON-serializable tool output, shown to the model.

Tool error (failure)

string
required
"error_event".
string
required
Error text shown to the model.
string
required
Component that produced the error, e.g. "custom_tools".
object
The pending tool call this answers, echoed back from pending_tool_calls. Optional in the schema, but send it so the agent can match the error to its call.

Batch

string
required
"batch".
object[]
required
At least one tool_result or error_event object.

Examples

Send a single result

Send a batch of results

Errors