Custom tools

Let the agent call functions in your code.

With the SDKs

Pass your functions via tools. They add to the core tools the environment supplies, like click and type. Python derives the schema from the signature and docstring. TypeScript declares it with tool(). The SDK runs the whole loop.

Python

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="Has order 4242 shipped?",
    tools=[get_order_status],
)
print(result.answer)

• Functions may be sync or async. Exceptions reach the agent as tool errors and don’t crash the session.
• Tools run only while your program waits on the session.
• 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

1. 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:

   cURL

   SESSION_ID=$(curl -s -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
     -H "Authorization: Bearer $HAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "agent": {
         "name": "support-agent",
         "description": "Answers order questions.",
         "environments": [{"id": "browser", "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": "Has order 4242 shipped?"
     }' | jq -r .id)
   
2. 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"
   }
   

   The same list is on the session itself: pending_tool_calls on status and changes holds the calls from the agent’s latest report, so you don’t need to scan events for it. A call you just answered can stay listed until the agent reports again.

3. 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 turn ends (for example on max_time_s) fail with a model-visible error.