> ## 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. # Watch and steer sessions > Watch a run, intervene while it works, and keep the conversation going. Agent View: event log on the left, live browser screenshot with the agent's current action on the right Every session shows up in **Agent View** on the [H Platform](https://platform.hcompany.ai/?product=computeruseagents\&source=docs), and its `agent_view_url` links straight there. Watch it live to debug a detour or tune a prompt, or replay every observation, action, and message once it ends. Agent View reads the same [`events`](/agents-api/sessions/events) stream as your code. Everything below targets the session `id` and works the same for a single agent or a [manager with subagents](/agents-api/multi-agent). ## Watch a run | Read | Returns | Use it to | | - | - | - | | [`status`](/agents-api/sessions/status) | Current [state](/agents-api/sessions/overview#lifecycle), step count, token usage | Poll as a cheap health check | | [`changes`](/agents-api/sessions/changes) | New events past an index, plus the final `answer`, long-polled | Follow an active run (see its [polling rules](/agents-api/sessions/changes#polling-rules)) | | [`events`](/agents-api/sessions/events) | The full, paginated record | Replay or audit after the fact | ```bash CLI theme={"system"} hai sessions status "$SESSION_ID" hai sessions watch "$SESSION_ID" # stream events until the session settles ``` ```bash cURL theme={"system"} curl "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/status" -H "Authorization: Bearer $HAI_API_KEY" curl "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/changes?from_index=0&wait_for_seconds=25" -H "Authorization: Bearer $HAI_API_KEY" curl "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/events?size=50" -H "Authorization: Bearer $HAI_API_KEY" ``` ```python Python theme={"system"} from hai_agents import Client client = Client() session = client.start_session( agent="h/web-surfer-flash", messages=[{"type": "user_message", "message": "Find the top story on Hacker News"}], ) session.status() # cheap snapshot session.changes(from_index=0) # new events + final answer, long-polled session.get() # the full Session resource result = session.wait_for_completion() # block until terminal print(result.status, result.answer) ``` ```typescript TypeScript theme={"system"} import { HaiAgentsClient } from "hai-agents"; const client = new HaiAgentsClient(); const session = await client.startSession({ agent: "h/web-surfer-flash", messages: [{ type: "user_message", message: "Find the top story on Hacker News" }], }); await session.status(); // cheap snapshot await session.changes({ fromIndex: 0 }); // new events + final answer, long-polled await session.get(); // the full Session resource const result = await session.waitForCompletion(); // block until terminal console.log(result.status, result.answer); ``` A blocking run-and-wait call (`run_session` / `runSession`) never surfaces the session mid-run. To read or intervene while it works, start the session and keep its handle. ### Stream events as they arrive The SDK handle's `stream()` runs the [`changes`](/agents-api/sessions/changes) long-poll loop for you and yields each [event](/agents-api/sessions/events) in order. * It resumes `from_index` and skips `204` no-change responses. * It stops when the session settles: a [terminal state](/agents-api/sessions/overview#lifecycle), or `idle`. Pass `until="terminal"` to keep it open across the idle turns of an [interactive session](#hold-an-interactive-conversation). * It is read-only and does not answer tool calls. For [custom tools](/agents-api/custom-tools), use `wait_for_completion` / `run_session`, which run them for you. ```python Python theme={"system"} for event in session.stream(): # `async for` with the async client print(event.type) ``` ```typescript TypeScript theme={"system"} for await (const event of session.stream()) { console.log(event.type); } ``` ## Steer a running agent Until the session reaches a [terminal state](/agents-api/sessions/overview#lifecycle), you can: | Action | Effect | | - | - | | [Send a message](/agents-api/sessions/send-messages) | Adds context or redirects the agent. The agent picks it up on the next step. Wakes an `idle` session and auto-resumes a `paused` one. | | [Pause](/agents-api/sessions/pause) / [Resume](/agents-api/sessions/resume) | Halts the agent with its state preserved, then continues. | | [Force an answer](/agents-api/sessions/force-answer) | The agent stops exploring and answers from what it has. | | [Cancel](/agents-api/sessions/cancel) | Stops the session for good. It ends `interrupted`. | ```bash CLI theme={"system"} hai sessions send "$SESSION_ID" "Only consider results from the last 24 hours" hai sessions cancel "$SESSION_ID" --yes ``` ```bash cURL theme={"system"} API=https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID AUTH="Authorization: Bearer $HAI_API_KEY" curl -X POST "$API/messages" -H "$AUTH" -H "Content-Type: application/json" \ -d '{"type": "user_message", "message": "Only consider results from the last 24 hours"}' curl -X POST "$API/pause" -H "$AUTH" curl -X POST "$API/resume" -H "$AUTH" curl -X POST "$API/force_answer" -H "$AUTH" curl -X DELETE "$API" -H "$AUTH" # cancel ``` ```python Python theme={"system"} session.send_message({"type": "user_message", "message": "Only consider results from the last 24 hours"}) session.pause() session.resume() session.force_answer() session.cancel() ``` ```typescript TypeScript theme={"system"} await session.sendMessage({ type: "user_message", message: "Only consider results from the last 24 hours" }); await session.pause(); await session.resume(); await session.forceAnswer(); await session.cancel(); ``` ## Hold an interactive conversation By default a session ends when the agent answers. Set [`idle_timeout_s`](/agents-api/sessions/create) at create time to keep it open: after each answer it goes [`idle`](/agents-api/sessions/overview#lifecycle) and waits that long for your next message, keeping its context and environment across turns. It terminates once a turn goes unanswered for `idle_timeout_s`. ```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", "idle_timeout_s": 600, "messages": [{"type": "user_message", "message": "Find the top story on Hacker News"}] }' | jq -r .id) # Once it answers and goes idle, follow up in the same context curl -X POST "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages" \ -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \ -d '{"type": "user_message", "message": "Now open its comments and summarize the discussion"}' ``` ```python Python theme={"system"} session = client.start_session( agent="h/web-surfer-flash", idle_timeout_s=600, messages=[{"type": "user_message", "message": "Find the top story on Hacker News"}], ) session.send_message({"type": "user_message", "message": "Now open its comments and summarize the discussion"}) ``` ```typescript TypeScript theme={"system"} const session = await client.startSession({ agent: "h/web-surfer-flash", idleTimeoutS: 600, messages: [{ type: "user_message", message: "Find the top story on Hacker News" }], }); await session.sendMessage({ type: "user_message", message: "Now open its comments and summarize the discussion" }); ``` A settled session reports the agent's `outcome` and, on failure, an `error_code`: see [Session failures](/agents-api/errors#session-failures). At your concurrency limit, new sessions wait in `queued`: see [Queued sessions](/agents-api/plans-and-limits#queued-sessions). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.