Agents

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.

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 -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"]
  }'

from hai_agents import Client

client = Client()

client.agents.create_agent(
    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"],
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.agents.createAgent({
  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 },
      startUrl: "https://www.google.com/travel/flights",
    },
  ],
  skills: ["extract-data"],
});

Pre-built agents

H maintains a catalog of configured agents under the h/ namespace. You can run them as-is, with no setup. Catalog agents that delegate to subagents (such as h/deep-search-pro) build on Multi-agent. List them anytime with GET /api/v2/agents:

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

from hai_agents import Client

client = Client()

agents = client.agents.list_agents()

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const agents = await client.agents.listAgents();

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

hai run "Top 3 stories on Hacker News right now?" \
  --agent h/web-surfer-flash

curl -X 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": [{"type": "user_message", "message": "Top 3 stories on Hacker News right now?"}]
  }'

client.sessions.create_session(
    agent="h/web-surfer-flash",
    messages=[{"type": "user_message", "message": "Top 3 stories on Hacker News right now?"}],
)

await client.sessions.createSession({
  body: {
    agent: "h/web-surfer-flash",
    messages: [{ type: "user_message", message: "Top 3 stories on Hacker News right now?" }],
  },
});

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.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Configure an agent

Create your own

Pre-built agents

Endpoints

​Configure an agent

​Create your own

​Pre-built agents

​Endpoints

Configure an agent

Create your own

Pre-built agents

Endpoints