SDKs

Python, TypeScript, and the CLI.

Install

The typed clients and CLI ship as hai-agents: Python (sync and async, typed with Pydantic v2) and TypeScript.

CLI

pip install "hai-agents[cli]"

The cli extra installs holo (also hai). See Holo CLI.

To run the agent on your own machine behind the same sessions API, use Python’s Client.local() (Local runtime).

Authenticate

Set HAI_API_KEY in your environment, or pass the key explicitly. The client sends it on every call as a bearer token. No key yet? Create one.

CLI

holo login   # browser sign-in; stores the key in ~/.config/hai/.env

Call over HTTP

Requests go to your region’s host under /api/v2. Bodies are JSON with Content-Type: application/json, and every request sends the key as Authorization: Bearer $HAI_API_KEY. Responses are JSON, except 204 No Content on deletes and on a changes poll with nothing new. Timestamps are ISO 8601 strings. Errors share one envelope. Each endpoint page has a playground.

Pagination

List endpoints for sessions, agents, environments, skills, schedules, and webhooks take page (1-based, default 1) and size (default 10) and return a page envelope:

Page envelope

{
  "items": [],
  "page": 1,
  "total": 47
}

items holds the resources, page echoes the page you asked for, and total counts all matches. Responses do not echo size, so track it yourself: there are more pages while page * size < total. Each list page documents its size cap and sort options.

Vaults and browser profiles use offset pagination: limit and offset in, total, limit, offset, and a named array out.

Client configuration

Region

H runs isolated EU and US regions. Requests stay in-region: an EU key only ever reaches EU infrastructure. The REST API lives under /api/v2 and the MCP server under /mcp on each region’s host.

Region	Host
EU (default)	https://agp.eu.hcompany.ai
US	https://agp.hcompany.ai

The clients and CLI default to EU. To target the US region:

Python

from hai_agents import Client, HaiAgentsEnvironment

client = Client(environment=HaiAgentsEnvironment.US)

Retries and timeouts

Setting	Python	TypeScript	Default
Retries on transient errors, with backoff	max_retries	maxRetries	2
Request timeout, in seconds	timeout on the client, timeout_in_seconds per call	timeoutInSeconds	60

Set retries and timeouts on the client, or per call through request options:

Python

client = Client(max_retries=5, timeout=120)
client.sessions.list_sessions(request_options={"max_retries": 0, "timeout_in_seconds": 10})

Async

Python’s AsyncClient has the same surface as Client, awaited, with async for on stream(). The TypeScript client is async throughout.

Python

import asyncio
from hai_agents import AsyncClient

result = asyncio.run(AsyncClient().run_session(agent="h/web-surfer-flash", messages="List the top 3 Hacker News stories."))

Structured output uses it to run agents in parallel with asyncio.gather.

Examples

Runnable recipes (QA, extraction, custom tools), each wired as an MCP server or CLI tool, live in hcompai/computer-use-agents-demos.

Prompt: Search for 'Random Access Memories' by Daft Punk, add it to the shopping cart. Code: examples/add_to_cart/add_to_cart.py