> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send tool results

> Answer the agent's pending custom tool calls.

Sends results for pending [custom tool](/computer-use-agents/custom-tools) calls. When the agent calls a custom tool, the session waits on `awaiting_tool_results`; posting a result for every pending call lets the run continue. 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; [resume](/computer-use-agents/sessions/resume) it separately.

**Returns** `202 Accepted`. The result is delivered asynchronously: the agent resumes once every pending call has one.

***

## Path parameters

<ParamField path="id" type="string" required>
  The session ID.
</ParamField>

***

## 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`, and a batch wraps a list of them. Each call echoes back the full pending `tool_req` from [`pending_tool_calls`](/computer-use-agents/custom-tools) (`{ tool_name, args, id }`) rather than only its id.

### Tool result (success)

<ParamField body="kind" type="string" required>
  Must be `"tool_result"`.
</ParamField>

<ParamField body="tool_req" type="object" required>
  The pending tool call this answers, echoed back from `pending_tool_calls`: `{ tool_name, args, id }`.
</ParamField>

<ParamField body="result">
  JSON-serializable tool output, shown to the model.
</ParamField>

### Tool error (failure)

<ParamField body="kind" type="string" required>
  Must be `"error_event"`.
</ParamField>

<ParamField body="error" type="string" required>
  Error text shown to the model.
</ParamField>

<ParamField body="origin" type="string" required>
  Component that produced the error, e.g. `"custom_tools"`.
</ParamField>

<ParamField body="tool_req" type="object" required>
  The pending tool call this answers, echoed back from `pending_tool_calls`.
</ParamField>

### Batch

<ParamField body="type" type="string" required>
  Must be `"batch"`.
</ParamField>

<ParamField body="results" type="array" required>
  Array of `tool_result` and/or `error_event` objects.
</ParamField>

***

## Examples

### Send a single result

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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",
      ),
  )
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  await client.sessions.sendSessionToolResults({
    id: sessionId,
    body: {
      kind: "tool_result",
      toolReq: { toolName: "lookup_order", args: { order_id: "A1" }, id: "call_1" },
      result: "shipped",
    },
  });
  ```
</CodeGroup>

### Send a batch of results

<CodeGroup>
  ```bash cURL theme={null}
  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"}}
      ]
    }'
  ```

  ```python Python theme={null}
  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"),
              ),
          ],
      ),
  )
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  await client.sessions.sendSessionToolResults({
    id: sessionId,
    body: {
      type: "batch",
      results: [
        {
          kind: "tool_result",
          toolReq: { toolName: "lookup_order", args: {}, id: "call_1" },
          result: "shipped",
        },
        {
          kind: "error_event",
          error: "Order not found",
          origin: "custom_tools",
          toolReq: { toolName: "lookup_order", args: {}, id: "call_2" },
        },
      ],
    },
  });
  ```
</CodeGroup>

***

## Errors

| Status | Cause                                                                     |
| ------ | ------------------------------------------------------------------------- |
| `404`  | Session not found, or you don't have access.                              |
| `409`  | The session already finished; its pending calls were resolved at run end. |
| `422`  | Malformed request body.                                                   |