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>",
"reasoning_effort": "<string>",
"instructions": "<string>",
"skills": [
{}
],
"subagents": [
{}
],
"answer_format": {},
"tools": [
{}
]
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/agents"
payload = {
"name": "<string>",
"description": "<string>",
"environments": [{}],
"model": "<string>",
"reasoning_effort": "<string>",
"instructions": "<string>",
"skills": [{}],
"subagents": [{}],
"answer_format": {},
"tools": [{}]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
environments: [{}],
model: '<string>',
reasoning_effort: '<string>',
instructions: '<string>',
skills: [{}],
subagents: [{}],
answer_format: {},
tools: [{}]
})
};
fetch('https://agp.eu.hcompany.ai/api/v2/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'environments' => [
[
]
],
'model' => '<string>',
'reasoning_effort' => '<string>',
'instructions' => '<string>',
'skills' => [
[
]
],
'subagents' => [
[
]
],
'answer_format' => [
],
'tools' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_bodyAgents
Create an agent
Create a reusable agent in your catalog: model, environments, skills, instructions, subagents, and answer format, referenced by name in every session.
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>",
"reasoning_effort": "<string>",
"instructions": "<string>",
"skills": [
{}
],
"subagents": [
{}
],
"answer_format": {},
"tools": [
{}
]
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/agents"
payload = {
"name": "<string>",
"description": "<string>",
"environments": [{}],
"model": "<string>",
"reasoning_effort": "<string>",
"instructions": "<string>",
"skills": [{}],
"subagents": [{}],
"answer_format": {},
"tools": [{}]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
environments: [{}],
model: '<string>',
reasoning_effort: '<string>',
instructions: '<string>',
skills: [{}],
subagents: [{}],
answer_format: {},
tools: [{}]
})
};
fetch('https://agp.eu.hcompany.ai/api/v2/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'environments' => [
[
]
],
'model' => '<string>',
'reasoning_effort' => '<string>',
'instructions' => '<string>',
'skills' => [
[
]
],
'subagents' => [
[
]
],
'answer_format' => [
],
'tools' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"environments\": [\n {}\n ],\n \"model\": \"<string>\",\n \"reasoning_effort\": \"<string>\",\n \"instructions\": \"<string>\",\n \"skills\": [\n {}\n ],\n \"subagents\": [\n {}\n ],\n \"answer_format\": {},\n \"tools\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_bodyCreates 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).| 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 |
string
Steering text appended to the system prompt.
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
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"
}
]
}'
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)
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);
Response
{
"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. |
Was this page helpful?