Skip to main content
Set up a browser environment, create an agent, run it on a task, and read its answer. All you need to start is an API key.
1

Get your API key

Every request needs an H API key. Create one at platform.eu.hcompany.ai/settings/api-keys: click Create key and give it a name. The key is shown once, so store it securely and keep it server-side. See Authentication for details.Pick a language below; it applies to every code block on this page.
export H_API_KEY="hk-..."
2

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. V1 ships the Browser; Desktop is in What’s next.
curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "visual-browser",
    "kind": "web",
    "mode": "visual",
    "headless": true,
    "width": 1200,
    "height": 1200,
    "start_url": "https://www.google.com/"
  }'
3

Create an agent

Create an agent that references the environment by id and reuse it across sessions. 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 $H_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"]
  }'
4

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.The client’s run_session / runSession method creates the session and blocks until it finishes, returning the final answer. Raw HTTP has no equivalent, so you create the session and long-poll changes until it reaches a terminal state.
# Create the session and capture its id
SESSION_ID=$(curl -sX POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "web-navigator",
    "messages": [
      {"type": "user_message", "message": "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."}
    ]
  }' | jq -r .id)

# Long-poll until the session reaches a terminal state, then print the answer
while true; do
  CHANGES=$(curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/changes?wait_for_seconds=25" \
    -H "Authorization: Bearer $H_API_KEY")
  [ -z "$CHANGES" ] && continue  # 204 No Content: nothing new yet
  STATUS=$(echo "$CHANGES" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|timed_out|interrupted)
      echo "$CHANGES" | jq -r .answer
      break
      ;;
  esac
done
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.
Prefer a UI? Watch the run live or replay it afterward in the H Platform.

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