Skip to main content
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. H’s pre-built agents and environments live under the reserved h/ namespace (for example h/web-surfer-flash and h/browser). They are H-maintained, read-only, and available to every organization. Agents you create have no prefix and are private to your org. See Authentication for how names are scoped.

​
Configure an agent

FieldRequiredDescription
nameYesIdentifies the agent in your catalog and is the value you pass as agent when creating a session.
environmentsConditionalThe surfaces it acts on, like a browser. Required unless the agent is a pure manager that only delegates to subagents.
descriptionYesA 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.
modelNoThe Holo model that runs the agent. Defaults to holo3-122b-a10b; pass any Holo model id (for example holo3-1-35b-a3b for the faster Holo3.1) from the Models API. The choice also fixes the agent’s runtime profile (reasoning effort, concurrency, context window), which is not separately tunable.
instructionsNoAppended to the system prompt to steer behavior.
skillsNoReusable instruction fragments the agent loads on demand.
toolsNoExtra tools the agent can call from your own code. See Custom tools.
subagentsNoSpecialist 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_formatNoA 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",
        "width": 1280,
        "height": 800,
        "start_url": "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. List them anytime with GET /api/v2/agents: 
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: 
hai run "Top 3 stories on Hacker News right now?" \
  --agent h/web-surfer-flash

​
Endpoints

MethodPathDescription
POST/api/v2/agentsCreate an agent
GET/api/v2/agentsList agents
GET/api/v2/agents/{name}Retrieve an agent
PUT/api/v2/agents/{name}Update an agent
DELETE/api/v2/agents/{name}Delete an agent