Skip to main content
POST
Create an agent
Creates a custom agent in your catalog. Reference it by name (e.g. "agent": "my-research-bot") when creating a session. Its environments, skills, and subagents come from the stored configuration. Returns 201 with the created agent object.

Request body

string
required
Catalog identifier, kebab-case with an optional single org/ namespace prefix. The h/ prefix is reserved for H’s catalog (rejected with 403). Any other name creates a custom agent, private to your organization. 1 to 127 characters, immutable after creation.
string
required
What the agent does. Read by parent agents to decide what to delegate.
array
required
The surfaces the agent acts on, at most one per kind. Each item is a string catalog id or an inline environment spec, such as a Browser. The field is always required, but it may be empty ([]) only when the agent has subagents (a pure manager) or custom tools.
string
Holo model that runs the agent: any Holo model id listed in the Models API, for example holo4-35b-a3b. Omit for the default, holo4-27b (stored as null).
string
How long the model thinks before each step: disabled, low, medium, or xhigh. More effort is slower and more careful. Omit to use the model’s default (medium on Holo4).
string
Steering text appended to the system prompt.
array
Skills available to the agent, as catalog id strings or inline skill specs.
array
Agents this one can delegate to, as catalog id strings or inline agent specs. See Multi-agent.
object
A JSON Schema the final answer must conform to. When set, the agent returns structured output instead of free-form text. Callers can set or override it per run with session overrides.
object[]
Custom tools the agent can call from your own code. Each has a name (letters, digits, and underscores, up to 64 characters), a description, and an optional input_schema (JSON Schema object).

Examples

Response

Errors