Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Body

application/json
name
string
required

Display name for the agent.

Example:

"Sales research agent"

model_name
string
required

ID of the LLM the agent runs on. Use GET /models to discover valid values.

Example:

"anthropic/claude-sonnet-4"

description
string | null
Example:

"Researches accounts and drafts outreach"

system_prompt
string | null
Example:

"You are a B2B sales research assistant."

tools
object[]

Tools the agent can call. Each tool is an object whose shape depends on the tool type.

resources
object[]

Resources attached to the agent.

skill_ids
string[] | null

IDs of skills to attach to the agent. Attachment happens inside the create transaction, so an invalid ID fails the whole request (no orphaned agent). Omit to attach none. The caller must hold INVOKE on each skill. After creation, manage skills with PATCH /agents/{agent_id}/skills.

Example:
metadata
object | null

Arbitrary key/value metadata stored on the agent.

folder_id
string | null

ID of the folder to place the agent in.

Example:

"folder_91ab"

is_active
boolean
default:true

Whether the agent is active. Defaults to true.

agent_id
string | null

Optional caller-supplied agent ID. When omitted, the server generates one.

team_id
string | null

ID of the team to create the agent under. When omitted, the agent is owned by the authenticated user.

Example:

"team_4f8c92ab"

Response

Agent created.

agent
object