Give an agent custom tools

The environment supplies the agent’s core tools. Custom tools are functions from your own code: the agent calls one mid-run, your process executes it, and the run continues with the result.

	Environment tools	Custom tools
Examples	Navigate, click, type, scroll	Query your database, call an internal API, look up a customer
Defined by	The environment	You, as a function
Runs	In the environment	In your process, via the SDK
Agent sees	The screen	The return value

With the SDKs

Pass your functions via tools. Python derives the schema from the signature and docstring. TypeScript declares it with tool(). The SDK runs the whole loop.

from hai_agents import Client

def get_order_status(order_id: str) -> str:
    """Look up the status of an order in our system."""
    return db.orders.get(order_id).status

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Check order 4242 and email the customer if it shipped.",
    tools=[get_order_status],
)
print(result.answer)

import { HaiAgentsClient, tool } from "hai-agents";

const getOrderStatus = tool({
  name: "get_order_status",
  description: "Look up the status of an order in our system.",
  inputSchema: {
    type: "object",
    properties: { order_id: { type: "string" } },
    required: ["order_id"],
  },
  fn: async ({ order_id }) => db.orders.get(order_id).status,
});

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Check order 4242 and email the customer if it shipped.",
  tools: [getOrderStatus],
});
console.log(result.answer);

Functions may be sync or async. Exceptions reach the agent as tool errors and don’t crash the run.
Tools run in the process that polls the session: only while your program waits on run_session / runSession, or on a handle’s wait_for_completion / waitForCompletion with the same tools.
Execution is at-least-once: if posting a result fails and the wait retries, the tool may run again. Make side-effecting tools idempotent.

Over the raw API

Declare the tools at session create

Declare the tools when creating the session, inline on the agent or via the agent.tools override for a registered agent:

Session create body

{
  "agent": {
    "name": "support-agent",
    "environments": [{ "kind": "web" }],
    "tools": [
      {
        "name": "get_order_status",
        "description": "Look up the status of an order in our system.",
        "input_schema": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ]
  },
  "messages": "Check order 4242 and email the customer if it shipped."
}

Detect the pending call

Long-poll changes for an ActiveStateChangeEvent whose data.state is "awaiting_tool_results". Its data.pending_tool_calls lists each pending call as a { tool_name, args, id } object:

Pending tool call event

{
  "type": "ActiveStateChangeEvent",
  "data": {
    "state": "awaiting_tool_results",
    "pending_tool_calls": [
      { "tool_name": "get_order_status", "args": { "order_id": "4242" }, "id": "call_1" }
    ]
  },
  "timestamp": "2026-06-01T15:14:05Z"
}

Post the result

Execute the call and post the result, echoing the pending call back as tool_req:

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": "get_order_status", "args": {"order_id": "4242"}, "id": "call_1"}, "result": "shipped"}'

Send several at once with {"type": "batch", "results": [...]}. Report a failure as an error_event instead of a tool_result. It carries error, origin (both required), and the echoed tool_req:

Tool error report

{ "kind": "error_event", "error": "Order not found", "origin": "custom_tools", "tool_req": { "tool_name": "get_order_status", "args": { "order_id": "4242" }, "id": "call_1" } }

The agent resumes once every pending call has a result. Calls still unresolved when the run ends (for example on max_time_s) fail with a model-visible error. Posting to a finished session returns 409.

Related: Two-factor authentication (a built-in tool for one-time codes), Watch and steer sessions

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

With the SDKs

Over the raw API

Declare the tools at session create

Detect the pending call

Post the result

​With the SDKs

​Over the raw API

Declare the tools at session create

Detect the pending call

Post the result

With the SDKs

Over the raw API