Skip to main content
POST
Create Agent

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspace
string
required

Slug of the workspace the request acts in

Maximum string length: 120
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Body

application/json

AgentCreate plus the triggers created with the agent.

name
string
required

Human-readable agent name (unique per workspace).

Required string length: 1 - 255
tools
(CodeToolConfig · object | McpToolConfig · object | AgentToolConfig · object | OpenApiToolConfig · object)[]
required

Tools attached to the agent (code/mcp/agent/openapi). Required: pass [] for an agent with no tools. Built-in toolsets and their groups are listed by GET /v1/agents/tools.

a2ui_enabled
boolean | null

Expose this agent over the A2UI protocol.

agent_type
enum<string>
default:stateless
deprecated

DEPRECATED — stored and echoed back, but the runtime never reads it, so every agent behaves as 'stateless' regardless of this value. Conversation history does not currently survive across runs. Do not branch on this field.

Available options:
stateless,
stateful
answer_check
AnswerCheckPolicy · object | null

Check the agent's final answer for leaks (other scripts, tool names, codes, JSON, stack traces) and have the model rewrite it once before the person sees it. Null leaves it off. A governance safety rule that sets answer_check overrides this setting.

description
string
default:""

Short summary of what the agent does.

Maximum string length: 1000
instruction
string
default:""

System prompt / behavioural instructions for the agent.

Maximum string length: 20000
model_id
string | null

UUID of a model instance in this workspace (see GET /v1/model-instances). Null means no model is bound yet and the agent cannot be run.

planning
boolean | null

Enable explicit planning step before execution.

reasoning_effort
string | null

A reasoning level the model takes, e.g. low or high; the catalog lists each model's levels. Unset keeps the model's default. Not together with reasoning_max_tokens.

reasoning_max_tokens
integer | null

A token budget for the model's reasoning, a positive integer. Unset keeps the model's default. Not together with reasoning_effort.

skill_ids
string<uuid>[] | null

UUIDs of skills to attach to the agent.

triggers
TriggerSpec · object[]

Triggers that start the agent: cron schedules, or stream triggers on a stream whose sources are webhooks and polled providers. Created with the agent; if any cannot be created, neither the agent nor any trigger is kept.

Response

Successful Response

id
string<uuid>
required
name
string
required
slug
string
required
status
string
required
a2a_url
string | null
a2ui_enabled
boolean | null
agent_type
string
default:stateless
answer_check
AnswerCheckPolicy · object | null

Check an agent's final answer and have the model rewrite it once if it leaks.

Leaks: CJK characters, tool names and snake_case codes, stack traces, raw JSON, and (for language: ru) lowercase English words in a Russian answer.

description
string | null
instruction
string | null
is_catalog
boolean
default:false
model_id
string | null
planning
boolean | null
reasoning_effort
string | null
reasoning_max_tokens
integer | null
registry_item_id
string | null
skills
Skills · object[] | null
tools
(CodeToolConfig · object | McpToolConfig · object | AgentToolConfig · object | OpenApiToolConfig · object)[] | null
update_available
boolean
default:false