> ## Documentation Index > Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). > Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`. > Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status. > Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress. # 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](/agents-api/run-from-the-platform). Create a key at [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys?product=computeruseagents\&source=docs). 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. Pick a language below. It applies to every code block on this page. ```bash CLI theme={"system"} pip install "hai-agents[cli]" hai login # browser sign-in; creates and stores your key in ~/.config/hai/.env ``` ```bash cURL theme={"system"} # no install needed, the API is plain HTTP export HAI_API_KEY="hk-..." ``` ```bash Python theme={"system"} pip install hai-agents ``` ```bash TypeScript theme={"system"} npm install hai-agents ``` `h/web-surfer-flash` is a [pre-built agent](/agents-api/agents/overview#pre-built-agents) with a cloud browser already attached. Give it an imperative task. The CLI and SDK calls create the [session](/agents-api/sessions/overview) and block until the agent finishes. Over raw HTTP, create the session, wait for it to finish (long-poll [`changes`](/agents-api/sessions/changes)), then read `latest_answer` off the session. ```bash CLI theme={"system"} hai run "Open Hacker News and list the top 3 stories with their URLs." \ --agent h/web-surfer-flash ``` ```bash cURL theme={"system"} 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": [{"type": "user_message", "message": "Open Hacker News and list the top 3 stories with their URLs."}] }' | jq -r .id) # Once the session has finished, read the settled answer curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID" \ -H "Authorization: Bearer $HAI_API_KEY" | jq -r .latest_answer ``` ```python Python theme={"system"} 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) ``` ```typescript TypeScript theme={"system"} 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: ```text theme={"system"} completed 1. - 2. - 3. - ``` Open the [H Platform](https://platform.hcompany.ai/?product=computeruseagents\&source=docs) while it runs to watch the agent work, screenshot by screenshot. See [Agent View](/agents-api/observe-and-steer). ## 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. An [environment](/agents-api/environments/overview) is what your agent sees and acts on. Register a web browser in [`visual` mode](/agents-api/browser/configuration#modes), where the agent works from screenshots and clicks by coordinates, and give it an `id` the agent will reference. ```bash cURL theme={"system"} 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/" }' ``` ```python Python theme={"system"} client.environments.create_environment( id="visual-browser", kind="web", mode={"type": "visual", "width": 1200, "height": 1200}, start_url="https://www.google.com/", ) ``` ```typescript TypeScript theme={"system"} await client.environments.createEnvironment({ kind: "web", id: "visual-browser", mode: { type: "visual", width: 1200, height: 1200 }, startUrl: "https://www.google.com/", }); ``` 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: ```bash cURL theme={"system"} 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"] }' ``` ```python Python theme={"system"} 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"], ) ``` ```typescript TypeScript theme={"system"} 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"], }); ``` 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. ```bash CLI theme={"system"} 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." ``` ```bash cURL theme={"system"} 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) # Once the session has finished, read the settled answer curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID" \ -H "Authorization: Bearer $HAI_API_KEY" | jq -r .latest_answer ``` ```python Python theme={"system"} 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) ``` ```typescript TypeScript theme={"system"} 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); ``` Need live progress? Poll [`status`](/agents-api/sessions/status) for state and step count, or long-poll [`changes`](/agents-api/sessions/changes) to stream events as they happen. Open the [H Platform](https://platform.hcompany.ai/?product=computeruseagents\&source=docs) to see your sessions: watch a running one step by step, or scrub a finished run to replay the full trajectory. See [Agent View](/agents-api/observe-and-steer) for details. *** ## Next steps Reusable configurations: pre-built agents and how to create your own. The surfaces your agent perceives and acts on. Reusable instruction fragments you can attach to agents. The session lifecycle and how to interact with a running agent.