Quickstart

pip install "hai-agents[cli]"

# no install needed, the API is plain HTTP

pip install hai-agents

npm install hai-agents

hai login            # browser sign-in; creates and stores your key in ~/.config/hai/.env

export HAI_API_KEY="hk-..."

from hai_agents import Client

client = Client()

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

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/"
  }'

client.environments.create_environment(
    id="visual-browser",
    kind="web",
    mode={"type": "visual", "width": 1200, "height": 1200},
    start_url="https://www.google.com/",
)

await client.environments.createEnvironment({
  kind: "web",
  id: "visual-browser",
  mode: { type: "visual", width: 1200, height: 1200 },
  startUrl: "https://www.google.com/",
});

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"]
  }'

client.agents.create_agent(
    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"],
)

await client.agents.createAgent({
  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"],
});

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

# Create the session and capture its id
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": "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.
# Advance FROM_INDEX each turn so the server waits for *new* changes instead of replaying old ones.
FROM_INDEX=0
while true; do
  CHANGES=$(curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/changes?from_index=$FROM_INDEX&wait_for_seconds=25" \
    -H "Authorization: Bearer $HAI_API_KEY")
  [ -z "$CHANGES" ] && continue  # 204 No Content: nothing new yet
  FROM_INDEX=$((FROM_INDEX + $(echo "$CHANGES" | jq '.new_events | length')))
  STATUS=$(echo "$CHANGES" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|timed_out|interrupted) break ;;
  esac
done

# The answer rides the page carrying the final events, which may trail the
# status flip; the session snapshot has the settled value.
curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $HAI_API_KEY" | jq -r .latest_answer

result = client.run_session(
    agent="web-navigator",
    messages="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.",
)

print(result.status)  # "completed"
print(result.answer)

const result = await client.runSession({
  agent: "web-navigator",
  messages:
    "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.",
});

console.log(result.status); // "completed"
console.log(result.answer);