> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.
# Create an agent
> Create a reusable agent in your catalog: model, environments, skills, instructions, subagents, and answer format, referenced by name in every session.
Creates a custom agent in your catalog. Reference it by `name` (e.g. `"agent": "my-research-bot"`) when [creating a session](/agents-api/sessions/create). Its environments, skills, and subagents come from the stored configuration.
**Returns** `201` with the created [agent object](/agents-api/agents/retrieve#response).
## Request body
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.
What the agent does. Read by parent agents to decide what to delegate.
The surfaces the agent acts on, at most one per kind. Each item is a string catalog id or an inline [environment](/agents-api/environments/create) spec, such as a [Browser](/agents-api/browser/configuration). The field is always required, but it may be empty (`[]`) only when the agent has `subagents` (a pure [manager](/agents-api/multi-agent)) or custom `tools`.
Holo model that runs the agent: any Holo model id listed in the [Models API](/models-api/introduction#models), for example `holo4-35b-a3b`. Omit for the default, `holo4-27b` (stored as `null`).
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).
| Model | Honored values |
| - | - |
| `holo4-27b` | `disabled`, `low`, `medium`, `xhigh` |
| `holo4-35b-a3b` | No effort levels: only `disabled` matters (thinking off) |
| Holo3, Holo3.1 | Only `disabled` (thinking off). Other values keep the default thinking |
Steering text appended to the system prompt.
Skills available to the agent, as catalog id strings or inline [skill](/agents-api/skills/create) specs.
Agents this one can delegate to, as catalog id strings or inline agent specs. See [Multi-agent](/agents-api/multi-agent).
A [JSON Schema](https://json-schema.org/) the final answer must conform to. When set, the agent returns [structured output](/agents-api/structured-output) instead of free-form text. Callers can set or override it per run with session [`overrides`](/agents-api/sessions/overview#overrides).
[Custom tools](/agents-api/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
```bash cURL theme={"system"}
curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
]
}'
```
```python Python theme={"system"}
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)
```
```typescript TypeScript theme={"system"}
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const agent = await client.agents.createAgent({
name: "my-web-agent",
description: "Custom web researcher",
environments: [
{
id: "browser",
kind: "web",
mode: { type: "visual", width: 1280, height: 720 },
startUrl: "https://news.ycombinator.com",
},
],
});
console.log(agent.name);
```
```json Response theme={"system"}
{
"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. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.