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": [
    {}
  ],
  "answer_format": {},
  "tools": [
    {}
  ]
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/agents"

payload = {
    "name": "<string>",
    "description": "<string>",
    "environments": [{}],
    "model": "<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>',
    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>',
    '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  \"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  \"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  \"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_body

POST

api

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": [
    {}
  ],
  "answer_format": {},
  "tools": [
    {}
  ]
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/agents"

payload = {
    "name": "<string>",
    "description": "<string>",
    "environments": [{}],
    "model": "<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>',
    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>',
    '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  \"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  \"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  \"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_body

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’s catalog (rejected with 403) and marks the agent as reserved; 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 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. 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

Agents this one can delegate to, as catalog id strings or inline agent specs.

answer_format

object

A JSON Schema the agent’s final answer must conform to. When set, the agent returns structured output matching the schema instead of free-form text. Omit it for free-form text; callers can also set or override it per run with session overrides.

tools

array

Custom tools the agent can call from your own code.

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,
  "instructions": null,
  "skills": null,
  "subagents": null,
  "answer_format": 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 fails validation; common cases: `environments` empty on an agent that has no `subagents`, a duplicate environment kind, or an invalid `name` shape.

List

Agents

Environments

Sessions

Skills

Vaults

Browser Profiles

Webhooks

Schedules

Create an agent

Request body

Examples

Errors

​Request body

​Examples

​Errors

Request body

Examples

Errors