Send tool results

Send results for the agent’s pending custom tool calls so the session continues.

POST /api/v2/sessions/{id}/tool_results

Python

from hai_agents import Client, ToolRequest, ToolResultEvent

client = Client()

client.sessions.send_session_tool_results(
    session_id,
    request=ToolResultEvent(
        tool_req=ToolRequest(tool_name="lookup_order", args={"order_id": "A1"}, id="call_1"),
        result="shipped",
    ),
)

Behavior

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.

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. Each call echoes back the full pending tool_req from pending_tool_calls ({ tool_name, args, id }), not only its ID.

Tool result (success)

kind · string · required

"tool_result".

tool_req · object · required

The pending tool call this answers, echoed back from pending_tool_calls.

tool_name · string · required

args · object

id · string

result · any

JSON-serializable tool output, shown to the model.

Tool error (failure)

kind · string · required

"error_event".

error · string · required

Error text shown to the model.

origin · string · required

Component that produced the error, for example "custom_tools".

tool_req · 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

type · string · required

"batch".

results · object[] · required

At least one tool_result or error_event object.

Response

202 Accepted. The agent resumes once every pending call has a result.

Python

from hai_agents import Client, ToolRequest, ToolResultEvent

client = Client()

client.sessions.send_session_tool_results(
    session_id,
    request=ToolResultEvent(
        tool_req=ToolRequest(tool_name="lookup_order", args={"order_id": "A1"}, id="call_1"),
        result="shipped",
    ),
)

More examples

Send a batch of results

Python

from hai_agents import Client, ErrorEvent, ToolRequest, ToolResultBatch, ToolResultEvent

client = Client()

client.sessions.send_session_tool_results(
    session_id,
    request=ToolResultBatch(
        results=[
            ToolResultEvent(
                tool_req=ToolRequest(tool_name="lookup_order", args={}, id="call_1"),
                result="shipped",
            ),
            ErrorEvent(
                error="Order not found",
                origin="custom_tools",
                tool_req=ToolRequest(tool_name="lookup_order", args={}, id="call_2"),
            ),
        ],
    ),
)

Errors

Status	Cause
404	Not found, or not in your organization.
409	The session already finished. Its pending calls were resolved when it ended.
422	Malformed request body.