Agents

A reusable configuration: environment, model, skills, instructions. Run a pre-built h/ agent or create your own with the Agents API.

An agent holds the configuration a run needs: the environment it acts in, the model that drives it, and optional skills and instructions. Start with a pre-built agent from H, or create your own.

Names are scoped to your organization: the agents, skills, and environments you create are visible only within it. H’s pre-built agents and environments live under the reserved h/ namespace (for example h/web-surfer-flash and h/browser); they are available to every organization and read-only, so modifying one returns 403. Agents you create have no prefix.

Pre-built agents

H maintains a catalog of configured agents under the h/ namespace. You can run them as-is, with no setup.

Pre-built agents that delegate to subagents (such as h/deep-search-pro) build on Multi-agent.

Pre-built agents as a table

Agent	Model	Environments	Skills	Description
h/deep-search-pro	holo3-122b-a10b		h/company, h/user-collaboration, h/answering, h/planning	Deep-research orchestrator of parallel web workers.
h/web-scraper-flash	holo3-1-35b-a3b	h/textual_browser	h/company, h/user-collaboration, h/answering, h/planning	Textual web agent for fast large-scale reading and extraction.
h/web-scraper-pro	holo3-122b-a10b	h/textual_browser	h/company, h/user-collaboration, h/answering, h/planning	Textual web agent for fast large-scale reading and extraction.
h/web-surfer-flash	holo3-1-35b-a3b	h/browser	h/company, h/user-collaboration, h/answering, h/planning	Visual web agent for interactive or visually rendered pages.
h/web-surfer-pro	holo3-122b-a10b	h/browser	h/company, h/user-collaboration, h/answering, h/planning	Visual web agent for interactive or visually rendered pages.

List them anytime with GET /api/v2/agents:

cURL

curl "https://agp.eu.hcompany.ai/api/v2/agents" \
  -H "Authorization: Bearer $HAI_API_KEY"

Reference one by name when you create a session, and the platform supplies its full configuration:

CLI

hai run "Open Hacker News and list the top 3 stories with their URLs." \
  --agent h/web-surfer-flash

Configure an agent

Field	Required	Description
name	Yes	Identifies the agent in your catalog and is the value you pass as agent when creating a session.
environments	Conditional	The surfaces it acts on, like a browser. Required unless the agent is a pure manager that only delegates to subagents.
description	Yes	A one-line summary of what the agent does. Also used for delegation: a parent agent reads it to decide whether to hand off a task.
model	No	The Holo model that runs the agent. Defaults to holo3-122b-a10b; pass any Holo model id from the Models API, for example holo3-1-35b-a3b for the faster Holo3.1.
instructions	No	Appended to the system prompt to steer behavior.
skills	No	Reusable instruction fragments the agent loads on demand.
tools	No	Extra tools the agent can call from your own code. See Custom tools.
subagents	No	Specialist agents this one can delegate to. Each runs as its own child session, in parallel, and returns a single answer the manager folds into its own. See Multi-agent.
answer_format	No	A JSON Schema the final answer must conform to. When set, the agent returns structured output matching the schema instead of free-form text. Leave it unset for free-form text. Override it per run with session overrides.

Each environments, skills, or subagents entry is either a string catalog id or an inline object. A reference keeps the definition central and reusable. An inline object is handy for one-offs. For exact field constraints, see Create an agent.

Create your own

Create an agent once, then reference it by name in every session:

cURL

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-price-finder",
    "description": "Finds and reports prices for products, flights, or services on the public web.",
    "instructions": "When the user asks for a price, return a single concise line with the amount, currency, and key context (vendor or airline, date, link). Prefer the cheapest matching option. If the price is not visible without login or payment, say so explicitly rather than guessing.",
    "model": "holo3-122b-a10b",
    "environments": [
      {
        "id": "price-browser",
        "kind": "web",
        "mode": {"type": "visual", "width": 1280, "height": 800},
        "start_url": "https://www.google.com/travel/flights"
      }
    ],
    "skills": ["extract-data"]
  }'

Context auto-compaction

Long sessions outgrow the model’s context window, so every agent compacts its own history automatically. Nothing to configure, and it can happen several times in one session.

When	After a step, once the last model call (prompt plus completion tokens) reaches about 70% of the context window.
Kept verbatim	Your task and messages, the agent’s notes and latest plan, earlier answers, the most recent tool calls, and the last screenshots.
Condensed	Everything else (past observations, tool outputs, reasoning) becomes a short execution summary written by the same model.
In the event stream	A flow_event with flow: "reset_history" and origin: "compactor", then a message_event from caller_id: "compactor" carrying the briefing the agent continues from. See Events.

Endpoints

Method	Path	Description
POST	/api/v2/agents	Create an agent
GET	/api/v2/agents	List agents
GET	/api/v2/agents/{name}	Retrieve an agent
PUT	/api/v2/agents/{name}	Update an agent
PATCH	/api/v2/agents/{name}	Patch an agent
DELETE	/api/v2/agents/{name}	Delete an agent

The list is paginated (page, size) and returns an items / page / total envelope. Sort it with sort=created_at or sort=agent_name, prefixed with - for descending.