Skip to main content
POST
/
api
/
v2
/
agents
Create an agent
curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "environments": [
    {}
  ],
  "model": "<string>",
  "instructions": "<string>",
  "skills": [
    {}
  ],
  "subagents": [
    {}
  ]
}
'
Creates a new custom agent in your catalog. Once created, reference it by name (e.g. "agent": "my-research-bot") when creating a session, and its environments, skills, and subagents are pulled from the stored configuration. Returns 201 with the created Agent object.

​
Request body

The body is the Agent object. See that page for the full meaning of each field; the constraints that matter when creating one are below.
​
name
string
required
Catalog identifier, kebab-case with an optional single org/ namespace prefix. The h/ prefix is reserved for H employees (rejected with 403 otherwise) and marks the agent as reserved; any other name creates a custom agent, private to your organization. 1–127 characters, immutable after creation.
​
description
string
required
What the agent does. Read by parent agents to decide what to delegate.
​
environments
array
At most one per kind. Each item is a string catalog id or an inline Browser environment spec (desktop soon). Required unless the agent only delegates to subagents (a pure manager needs none).
​
model
string
Holo model that runs the agent. Defaults to holo3-122b-a10b; pass any Holo model id (for example holo3-1-35b-a3b) listed in the Models API. Omit to take the default.
​
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
(preview) Agents this one can delegate to, as catalog id strings or inline agent specs.

​
Examples

curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-agent",
    "description": "Custom web researcher",
    "environments": [
      {
        "id": "browser",
        "kind": "web",
        "headless": true,
        "width": 1280,
        "height": 720,
        "start_url": "https://news.ycombinator.com"
      }
    ]
  }'
Response
{
  "name": "my-web-agent",
  "description": "Custom web researcher",
  "environments": [
    {
      "id": "browser",
      "kind": "web",
      "headless": true,
      "width": 1280,
      "height": 720,
      "start_url": "https://news.ycombinator.com"
    }
  ],
  "model": null,
  "instructions": null,
  "skills": null,
  "subagents": null
}

​
Errors

StatusCause
403Attempted to use the reserved h/ namespace without H employee privileges.
409An agent with this name already exists in your catalog.
422Body fails validation; common cases: environments empty on an agent that has no subagents, a duplicate environment kind, or an invalid name shape.