> ## 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. # Configure the browser > Define a Browser environment: its fields, modes, and actions. The Browser (`kind: "web"`) is a web browser H provisions per session in the cloud, or Chrome on your own machine with [local control](/agents-api/local-control). Reference a [built-in browser](/agents-api/environments/overview#built-in-environments) by catalog name (like `"h/browser"`), or define one inline in an agent's `environments` list. Inline, only `id` is required. Every other field has a default. ## Fields | Field | Default | Meaning | | - | - | - | | `id` | required | Catalog identifier. | | `kind` | `"web"` | Environment type. A browser is `web`. | | `start_url` | `"https://www.bing.com"` | First URL to open. | | `headless` | `false` | Run without a visible window. | | `mode` | `{"type": "visual"}` | How the agent sees and acts: `visual` or `text`. See [Modes](#modes). | | `lazy` | `false` | Cloud only. Start the browser on the agent's first browser action, not at session start. The first turn gets no initial page observation, and an unused browser never starts. Actions are the same. | | `settle_s` | `1.0` | Seconds the agent waits after each action, so the next observation shows the settled page. `0` to `10`. | | `host` | `"cloud"` | `cloud` (H infrastructure) or `user_device` (Chrome on your machine, see [Local control](/agents-api/local-control)). | | `session_id` | `null` | Command channel of a `user_device` browser. The Python SDK sets it. Set it yourself only to attach to [`hai local browser`](/agents-api/local-control#run-a-session). | ### Sign-in and network fields These apply to cloud browsers only. | Field | Default | Meaning | | - | - | - | | `vault_id` | `null` | [Vault](/agents-api/vaults/overview) whose secrets the agent can fill into login forms. Must be in your organization. | | `browser_profile_id` | `null` | [Browser profile](/agents-api/browser/profiles) to load (cookies, storage), so the session starts signed in. Must be in your organization. | | `use_default_browser_profile` | `false` | Load your [default profile](/agents-api/browser/profiles#default-profiles) (created empty on first use) and save state back when the session ends. Mutually exclusive with `browser_profile_id`. | | `persist_browser_profile` | `false` | Save the final state back into the loaded profile. Requires `browser_profile_id` or `use_default_browser_profile`. Best-effort: a profile has one writer, and other sessions start read-only. See [Persisting state back](/agents-api/browser/profiles#persisting-state-back-into-the-profile). | | `network` | `null` | Proxy egress: `managed_proxy` or `proxy_url`, set only one. See [Proxy](/agents-api/browser/proxy). | ## Modes At each step the agent gets a fresh observation of the page, then picks one or more actions. `mode` sets what the observation contains and which [actions](#actions) exist. | Mode | The agent sees | The agent acts | Use it for | | - | - | - | - | | `visual` (default) | A viewport screenshot, the URL, and open tabs. With `markdown: true`, also the page text. | Points at on-screen targets, and the platform resolves exact click and type coordinates. | General web work: clicking, forms, anything that needs the rendered page. | | `text` | The page as text only, split into chunks of `chunk_size` characters. | Reads, pages through chunks, follows links by URL. Read-only: it cannot click or type. | Reading and research at scale: search, scraping, link-heavy navigation. | * **Cost tracks screenshots.** `text` sends no images, so it uses the fewest tokens and runs fastest. `markdown: true` adds the page text on top of each screenshot. Default to `visual`, and switch to `text` for pure reading. * **`text` mode pages instead of scrolling.** Each observation says which chunk the agent is on. Raise `chunk_size` to fit more per step, at more tokens per observation. * **Replay what the agent saw.** Every observation is on the [event stream](/agents-api/sessions/events#observation-shapes): `web` in `visual` mode, `textual_web` in `text` mode. ### Mode fields `mode` is an object selected by `type`, carrying only the fields of that mode. | `type` | Field | Default | Meaning | | - | - | - | - | | `visual` | `width` | `1200` | Viewport width in pixels. Positive integer. Cloud only: a `user_device` browser keeps its window's size. | | `visual` | `height` | `1200` | Viewport height in pixels. Positive integer. Cloud only: a `user_device` browser keeps its window's size. | | `visual` | `markdown` | `false` | Also include the viewport's text as markdown with each screenshot. | | `text` | `chunk_size` | `20000` | Characters of page text per chunk. Positive integer. | ```json Text-mode browser theme={"system"} { "id": "research-browser", "kind": "web", "mode": { "type": "text", "chunk_size": 20000 } } ``` ## Actions The agent picks actions on its own. You never call them, and there is no per-agent tool list. To shape how it uses them, set the agent's [`instructions`](/agents-api/agents/overview). | Action | Description | Visual | Text | | - | - | :-: | :-: | | `go_to_web` | Navigate to a URL. | ✓ | ✓ | | `go_back_web` | Go back in the browser history. | ✓ | ✓ | | `refresh_web` | Refresh the current page. | ✓ | ✓ | | `switch_tab_web` | Switch to another tab, or open a new one. | ✓ | ✓ | | `close_tab_web` | Close a tab. | ✓ | ✓ | | `click_web` | Click at viewport coordinates. | ✓ | | | `write` | Focus an input at coordinates and type into it. | ✓ | | | `fill_secret_at` | Fill a vault secret (like `password` or `totp`) into a field. The value goes straight into the page, never into the agent's context. Offered only when a [vault](/agents-api/vaults/overview) is bound via `vault_id` and matches the current page. | ✓ | | | `select_option` | Pick an option from a native `