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.

Body

application/json

Payload for creating an agent.

model_id is the UUID of a model instance configured in the workspace — the runtime has no other interpretation of it. Omit it (or pass null) to create an agent with no model bound yet; such an agent cannot be run until a model is assigned.

name
string
required

Human-readable agent name (unique per workspace).

Required string length: 1 - 255
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
description
string
default:""

Short summary of what the agent does.

Maximum string length: 1000
events_config
EventsConfig · object | null

Event subscriptions that auto-trigger this agent.

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.

skill_ids
string<uuid>[] | null

UUIDs of skills to attach to the agent.

tools
(CodeToolConfig · object | McpToolConfig · object | AgentToolConfig · object | OpenApiToolConfig · object)[] | null

Tools attached to the agent (code/mcp/agent/openapi).

Response

Successful Response

id
string<uuid>
required
name
string
required
slug
string
required
status
string
required
a2ui_enabled
boolean | null
agent_type
string
default:stateless
description
string | null
events_config
Events Config · object | null
instruction
string | null
is_catalog
boolean
default:false
model_id
string | null
planning
boolean | 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