Skip to main content
POST
/
api
/
v2
/
sessions
/
{id}
/
tool_results
Send tool results
curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/tool_results \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "<string>",
  "tool_req": {},
  "error": "<string>",
  "origin": "<string>",
  "type": "<string>",
  "results": [
    {}
  ]
}
'
Sends results for pending custom tool calls. When the agent calls a custom tool, the session waits on awaiting_tool_results; posting a result for every pending call resumes the run. The SDK run helpers call this endpoint for you. Returns 202 Accepted. The result is delivered asynchronously: the agent resumes once every pending call has one.

​
Path parameters

​
id
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); a batch wraps a list of them. Each call echoes back the pending tool_req from pending_tool_calls ({ tool_name, args, id }), not just its id.

​
Tool result (success)

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

​
Tool error (failure)

​
kind
string
required
Must be "error_event".
​
error
string
required
Error text shown to the model.
​
origin
string
required
Component that produced the error, e.g. "custom_tools".
​
tool_req
object
required
The pending tool call this answers, echoed back from pending_tool_calls.

​
Batch

​
type
string
required
Must be "batch".
​
results
array
required
Array of tool_result and/or error_event objects.

​
Examples

​
Send a single result

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_results \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "tool_result",
    "tool_req": { "tool_name": "lookup_order", "args": { "order_id": "A1" }, "id": "call_1" },
    "result": "shipped"
  }'

​
Send a batch of results

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_results \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batch",
    "results": [
      {"kind": "tool_result", "tool_req": {"tool_name": "lookup_order", "args": {}, "id": "call_1"}, "result": "shipped"},
      {"kind": "error_event", "error": "Order not found", "origin": "custom_tools", "tool_req": {"tool_name": "lookup_order", "args": {}, "id": "call_2"}}
    ]
  }'

​
Errors

StatusCause
404Session not found, or you don’t have access.
409The session already finished.
422Unknown tool_req.id, or invalid result format.