> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentarea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Agent

> Create a new agent.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/
openapi: 3.1.0
info:
  description: >-
    Modular and extensible framework for building AI agents. This API requires
    JWT Bearer token authentication for most endpoints. Include your JWT token
    in the Authorization header. Public endpoints include /, /health, /docs,
    /redoc, and /openapi.json.
  title: AgentArea API
  version: 0.1.0
servers: []
security:
  - bearer: []
paths:
  /v1/agents/:
    post:
      tags:
        - v1
        - protected
        - agents
      summary: Create Agent
      description: Create a new agent.
      operationId: create_agent_v1_agents__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - HTTPBearer: []
components:
  schemas:
    AgentCreate:
      additionalProperties: false
      description: >-
        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.
      properties:
        a2ui_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Expose this agent over the A2UI protocol.
          title: A2Ui Enabled
        agent_type:
          default: stateless
          deprecated: true
          description: >-
            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.
          enum:
            - stateless
            - stateful
          title: Agent Type
          type: string
        description:
          default: ''
          description: Short summary of what the agent does.
          maxLength: 1000
          title: Description
          type: string
        events_config:
          anyOf:
            - $ref: '#/components/schemas/EventsConfig'
            - type: 'null'
          description: Event subscriptions that auto-trigger this agent.
        instruction:
          default: ''
          description: System prompt / behavioural instructions for the agent.
          maxLength: 20000
          title: Instruction
          type: string
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            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.
          title: Model Id
        name:
          description: Human-readable agent name (unique per workspace).
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        planning:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Enable explicit planning step before execution.
          title: Planning
        skill_ids:
          anyOf:
            - items:
                format: uuid
                type: string
              type: array
            - type: 'null'
          description: UUIDs of skills to attach to the agent.
          title: Skill Ids
        tools:
          anyOf:
            - items:
                discriminator:
                  mapping:
                    agent:
                      $ref: '#/components/schemas/AgentToolConfig'
                    code:
                      $ref: '#/components/schemas/CodeToolConfig'
                    mcp:
                      $ref: '#/components/schemas/McpToolConfig-Input'
                    openapi:
                      $ref: '#/components/schemas/OpenApiToolConfig'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/CodeToolConfig'
                  - $ref: '#/components/schemas/McpToolConfig-Input'
                  - $ref: '#/components/schemas/AgentToolConfig'
                  - $ref: '#/components/schemas/OpenApiToolConfig'
              type: array
            - type: 'null'
          description: Tools attached to the agent (code/mcp/agent/openapi).
          title: Tools
      required:
        - name
      title: AgentCreate
      type: object
    AgentResponse:
      properties:
        a2ui_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: A2Ui Enabled
        agent_type:
          default: stateless
          title: Agent Type
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        events_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Events Config
        id:
          format: uuid
          title: Id
          type: string
        instruction:
          anyOf:
            - type: string
            - type: 'null'
          title: Instruction
        is_catalog:
          default: false
          title: Is Catalog
          type: boolean
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Id
        name:
          title: Name
          type: string
        planning:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Planning
        registry_item_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Registry Item Id
        skills:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Skills
        slug:
          title: Slug
          type: string
        status:
          title: Status
          type: string
        tools:
          anyOf:
            - items:
                discriminator:
                  mapping:
                    agent:
                      $ref: '#/components/schemas/AgentToolConfig'
                    code:
                      $ref: '#/components/schemas/CodeToolConfig'
                    mcp:
                      $ref: '#/components/schemas/McpToolConfig-Output'
                    openapi:
                      $ref: '#/components/schemas/OpenApiToolConfig'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/CodeToolConfig'
                  - $ref: '#/components/schemas/McpToolConfig-Output'
                  - $ref: '#/components/schemas/AgentToolConfig'
                  - $ref: '#/components/schemas/OpenApiToolConfig'
              type: array
            - type: 'null'
          title: Tools
        update_available:
          default: false
          title: Update Available
          type: boolean
      required:
        - id
        - slug
        - name
        - status
      title: AgentResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    EventsConfig:
      description: Per-agent event subscriptions.
      properties:
        events:
          anyOf:
            - items:
                $ref: '#/components/schemas/EventConfig'
              type: array
            - type: 'null'
          title: Events
      title: EventsConfig
      type: object
    AgentToolConfig:
      properties:
        name:
          title: Name
          type: string
        settings:
          anyOf:
            - $ref: '#/components/schemas/AgentToolSettings'
            - type: 'null'
        type:
          const: agent
          default: agent
          title: Type
          type: string
      required:
        - name
      title: AgentToolConfig
      type: object
    CodeToolConfig:
      properties:
        name:
          title: Name
          type: string
        settings:
          anyOf:
            - $ref: '#/components/schemas/CodeToolSettings'
            - type: 'null'
        type:
          const: code
          default: code
          title: Type
          type: string
      required:
        - name
      title: CodeToolConfig
      type: object
    McpToolConfig-Input:
      properties:
        name:
          title: Name
          type: string
        settings:
          anyOf:
            - $ref: '#/components/schemas/McpToolSettings'
            - type: 'null'
        type:
          const: mcp
          default: mcp
          title: Type
          type: string
      required:
        - name
      title: McpToolConfig
      type: object
    OpenApiToolConfig:
      properties:
        name:
          title: Name
          type: string
        settings:
          anyOf:
            - $ref: '#/components/schemas/OpenApiToolSettings'
            - type: 'null'
        type:
          const: openapi
          default: openapi
          title: Type
          type: string
      required:
        - name
      title: OpenApiToolConfig
      type: object
    McpToolConfig-Output:
      properties:
        name:
          title: Name
          type: string
        settings:
          anyOf:
            - $ref: '#/components/schemas/McpToolSettings'
            - type: 'null'
        type:
          const: mcp
          default: mcp
          title: Type
          type: string
      required:
        - name
      title: McpToolConfig
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    EventConfig:
      description: One event subscription for an agent.
      properties:
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Event-specific configuration.
          title: Config
        enabled:
          default: true
          description: Whether this subscription is active.
          title: Enabled
          type: boolean
        event_type:
          description: Event type the agent listens to.
          title: Event Type
          type: string
      required:
        - event_type
      title: EventConfig
      type: object
    AgentToolSettings:
      description: >-
        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.
      properties:
        a2a_url:
          anyOf:
            - type: string
            - type: 'null'
          title: A2A Url
        description_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Description Override
        requires_user_confirmation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires User Confirmation
      title: AgentToolSettings
      type: object
    CodeToolSettings:
      description: Settings for a built-in code toolset.
      properties:
        disabled_methods:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Disabled Methods
        requires_user_confirmation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires User Confirmation
      title: CodeToolSettings
      type: object
    McpToolSettings:
      description: Settings for an MCP server tool (a subset of the server's tools).
      properties:
        allowed_tools:
          anyOf:
            - items:
                $ref: '#/components/schemas/McpToolPermission'
              type: array
            - type: 'null'
          title: Allowed Tools
        requires_user_confirmation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires User Confirmation
      title: McpToolSettings
      type: object
    OpenApiToolSettings:
      description: >-
        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.
      properties:
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
        load_mode:
          anyOf:
            - enum:
                - explicit
                - searchable
              type: string
            - type: 'null'
          title: Load Mode
        openapi_connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Openapi Connection Id
        requires_user_confirmation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires User Confirmation
      title: OpenApiToolSettings
      type: object
    McpToolPermission:
      description: >-
        A single MCP tool the agent may call.


        Replaces the old ``list[Any]`` for ``allowed_tools`` (the former FIXME).

        ``requires_user_confirmation`` is transport only: the API translates it
        into

        an agent-scoped approval policy rule and does not persist it here, so it
        is

        ``None`` at rest and reconstituted from rules on read.
      properties:
        requires_user_confirmation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires User Confirmation
        tool_name:
          title: Tool Name
          type: string
      required:
        - tool_name
      title: McpToolPermission
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: JWT Bearer token for authentication
      scheme: bearer
      type: http
    HTTPBearer:
      scheme: bearer
      type: http

````