> ## 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 three 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), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). The `holo` CLI (`pip install "hai-agents[cli]"`) runs Agents API agents from a terminal, drives the user's own desktop with `-a h/holo-desktop`, and serves coding agents through `holo mcp`.
> 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: `holo`.
> 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.

# Agents API

> Agents that use a browser or desktop for you.

```python Python wrap theme={"system"}
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Open Hacker News and list the top 3 stories with their URLs.",
)
print(result.answer)
```

```typescript TypeScript wrap theme={"system"}
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Open Hacker News and list the top 3 stories with their URLs.",
});
console.log(result.answer);
```

```bash CLI wrap theme={"system"}
holo "Open Hacker News and list the top 3 stories with their URLs."
```

```bash cURL wrap theme={"system"}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-flash", "messages": "Open Hacker News and list the top 3 stories with their URLs."}'
```

→

```bash CLI wrap theme={"system"}
holo run "On nike.com (US), find the men's Air Max 90 in white, open it and report its price and available sizes."
```

```python Python wrap theme={"system"}
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="On nike.com (US), find the men's Air Max 90 in white, open it and report its price and available sizes.",
)
print(result.answer)
```

```typescript TypeScript wrap theme={"system"}
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "On nike.com (US), find the men's Air Max 90 in white, open it and report its price and available sizes.",
});
console.log(result.answer);
```

```bash cURL wrap theme={"system"}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"agent": "h/web-surfer-flash", "messages": "On nike.com (US), find the men's Air Max 90 in white, open it and report its price and available sizes."}
EOF
```

→

```bash CLI wrap theme={"system"}
holo run --agent h/web-surfer-pro "On https://www.saucedemo.com log in with username standard_user and password secret_sauce. Add the two cheapest products to the cart, check out as Ada Lovelace with postal code 75009, finish the order and report the item total and the final confirmation message."
```

```python Python wrap theme={"system"}
result = client.run_session(
    agent="h/web-surfer-pro",
    messages="On https://www.saucedemo.com log in with username standard_user and password secret_sauce. Add the two cheapest products to the cart, check out as Ada Lovelace with postal code 75009, finish the order and report the item total and the final confirmation message.",
)
print(result.answer)
```

```typescript TypeScript wrap theme={"system"}
const result = await client.runSession({
  agent: "h/web-surfer-pro",
  messages: "On https://www.saucedemo.com log in with username standard_user and password secret_sauce. Add the two cheapest products to the cart, check out as Ada Lovelace with postal code 75009, finish the order and report the item total and the final confirmation message.",
});
console.log(result.answer);
```

```bash cURL wrap theme={"system"}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-pro", "messages": "On https://www.saucedemo.com log in with username standard_user and password secret_sauce. Add the two cheapest products to the cart, check out as Ada Lovelace with postal code 75009, finish the order and report the item total and the final confirmation message."}'
```

→

```python Python wrap theme={"system"}
class LegoSet(BaseModel):
    name: str
    pieces: int
    price: float

class Sets(BaseModel):
    sets: list[LegoSet]

result = client.run_session(
    agent="h/web-surfer-flash",
    messages="On lego.com (US), list the 8 LEGO Star Wars sets with the most pieces, with name, piece count and price.",
    answer_schema=Sets,
)
```

```typescript TypeScript wrap theme={"system"}
const Sets = z.object({
  sets: z.array(z.object({ name: z.string(), pieces: z.number(), price: z.number() })),
});

const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "On lego.com (US), list the 8 LEGO Star Wars sets with the most pieces, with name, piece count and price.",
  answerSchema: Sets,
});
```

```bash cURL wrap theme={"system"}
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-flash", "messages": "On lego.com (US), list the 8 LEGO Star Wars sets with the most pieces, with name, piece count and price.",
    "overrides": {"agent.answer_format": {"type": "object", "properties": {"sets": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "pieces": {"type": "integer"}, "price": {"type": "number"}}, "required": ["name", "pieces", "price"]}}}, "required": ["sets"]}}}'
```

→

```python Python wrap theme={"system"}
session = client.start_session(
    agent="h/web-surfer-flash",
    messages="On airbnb.com, search stays in Chamonix, France for 2 guests next weekend and report the first listing rated 4.9 or higher: name, price per night and rating.",
)
session.send_message("Change of plans: search Annecy instead of Chamonix, same criteria.")
print(session.wait_for_completion().answer)
```

```typescript TypeScript wrap theme={"system"}
const session = await client.startSession({
  agent: "h/web-surfer-flash",
  messages: "On airbnb.com, search stays in Chamonix, France for 2 guests next weekend and report the first listing rated 4.9 or higher: name, price per night and rating.",
});
await session.sendMessage({ type: "user_message", message: "Change of plans: search Annecy instead of Chamonix, same criteria." });
console.log((await session.waitForCompletion()).answer);
```

