> ## 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.

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Build with the SDKs

> Install and configure the hai-agents Python and TypeScript SDKs and CLI: authentication, region, retries, timeouts, and the async client.

The typed clients and CLI ship as `hai-agents`: [Python](https://pypi.org/project/hai-agents/) (sync and async, typed with Pydantic v2) and [TypeScript](https://www.npmjs.com/package/hai-agents). You can also call the API over HTTP (see the [API reference](/agents-api/api-reference), where each endpoint page has a playground) or connect any [MCP host](/agents-api/mcp).

## Install

<CodeGroup>
  ```bash CLI theme={"system"}
  pip install "hai-agents[cli]"
  ```

  ```bash Python theme={"system"}
  pip install hai-agents
  ```

  ```bash TypeScript theme={"system"}
  npm install hai-agents
  ```
</CodeGroup>

## 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](/agents-api/quickstart#get-your-api-key).

<CodeGroup>
  ```bash CLI theme={"system"}
  hai login   # browser sign-in; stores the key in ~/.config/hai/.env
  ```

  ```python Python theme={"system"}
  from hai_agents import Client

  client = Client()
  # or pass it explicitly: Client(api_key="hk-...")
  ```

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

  const client = new HaiAgentsClient();
  // or pass it explicitly: new HaiAgentsClient({ apiKey: "hk-..." })
  ```
</CodeGroup>

## Client configuration

### Region

The clients default to the EU host, and requests stay in-region (the [API reference](/agents-api/api-reference#base-url) lists the hosts). To target the US region:

<CodeGroup>
  ```python Python theme={"system"}
  from hai_agents import Client, HaiAgentsEnvironment

  client = Client(environment=HaiAgentsEnvironment.US)
  ```

  ```typescript TypeScript theme={"system"}
  import { HaiAgentsClient, HaiAgentsEnvironment } from "hai-agents";

  const client = new HaiAgentsClient({ environment: HaiAgentsEnvironment.Us });
  ```
</CodeGroup>

### Retries, timeouts, and async

| Setting | Python | TypeScript | Default |
| - | - | - | - |
| Retries on [transient errors](/agents-api/errors#handling-errors-with-the-sdk), with backoff | `max_retries` | `maxRetries` | `2` |
| Request timeout, in seconds | `timeout` on the client, `timeout_in_seconds` per call | `timeoutInSeconds` | `60` |
| Async client | `AsyncClient`: same surface as `Client`, awaited, with `async for` on `stream()` | Async throughout | |

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

<CodeGroup>
  ```python Python theme={"system"}
  client = Client(max_retries=5, timeout=120)
  client.sessions.list_sessions(request_options={"max_retries": 0, "timeout_in_seconds": 10})
  ```

  ```typescript TypeScript theme={"system"}
  const client = new HaiAgentsClient({ maxRetries: 5, timeoutInSeconds: 120 });
  await client.sessions.listSessions({}, { maxRetries: 0, timeoutInSeconds: 10 });
  ```
</CodeGroup>

[Structured output](/agents-api/structured-output#chaining-agents) uses `AsyncClient` to run agents in parallel with `asyncio.gather`. To run the agent on your own machine behind the same sessions API, use Python's `Client.local()`: see [Local mode](/agents-api/local-mode).

## Examples

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

<Frame caption="A plain-language prompt driving a browser agent from Python: add_to_cart.py">
  <video controls playsInline className="w-full aspect-video rounded-xl" src="https://mintcdn.com/hcompany/NKXrpCWEaWVdSeM0/videos/add-to-cart.mp4?fit=max&auto=format&n=NKXrpCWEaWVdSeM0&q=85&s=ee4bb16ed0f1b4765589a1c89e5dbad0" data-path="videos/add-to-cart.mp4" />
</Frame>

The prompt: *"Search for 'Random Access Memories' by Daft Punk, add it to the shopping cart."* Code: [`examples/add_to_cart/add_to_cart.py`](https://github.com/hcompai/computer-use-agents-demos/blob/main/examples/add_to_cart/add_to_cart.py).

Related: [MCP server](/agents-api/mcp), [Coding assistants](/agents-api/coding-skills), [Quickstart](/agents-api/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.