Agents API quickstart

Run a pre-built agent on a task and read the result. All you need is an API key. Prefer no code? See Run from the platform.

Get your API key

Create a key at platform.hcompany.ai/settings/api-keys. It is shown only once: store it securely and keep it server-side. The key is scoped to your organization, and everything you create with it is private to that org.Set it as HAI_API_KEY. The CLI and SDKs read it automatically. Raw HTTP sends it as a bearer token in the Authorization header.

Install the client

pip install "hai-agents[cli]"
hai login            # browser sign-in; creates and stores your key in ~/.config/hai/.env

# no install needed, the API is plain HTTP
export HAI_API_KEY="hk-..."

pip install hai-agents

npm install hai-agents

Run a pre-built agent

h/web-surfer-flash is a pre-built agent with a cloud browser attached. Give it a task as an instruction. The CLI and SDKs create the session and block until the agent finishes. Over raw HTTP, create the session, wait for it to finish (long-poll changes), then read latest_answer.

hai run "Open Hacker News and list the top 3 stories with their URLs." \
  --agent h/web-surfer-flash

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)

# Once the session has finished, read the answer
curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $HAI_API_KEY" | jq -r .latest_answer

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)

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);

Output, with the day’s front page:

completed
<story title> - <url>
<story title> - <url>
<story title> - <url>

To watch the agent work screenshot by screenshot, or replay a finished run, open the H Platform. See Agent View.

Customize

Create your own agent when you need other browser settings, a model, or instructions. Create it once, then pass its name as agent in every session. Names you create have no prefix. The h/ prefix is reserved for H’s catalog.

curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hn-reader",
    "description": "Reads Hacker News and reports what it sees.",
    "instructions": "Report only what you see on the page. If something is blocked, say so.",
    "environments": [{"id": "hn-browser", "kind": "web", "start_url": "https://news.ycombinator.com"}]
  }'

client.agents.create_agent(
    name="hn-reader",
    description="Reads Hacker News and reports what it sees.",
    instructions="Report only what you see on the page. If something is blocked, say so.",
    environments=[{"id": "hn-browser", "kind": "web", "start_url": "https://news.ycombinator.com"}],
)

result = client.run_session(agent="hn-reader", messages="List the top 3 stories with their URLs.")

await client.agents.createAgent({
  body: {
    name: "hn-reader",
    description: "Reads Hacker News and reports what it sees.",
    instructions: "Report only what you see on the page. If something is blocked, say so.",
    environments: [{ id: "hn-browser", kind: "web", startUrl: "https://news.ycombinator.com" }],
  },
});

const result = await client.runSession({ agent: "hn-reader", messages: "List the top 3 stories with their URLs." });

The example defines the environment inline and sets start_url, which defaults to https://www.bing.com. Run it like the pre-built agent, with hn-reader as the agent (hai run ... --agent hn-reader from the CLI). Related: Agents (all fields, model, reasoning), Environments (reusable catalog environments), Browser configuration (modes, viewport).

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Get your API key

Install the client

Run a pre-built agent

Customize

Get your API key

Install the client

Run a pre-built agent

​Customize

Customize