```bash cURL wrap theme={"system"}
API=https://agp.eu.hcompany.ai/api/v2
AUTH="Authorization: Bearer $HAI_API_KEY"

SESSION_ID=$(curl -sX POST $API/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-flash", "messages": "On airbnb.com, search stays in Chamonix, France for 2 guests next weekend and report the first listing rated 4.9 or higher: name, price per night and rating."}' | jq -r .id)

curl -X POST "$API/sessions/$SESSION_ID/messages" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"type": "user_message", "message": "Change of plans: search Annecy instead of Chamonix, same criteria."}'
```

→

```python Python wrap theme={"system"}
client.agents.create_agent(
    name="trip-scout",
    description="Compares stays across cities in parallel.",
    environments=[],
    subagents=["h/web-surfer-flash"],
)
result = client.run_session(agent="trip-scout", messages="On airbnb.com, find the first stay rated 4.9 or higher for 2 guests next weekend in Annecy, Chamonix and Lyon. Use one subagent per city, in parallel. Each subagent answers as 'Stay: <name> | Price: <price per night>'. Return a comparison table with city, stay and price per night.")
```

```typescript TypeScript wrap theme={"system"}
await client.agents.createAgent({
  body: {
    name: "trip-scout",
    description: "Compares stays across cities in parallel.",
    environments: [],
    subagents: ["h/web-surfer-flash"],
  },
});
const result = await client.runSession({ agent: "trip-scout", messages: "On airbnb.com, find the first stay rated 4.9 or higher for 2 guests next weekend in Annecy, Chamonix and Lyon. Use one subagent per city, in parallel. Each subagent answers as 'Stay: <name> | Price: <price per night>'. Return a comparison table with city, stay and price per night." });
```

```bash cURL wrap theme={"system"}
API=https://agp.eu.hcompany.ai/api/v2
AUTH="Authorization: Bearer $HAI_API_KEY"

curl -X POST $API/agents -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "trip-scout", "description": "Compares stays across cities in parallel.", "environments": [], "subagents": ["h/web-surfer-flash"]}'

curl -X POST $API/sessions -H "$AUTH" -H "Content-Type: application/json" -d @- <<'EOF'
{"agent": "trip-scout", "messages": "On airbnb.com, find the first stay rated 4.9 or higher for 2 guests next weekend in Annecy, Chamonix and Lyon. Use one subagent per city, in parallel. Each subagent answers as 'Stay: <name> | Price: <price per night>'. Return a comparison table with city, stay and price per night."}
EOF
```

## Quickstart

### 1. Get your API key

Create a key at [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys?product=computeruseagents\&source=docs) and keep it server-side. It is shown only once. The SDKs read it from `HAI_API_KEY`. Using the CLI? Skip this: `holo login` creates one.

```bash theme={"system"}
export HAI_API_KEY="hk-..."
```

### 2. Install the client

```bash CLI theme={"system"}
pip install "hai-agents[cli]"
holo login
```

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

```bash TypeScript theme={"system"}
npm install hai-agents
```

### 3. Run a pre-built agent

`h/web-surfer-flash` is a [pre-built agent](https://hub.hcompany.ai/agents-api/agents/overview.md#pre-built-agents) with a cloud browser attached. Give it a task as an instruction. The CLI and SDKs create the [session](https://hub.hcompany.ai/agents-api/sessions/overview.md) and block until the agent finishes.

```bash CLI theme={"system"}
holo "Open Hacker News and list the top 3 stories with their URLs."
# runs h/web-surfer-flash by default; pick another with --agent
```

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

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Open Hacker News and list the top 3 stories with their URLs.",
)

print(result.status)
print(result.answer)
```

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

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Open Hacker News and list the top 3 stories with their URLs.",
});

console.log(result.status);
console.log(result.answer);
```

```bash cURL theme={"system"}
SESSION_ID=$(curl -sX POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-flash",
    "messages": "Open Hacker News and list the top 3 stories with their URLs."
  }' | jq -r .id)

# Wait until the session settles, then read the answer
while :; do
  STATUS=$(curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/status" \
    -H "Authorization: Bearer $HAI_API_KEY" | jq -r .status)
  case "$STATUS" in completed|idle|failed|timed_out|interrupted) break ;; esac
  sleep 5
done

curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $HAI_API_KEY" | jq -r .latest_answer
```

To set the browser, model, or instructions, [create your own agent](https://hub.hcompany.ai/agents-api/agents/overview.md#create-your-own).

## Next


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