Create an agent

Create a reusable agent configuration in your catalog.

POST /api/v2/agents

Python

from hai_agents import Client

client = Client()

agent = client.agents.create_agent(
    name="my-web-agent",
    description="Custom web researcher",
    environments=[
        {
            "id": "browser",
            "kind": "web",
            "mode": {"type": "visual", "width": 1280, "height": 720},
            "start_url": "https://news.ycombinator.com",
        }
    ],
)
print(agent.name)

201

{
  "name": "my-web-agent",
  "description": "Custom web researcher",
  "environments": [
    {
      "id": "browser",
      "kind": "web",
      "mode": {"type": "visual", "width": 1280, "height": 720},
      "start_url": "https://news.ycombinator.com"
    }
  ],
  "model": null,
  "reasoning_effort": null,
  "instructions": null,
  "subagents": null,
  "skills": null,
  "answer_format": null,
  "tools": null
}

Behavior

Reference it by name (for example "agent": "my-research-bot") when creating a session. Its environments, skills, and subagents come from the stored configuration.

Query parameters

message · string

A note stored on revision 1, such as what the agent is for. Up to 500 characters. Shown by List revisions.

Request body

name · 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.

description · string · required

What the agent does. Read by managers to decide what to delegate.

environments · array · required

The surfaces the agent acts on, at most one per kind. Each item is a catalog ID string 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.

model · string

Holo model that runs the agent: any Holo model ID listed in Models, for example holo4-35b-a3b. Omit for the default, holo4-27b (stored as null).

reasoning_effort · string

How long the model thinks before each step: disabled (thinking off), low, medium, or xhigh. More effort is slower and more careful. Omit for medium on Holo4 models, and the model’s default thinking on Holo3 and Holo3.1. Only holo4-27b has effort levels: the other models honor just disabled.

instructions · string

Steering text appended to the system prompt.

skills · array

Skills available to the agent, as catalog ID strings or inline skill specs.

subagents · array

Subagents this agent can delegate to, as catalog ID strings or inline agent specs.

answer_format · 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 session with overrides.

tools · object[]

Custom tools the agent can call from your own code.

name · string · required

Letters, digits, and underscores, up to 64 characters.

description · string · required

input_schema · object

JSON Schema object.

Response

201 with the created agent object at revision 1, also in the ETag header ("1").

Python

from hai_agents import Client

client = Client()

agent = client.agents.create_agent(
    name="my-web-agent",
    description="Custom web researcher",
    environments=[
        {
            "id": "browser",
            "kind": "web",
            "mode": {"type": "visual", "width": 1280, "height": 720},
            "start_url": "https://news.ycombinator.com",
        }
    ],
)
print(agent.name)

201

{
  "name": "my-web-agent",
  "description": "Custom web researcher",
  "environments": [
    {
      "id": "browser",
      "kind": "web",
      "mode": {"type": "visual", "width": 1280, "height": 720},
      "start_url": "https://news.ycombinator.com"
    }
  ],
  "model": null,
  "reasoning_effort": null,
  "instructions": null,
  "subagents": null,
  "skills": null,
  "answer_format": null,
  "tools": null
}

Errors

Status	Cause
403	Attempted to use the reserved h/ namespace.
409	An agent with this name already exists in your catalog.
422	Body failed validation. Common cases: environments missing, environments empty on an agent with no subagents or tools, a duplicate environment kind, or an invalid name shape.