AGagentarea
v1
protected
agents

Create Agent

Changed on

Create a new agent, and the triggers that start it, in one request.

Every trigger is checked before anything is written. If creating one still fails, the triggers already made and the agent are removed again, so the caller never ends up with an agent that silently lacks a schedule or channel.

post/v1/workspaces/{workspace}/agents/

Request

Path parameters

workspacestring required

Slug of the workspace the request acts in

Request body

a2ui_enabledboolean nullable

Expose this agent over the A2UI protocol.

agent_type'stateless' | 'stateful'

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.

client_idstring uuid nullable

A Codex or Claude Code client of this workspace whose runner runs the agent's tasks on the CLI's subscription; null runs them on the platform's own loop and model.

descriptionstring

Short summary of what the agent does.

instructionstring

System prompt / behavioural instructions for the agent.

model_idstring nullable

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.

namestring required

Human-readable agent name (unique per workspace).

planningboolean nullable

Enable explicit planning step before execution.

reasoning_effortstring nullable

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_tokensinteger nullable

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

skill_idsstring[] nullable

UUIDs of skills to attach to the agent.

Response

Successful Response

a2a_urlstring nullable
a2ui_enabledboolean nullable
agent_typestring
client_idstring uuid nullable
descriptionstring nullable
idstring uuid required
instructionstring nullable
is_catalogboolean
model_idstring nullable
namestring required
planningboolean nullable
reasoning_effortstring nullable
reasoning_max_tokensinteger nullable
registry_item_idstring nullable
skillsobject[] nullable
slugstring required
statusstring required
update_availableboolean

Changes

  • fc6f062f7d70Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 97bdabfb1aaaRevision changes
    • info

      added the new optional request property /////

    • info

      added the optional property ////// to the response with the status