---
title: "Create Agent"
method: POST
path: "/v1/workspaces/{workspace}/agents/"
tags: ["v1", "protected", "agents"]
---

# Create Agent

`POST /v1/workspaces/{workspace}/agents/`

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.

## Path parameters

- `workspace` string, required — Slug of the workspace the request acts in

## Request body

- AgentCreateRequest — ``AgentCreate`` plus the triggers created with the agent.
  - `a2ui_enabled` boolean, 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.
  - `description` string — Short summary of what the agent does.
  - `instruction` string — System prompt / behavioural instructions for the agent.
  - `model_id` string, 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.
  - `name` string, required — Human-readable agent name (unique per workspace).
  - `planning` boolean, nullable — Enable explicit planning step before execution.
  - `skill_ids` string[], nullable — UUIDs of skills to attach to the agent.
  - `tools` union[], 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.
    - union
      - CodeToolConfig
        - `name` string, required
        - `settings` CodeToolSettings — Settings for a built-in code toolset.
          - `disabled_methods` string[], nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'code'
      - McpToolConfigInput
        - `name` string, required
        - `settings` McpToolSettings — Settings for an MCP server tool (a subset of the server's tools).
          - `allowed_tools` McpToolPermission[], nullable
            - `requires_user_confirmation` boolean, nullable
            - `tool_name` string, required
          - `requires_user_confirmation` boolean, nullable
        - `type` 'mcp'
      - AgentToolConfig
        - `name` string, required
        - `settings` AgentToolSettings — Settings for an agent-to-agent (delegation) tool. ``a2a_url`` selects the *remote* transport binding; absent → same-platform direct delegation. Lives here only — A2A is a per-edge binding, not a property every tool type carries.
          - `a2a_url` string, nullable
          - `description_override` string, nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'agent'
      - OpenApiToolConfig
        - `name` string, required
        - `settings` OpenApiToolSettings — Settings for an OpenAPI connection tool. ``load_mode`` picks schema disclosure: "explicit" inlines every operation's schema into each LLM call (legacy); "searchable" defers them behind a ``load_tools`` meta-tool. Honored only for openapi tools — which is exactly why it lives here and nowhere else.
          - `allowed_tools` string[], nullable
          - `load_mode` 'explicit' | 'searchable', nullable
          - `openapi_connection_id` string, nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'openapi'
  - `triggers` TriggerSpec[] — Triggers that start the agent: schedules, webhooks, messaging channels (types from GET /v1/triggers/catalog). Created with the agent; if any cannot be created, neither the agent nor any trigger is kept.
    - `allowed_methods` string[] — HTTP methods accepted on the webhook endpoint.
    - `channel_credentials` object, nullable — Channel credentials (bot_token, SMTP password, etc). Stored encrypted in the secret store. Never returned in responses.
    - `conditions` object — Optional conditions evaluated against event data before firing.
    - `cron_expression` string, nullable — 5- or 6-field cron expression (required when trigger_type='cron').
    - `data_extractor` string, nullable — Polling extractor identifier (e.g. 'imap', 'rss').
    - `data_extractor_config` object, nullable — Connection/auth details for the polling extractor.
    - `description` string — Short summary of what this trigger does.
    - `enabled` boolean — Whether the trigger is active immediately on creation.
    - `event_types` string[] — Event types to filter on (empty list = accept all events).
    - `failure_threshold` integer — Auto-disable after this many consecutive failed executions.
    - `name` string, required — Human-readable trigger name.
    - `task_parameters` object — Parameters merged into the task created when the trigger fires.
    - `timezone` string — IANA timezone for cron evaluation (e.g. 'UTC', 'America/New_York').
    - `trigger_type` 'cron' | 'webhook' | 'polling', required — 'cron' for scheduled, 'webhook' for inbound HTTP, 'polling' for extractor-driven.
    - `validation_rules` object — Per-channel validation rules (signature secrets, allowed senders, etc).
    - `webhook_config` object, nullable — Channel-specific configuration (bot tokens, signing keys, etc).
    - `webhook_id` string, nullable — Public webhook path segment. Auto-generated if omitted for webhook triggers.
    - `webhook_type` string — Channel type: 'generic', 'telegram', 'slack', 'discord', etc.

## Response `200`

Successful Response

- AgentResponse
  - `a2ui_enabled` boolean, nullable
  - `agent_type` string
  - `description` string, nullable
  - `id` string, uuid, required
  - `instruction` string, nullable
  - `is_catalog` boolean
  - `model_id` string, nullable
  - `name` string, required
  - `planning` boolean, nullable
  - `registry_item_id` string, nullable
  - `skills` object[], nullable
  - `slug` string, required
  - `status` string, required
  - `tools` union[], nullable
    - union
      - CodeToolConfig
        - `name` string, required
        - `settings` CodeToolSettings — Settings for a built-in code toolset.
          - `disabled_methods` string[], nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'code'
      - McpToolConfigOutput
        - `name` string, required
        - `settings` McpToolSettings — Settings for an MCP server tool (a subset of the server's tools).
          - `allowed_tools` McpToolPermission[], nullable
            - `requires_user_confirmation` boolean, nullable
            - `tool_name` string, required
          - `requires_user_confirmation` boolean, nullable
        - `type` 'mcp'
      - AgentToolConfig
        - `name` string, required
        - `settings` AgentToolSettings — Settings for an agent-to-agent (delegation) tool. ``a2a_url`` selects the *remote* transport binding; absent → same-platform direct delegation. Lives here only — A2A is a per-edge binding, not a property every tool type carries.
          - `a2a_url` string, nullable
          - `description_override` string, nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'agent'
      - OpenApiToolConfig
        - `name` string, required
        - `settings` OpenApiToolSettings — Settings for an OpenAPI connection tool. ``load_mode`` picks schema disclosure: "explicit" inlines every operation's schema into each LLM call (legacy); "searchable" defers them behind a ``load_tools`` meta-tool. Honored only for openapi tools — which is exactly why it lives here and nowhere else.
          - `allowed_tools` string[], nullable
          - `load_mode` 'explicit' | 'searchable', nullable
          - `openapi_connection_id` string, nullable
          - `requires_user_confirmation` boolean, nullable
        - `type` 'openapi'
  - `update_available` boolean

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-26** `286327d8bd86` — 2 breaking, 2 warning, 1 info
  - the request property `tools` became required
  - request property `tools` list-of-types was narrowed by removing types `null` from media type `application/json`
  - removed the request property `events_config`
  - removed the optional property `events_config` from the response with the `200` status
  - …1 more
- **2026-09-26** `d3ad8e1a3681` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/agentarea/apis/agentarea-api/changes/v1/workspaces/:workspace/agents/post.md)

---

[API](https://skmtc.dev/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.dev/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentarea/apis/agentarea-api/revisions/286327d8bd86?raw)