Agents

A saved config of environment, model, skills, and instructions.

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.

Create your own

Python

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-27b",
    environments=[{"id": "price-browser", "kind": "web", "mode": {"type": "visual", "width": 1280, "height": 800}}],
)

Then run it by name in a session: client.run_session(agent="web-price-finder", messages="Find the price of a Kindle Paperwhite.").

Configure an agent

Field	Required	Description
name	Yes	The value you pass as agent when creating a session, within the naming rules.
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.
model	No	The Holo model. Default holo4-27b. Any ID from Models, for example holo4-35b-a3b for lower latency.
reasoning_effort	No	How long the model thinks before each step. Values depend on the model.
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.
subagents	No	Agents this one can delegate to, as subagents.
answer_format	No	A JSON Schema the final answer must match (structured output). Unset returns free-form text. Override per session with overrides.

Each environments, skills, or subagents entry is a catalog ID to reuse, or an inline object for one-offs.

Pin a revision

Every write to a catalog agent creates a numbered revision: create makes revision 1, and each update or patch adds the next one.

Pass name:N wherever you reference the agent: a session’s agent, a schedule’s session_request, or a manager’s subagents. "agent": "my-research-bot:3" keeps running revision 3 after later edits. A bare name runs the latest.

Retrieve an agent reads a revision, List agent revisions lists them, and Restore an agent revision rolls back. Update an agent guards concurrent edits with ETag and If-Match.