> ## 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 create your own agent.

Run a pre-built agent on a task and read the result. All you need is an API key. Prefer no code? See [Run from the platform](/agents-api/run-from-the-platform).

<Steps titleSize="h3">
  <Step id="get-your-api-key" title="Get your API key">
    Create a key at [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys?product=computeruseagents\&source=docs). It is shown only once: store it securely and keep it server-side. The key is scoped to your **organization**, and everything you create with it is private to that org.

    Set it as `HAI_API_KEY`. The CLI and SDKs read it automatically. Raw HTTP sends it as a bearer token in the `Authorization` header.
  </Step>

  <Step id="install" title="Install the client">
    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Step>

  <Step id="run-a-pre-built-agent" title="Run a pre-built agent">
    `h/web-surfer-flash` is a [pre-built agent](/agents-api/agents/overview#pre-built-agents) with a cloud browser attached. Give it a task as an instruction. The CLI and SDKs 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`.

    <CodeGroup>
      ```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": "Open Hacker News and list the top 3 stories with their URLs."
        }' | jq -r .id)

      # Once the session has finished, read the 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);
      ```
    </CodeGroup>

    Output, with the day's front page:

    ```text theme={"system"}
    completed
    1. <story title> - <url>
    2. <story title> - <url>
    3. <story title> - <url>
    ```

    To watch the agent work screenshot by screenshot, or replay a finished run, open the [H Platform](https://platform.hcompany.ai/?product=computeruseagents\&source=docs). See [Agent View](/agents-api/observe-and-steer).
  </Step>
</Steps>

## Customize

Create your own agent when you need other browser settings, a model, or instructions. Create it once, then pass its `name` as `agent` in every session. Names you create have no prefix. The `h/` prefix is reserved for H's catalog.

<CodeGroup>
  ```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": "hn-reader",
      "description": "Reads Hacker News and reports what it sees.",
      "instructions": "Report only what you see on the page. If something is blocked, say so.",
      "environments": [{"id": "hn-browser", "kind": "web", "start_url": "https://news.ycombinator.com"}]
    }'
  ```

  ```python Python theme={"system"}
  client.agents.create_agent(
      name="hn-reader",
      description="Reads Hacker News and reports what it sees.",
      instructions="Report only what you see on the page. If something is blocked, say so.",
      environments=[{"id": "hn-browser", "kind": "web", "start_url": "https://news.ycombinator.com"}],
  )

  result = client.run_session(agent="hn-reader", messages="List the top 3 stories with their URLs.")
  ```

  ```typescript TypeScript theme={"system"}
  await client.agents.createAgent({
    name: "hn-reader",
    description: "Reads Hacker News and reports what it sees.",
    instructions: "Report only what you see on the page. If something is blocked, say so.",
    environments: [{ id: "hn-browser", kind: "web", startUrl: "https://news.ycombinator.com" }],
  });

  const result = await client.runSession({ agent: "hn-reader", messages: "List the top 3 stories with their URLs." });
  ```
</CodeGroup>

The example defines the environment inline and sets `start_url`, which defaults to `https://www.bing.com`. Run it like the pre-built agent, with `hn-reader` as the agent (`hai run ... --agent hn-reader` from the CLI).

Related: [Agents](/agents-api/agents/overview) (all fields, model, reasoning), [Environments](/agents-api/environments/overview) (reusable catalog environments), [Browser configuration](/agents-api/browser/configuration) (modes, viewport).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.