Agents

An agent is the configuration a run needs: the environments it acts in, the model that drives it, and optional skills and instructions. Pass its name as agent when you create a session. Names are scoped to your organization. H’s pre-built agents and environments live under the reserved h/ namespace (like h/web-surfer-flash and h/browser): every organization can use them, and they are read-only (modifying one returns 403). Agents you create have no prefix.

Pre-built agents

Run these as-is, with no setup. List them with GET /api/v2/agents. Pre-built managers like h/deep-search-pro delegate to subagents.

Configure an agent

Field	Required	Description
`name`	Yes	The value you pass as `agent` when creating a session.
`description`	Yes	One line on what the agent does. A manager reads it to decide whether to delegate a task.
`environments`	Yes	The surfaces it acts on, like a browser or a desktop. At most one per kind. `[]` only for a pure manager with `subagents` or an agent with custom tools.
`model`	No	The Holo model. Default `holo4-27b`. Any id from the Models API, for example `holo4-35b-a3b` for lower latency.
`reasoning_effort`	No	How long the model thinks before each step: `disabled`, `low`, `medium`, `xhigh`. Unset uses the model default (`medium` on Holo4). See the support table below.
`instructions`	No	Appended to the system prompt to steer behavior.
`skills`	No	Instruction fragments the agent loads on demand.
`tools`	No	Tools the agent calls in your own code. See Custom tools.
`subagents`	No	Agents this one can delegate to. Each runs as its own child session, in parallel, and returns one answer the manager folds into its own. See Multi-agent.
`answer_format`	No	A JSON Schema the final answer must match (structured output). Unset returns free-form text. Override per run with session `overrides`.

Each environments, skills, or subagents entry is a catalog id (string, reusable) or an inline object (handy for one-offs). Exact constraints: Create an agent.

Model	`reasoning_effort` support
`holo4-27b`	`disabled`, `low`, `medium`, `xhigh` all apply.
`holo4-35b-a3b`	No effort levels. Only `disabled` changes behavior (thinking off).
Holo3, Holo3.1	Only `disabled` applies (thinking off). Other values keep the default.

Create your own

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 on the public web.",
    "instructions": "Return one line: amount, currency, vendor, link. If the price needs a login, say so.",
    "model": "holo4-35b-a3b",
    "environments": [{"id": "price-browser", "kind": "web", "mode": {"type": "visual", "width": 1280, "height": 800}}]
  }'

from hai_agents import Client

client = Client()
client.agents.create_agent(
    name="web-price-finder",
    description="Finds and reports prices on the public web.",
    instructions="Return one line: amount, currency, vendor, link. If the price needs a login, say so.",
    model="holo4-35b-a3b",
    environments=[{"id": "price-browser", "kind": "web", "mode": {"type": "visual", "width": 1280, "height": 800}}],
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();
await client.agents.createAgent({
  name: "web-price-finder",
  description: "Finds and reports prices on the public web.",
  instructions: "Return one line: amount, currency, vendor, link. If the price needs a login, say so.",
  model: "holo4-35b-a3b",
  environments: [{ id: "price-browser", kind: "web", mode: { type: "visual", width: 1280, height: 800 } }],
});

To run it, see the Quickstart with agent="web-price-finder".

Context auto-compaction

Long sessions outgrow the context window, so every agent compacts its own history automatically, possibly several times per session. There is nothing to configure. After a step, once the last model call (prompt plus completion tokens) reaches about 70% of the window, the same model condenses past observations, tool outputs, and reasoning into a short summary. Your task and messages, the agent’s notes and plan, earlier answers, and the latest tool calls and screenshots stay verbatim. It shows in events as a flow_event with flow: "reset_history" and origin: "compactor", then a message_event from caller_id: "compactor" carrying the briefing.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Pre-built agents

Configure an agent

Create your own

Context auto-compaction

​Pre-built agents

​Configure an agent

​Create your own

​Context auto-compaction

Pre-built agents

Configure an agent

Create your own

Context auto-compaction