Agents API quickstart

Get an API key, install the hai-agents SDK or CLI, run a pre-built computer-use agent with one call, then customize the environment and agent.

Run a pre-built agent on a task and read the result in three steps. Then customize the environment and agent it runs with. All you need is an API key. Prefer no code? See Run from the platform.

1. Get your API key

   Create a key at platform.hcompany.ai/settings/api-keys. It’s shown only once, so store it securely and keep it server-side. The key is scoped to your organization: everything you create with it is private to that org.

   Set it as HAI_API_KEY in your environment. Raw HTTP sends it as a bearer token in the Authorization header. The CLI and SDKs pick it up automatically.

2. Install the client

   Pick a language below. It applies to every code block on this page.

   CLI

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

   h/web-surfer-flash is a pre-built agent with a cloud browser already attached. Give it an imperative task. The CLI and SDK calls 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 off the session.

   CLI

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

   Output, with the day’s front page:

   completed
   1. <story title> - <url>
   2. <story title> - <url>
   3. <story title> - <url>
   

   Open the H Platform while it runs to watch the agent work, screenshot by screenshot. See Agent View.

Customize

A pre-built agent covers many tasks. When you need your own browser settings, model, or instructions, register an environment and an agent once, then reference them by id and name in every session.

1. Create an environment

   An environment is what your agent sees and acts on. Register a web browser in visual mode, where the agent works from screenshots and clicks by coordinates, and give it an id the agent will reference.

   cURL

   curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
     -H "Authorization: Bearer $HAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "visual-browser",
       "kind": "web",
       "mode": {"type": "visual", "width": 1200, "height": 1200},
       "start_url": "https://www.google.com/"
     }'
   
2. Create an agent

   Create an agent that references the environment by id. Agents you create have no prefix; H’s pre-built agents and environments use the reserved h/ namespace (like h/web-surfer-flash and h/browser). The optional instructions shape how the agent behaves on every run:

   cURL

   curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
     -H "Authorization: Bearer $HAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "web-navigator",
       "description": "Navigates and operates interactive websites to carry out a task end to end.",
       "instructions": "Ground every claim in what you actually see; never invent values you have not observed. Check the page changed as expected after each action, operate the controls a task needs (filters, dropdowns, date pickers), and finish the whole task. If something is blocked or unavailable, say so plainly instead of guessing.",
       "environments": ["visual-browser"]
     }'
   
3. Run a session

   Launch a session against web-navigator. Google Flights is a good test: its date picker, filters, and result cards only respond to real clicks, so the agent has to drive the page.

   CLI

   hai run --agent web-navigator \
     "On Google Flights, search a round trip from Paris (CDG) to New York (JFK): set departure to the first Monday of next month and the return one week later using the date picker, filter to nonstop flights, then open the cheapest result. Report the airline, total price, and departure time shown on its details."
   

   Need live progress? Poll status for state and step count, or long-poll changes to stream events as they happen.

4. Watch it live

   Open the H Platform to see your sessions: watch a running one step by step, or scrub a finished run to replay the full trajectory. See Agent View for details.

---

Next steps

Agents

Reusable configurations: pre-built agents and how to create your own.

Environments

The surfaces your agent perceives and acts on.

Skills

Reusable instruction fragments you can attach to agents.

Sessions

The session lifecycle and how to interact with a running agent.