Skip to main content
Set up a browser environment, create an agent, run it on a task, and read its answer. All you need is an API key. To skip the setup and just watch a task run, one call to the built-in h/web-surfer-flash agent does it (see the introduction).
1

Install the client

Install the hai-agents client (and CLI). Pick a language below; it applies to every code block on this page.
pip install "hai-agents[cli]"
2

Get your API key

Create a key at platform.hcompany.ai/settings/api-keys: click Create key and give it a name. It’s shown only once, so copy it and keep it server-side. Set it as HAI_API_KEY in your environment. See Authentication for details.
hai login            # browser sign-in; creates and stores your key in ~/.config/hai/.env
3

Create an environment

An environment is what your agent sees and acts on. Register a web browser in visual mode (it works from screenshots and clicks by coordinates) and give it an id the agent will reference. Today the Browser is available; Desktop is in What’s next.
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": "visual",
    "width": 1200,
    "height": 1200,
    "start_url": "https://www.google.com/"
  }'
4

Create an agent

Create an agent that references the environment by id and reuse it across sessions. 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), which is how you tell the two apart. The optional instructions shape how it behaves on every run; here they enforce grounding, verification, and honesty:
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"]
  }'
5

Run a session

Launch a session against web-navigator and describe the task in plain language. 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.Each call below creates the session and returns the final answer. Over raw HTTP there’s no single blocking call, so you create the session and long-poll changes until it reaches a terminal state.
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 instead of one blocking call? Poll status for state and step count, or long-poll changes to stream events as they happen.
6

Watch it on the platform

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: built-in agents and how to create your own.

Environments

The surfaces your agent perceives and acts on. Browser today; more in What’s next.

Skills

Reusable instruction fragments you can attach to agents.

Sessions

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