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

> Creates a new agent with optional tools, API tools, MCP servers, and frontend actions. Use this endpoint to set up a fully configured agent in a single request.  **Validation:** All referenced tools,

# Create Agent

For the complete error reference, see [Error Guide](/rest-api/ai-agents-apis/error-codes).


## OpenAPI

````yaml post /ai-agents/agent-builder/agents
openapi: 3.0.0
info:
  title: AI Agents APIs
  description: API reference for CometChat AI Agents service
  version: '1.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: ai-agent
    description: ''
paths:
  /ai-agents/agent-builder/agents:
    post:
      tags:
        - Agent Builder
      summary: Create Agent
      description: >-
        Creates a new agent with optional tools, API tools, MCP servers, and
        frontend actions. Use this endpoint to set up a fully configured agent
        in a single request.


        **Validation:** All referenced tools, API tools, and MCP servers are
        validated before creation.
      operationId: AgentBuilderController_create
      parameters:
        - name: chatApiVersion
          required: false
          in: header
          description: Chat API version. Defaults to `v3.0`.
          schema:
            type: string
            default: v3.0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCometChatAgentDto'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type: object
                    properties:
                      uid:
                        type: string
                        example: agent-uuid-1234
                      appId:
                        type: string
                        example: my-app-id
                      name:
                        type: string
                        example: Support Agent
                      icon:
                        type: string
                        example: https://example.com/icon.png
                      isActive:
                        type: boolean
                        example: true
                      description:
                        type: string
                        example: A helpful support agent
                      tools:
                        type: array
                        items:
                          type: string
                        example:
                          - gmail
                          - slack
                      files:
                        type: array
                        items:
                          type: string
                        example: []
                      websites:
                        type: array
                        items:
                          type: string
                        example: []
                      otherKbIntegrations:
                        type: array
                        items:
                          type: string
                        example: []
                      apiTools:
                        type: array
                        items:
                          type: string
                        example: []
                      mcpServers:
                        type: array
                        items:
                          type: string
                        example: []
                      frontendActions:
                        type: array
                        items:
                          type: string
                        example: []
                      ragVersion:
                        type: string
                        enum:
                          - v1
                          - v2
                        example: v2
                      lastMessageAt:
                        type: number
                        nullable: true
                        example: 1700000000000
                      instruction:
                        type: string
                        example: You are a helpful assistant
                      formattedInstruction:
                        type: string
                        example: You are a helpful assistant
                      metaData:
                        type: object
                        example: {}
                      model:
                        type: string
                        example: gpt-4o-mini
                      modelMetaData:
                        type: object
                        example: {}
                      createdAt:
                        type: number
                        example: 1700000000000
                      updatedAt:
                        type: number
                        example: 1700000000000
              example:
                agent:
                  uid: agent-uuid-1234
                  appId: my-app-id
                  name: Support Agent
                  icon: https://example.com/icon.png
                  isActive: true
                  description: A helpful support agent
                  tools:
                    - gmail
                    - slack
                  files: []
                  websites: []
                  otherKbIntegrations: []
                  apiTools: []
                  mcpServers: []
                  frontendActions: []
                  ragVersion: v2
                  lastMessageAt: null
                  instruction: You are a helpful assistant
                  formattedInstruction: You are a helpful assistant
                  metaData: {}
                  model: gpt-4o-mini
                  modelMetaData: {}
                  createdAt: 1700000000000
                  updatedAt: 1700000000000
      security:
        - apiKey: []
components:
  schemas:
    CreateCometChatAgentDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the agent
        icon:
          type: string
          description: URL to the icon/avatar of the agent
        description:
          type: string
          description: Description of the agent
        tools:
          description: Array of tool names available to this agent
          type: array
          items:
            type: string
        apiTools:
          description: Array of API tool names available to this agent
          type: array
          items:
            type: string
        mcpServers:
          description: Array of MCP server names available to this agent
          type: array
          items:
            type: string
        instruction:
          type: string
          description: Instructions for the agent behavior
        metaData:
          type: object
          description: Additional metadata for the agent
        model:
          type: string
          description: AI model to use for this agent
          default: gpt-4o-mini
        modelMetaData:
          type: object
          description: Configuration metadata for the AI model
          properties:
            temperature:
              type: number
              description: >-
                Controls randomness in responses. Lower values make output more
                focused and deterministic.
              example: 0.7
            maxTokens:
              type: number
              description: Maximum number of tokens to generate in the response.
              example: 4096
          additionalProperties: true
        isActive:
          type: boolean
          default: true
          description: Is the agent active?
      required:
        - name
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key (i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````