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

# Create a new agent

> Creates a new agent with the provided information.



## OpenAPI

````yaml https://api-trial.cognigy.ai/swagger/openapi.json post /agents
openapi: 3.0.3
info:
  contact:
    email: support@example.com
    name: API Support
  description: API for managing agents and related resources
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: Agents API
  version: '1.0'
servers:
  - url: https://api-trial.cognigy.ai/v1
security:
  - ApiKey: []
tags:
  - name: Agents
  - name: Brand personas
  - name: Tools
  - name: Built-in tools
  - name: Skills
  - name: Built-in skills
  - name: MCP servers
  - name: Tool references
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create a new agent
      description: Creates a new agent with the provided information.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_agents.CreateAgentRequest'
        description: Agent data
        required: true
        x-originalParamName: agent
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/internal_agents.CreateAndReadAgentResponse
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest
          description: Invalid request body or validation error
        '403':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden
          description: Access denied
        '409':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict
          description: An agent with this name already exists in this project
        '500':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError
          description: Internal server error
components:
  schemas:
    internal_agents.CreateAgentRequest:
      properties:
        agentType:
          description: >-
            AgentType is the modality this agent is authored for: "text" or

            "voice". Omit it and the agent is created as "voice" — voice-native
            is

            what new agents are for. It drives which sections the configuration
            UI

            renders and is never consulted by the runtime, which takes its
            modality

            from the per-turn `channel` on ExecuteTurn instead.
          enum:
            - text
            - voice
          example: voice
          type: string
        description:
          type: string
        guardrails:
          allOf:
            - $ref: '#/components/schemas/internal_agents.GuardrailsRequest'
          description: |-
            Guardrails configures the agent's safety instructions and data
            privacy. Every safety toggle defaults to on, as in v1: leave out
            `safetySettings` (or the whole block) and all four are on; leave a
            toggle out of a sent `safetySettings` and that one is on. Only an
            explicit false turns a toggle off.
        hooks:
          allOf:
            - $ref: '#/components/schemas/internal_agents.HooksRequest'
          description: |-
            Hooks names the Flow the platform runs before the agent answers each
            message. Optional; at most one pre-Turn hook.
        image:
          description: >-
            Image is the agent's avatar: either a URL or a base64 data URI.

            Optional — an agent may be created without one, matching
            AgentPersona.
          type: string
        imageOptimizedFormat:
          type: boolean
        instructions:
          description: |-
            Instructions may hold CognigyScript. At most 5000 characters not
            counting CognigyScript (256 KiB stored).
          type: string
        knowledge:
          $ref: '#/components/schemas/internal_agents.KnowledgeRequest'
        largeLanguageModelReferenceId:
          type: string
        llmConfig:
          $ref: '#/components/schemas/internal_agents.LLMConfigRequest'
        localeReferenceId:
          type: string
        name:
          description: |-
            Name may hold CognigyScript. At most 200 characters not counting
            CognigyScript (64 KiB stored), and none of \ / : * ? " < > | ¥
            outside CognigyScript.
          type: string
        personaReferenceId:
          type: string
        projectId:
          description: MongoDB ObjectID represented as a hex string
          type: string
        realtimeVoice:
          description: >-
            RealtimeVoice is the gpt-live-1 voice; absent means the default
            ("marin").
          type: string
        role:
          description: >-
            Role is the agent's short role, e.g. "Customer support specialist".

            It opens the default system prompt. Optional; may hold
            CognigyScript.

            Trimmed; at most 100 characters not counting CognigyScript (64 KiB

            stored).
          type: string
        skillReferenceIds:
          items:
            type: string
          type: array
        toolReferenceIds:
          items:
            type: string
          type: array
        voiceLargeLanguageModelReferenceId:
          description: >-
            VoiceLargeLanguageModelReferenceId links a realtime (V2V) LLM for
            voice sessions.

            Optional UUID; text turns never use it.
          type: string
      required:
        - localeReferenceId
        - name
        - projectId
      type: object
    internal_agents.CreateAndReadAgentResponse:
      properties:
        agentType:
          description: >-
            AgentType is the modality the agent was authored for. Always
            present:

            an agent stored without one — every agent that predates the field —

            reads back as "text", because it was authored when chat was the only

            thing an agent could be.
          enum:
            - text
            - voice
          example: voice
          type: string
        createdAt:
          type: integer
        createdBy:
          example: 507f1f77bcf86cd799439011
          type: string
        description:
          type: string
        disabledToolReferenceIds:
          items:
            type: string
          type: array
        guardrails:
          $ref: '#/components/schemas/internal_agents.GuardrailsResponse'
        hooks:
          $ref: '#/components/schemas/internal_agents.HooksResponse'
        id:
          example: 507f1f77bcf86cd799439011
          type: string
        image:
          type: string
        imageOptimizedFormat:
          type: boolean
        instructions:
          type: string
        knowledge:
          $ref: '#/components/schemas/internal_agents.KnowledgeResponse'
        largeLanguageModelReferenceId:
          type: string
        lastChangedAt:
          type: integer
        lastChangedBy:
          example: 507f1f77bcf86cd799439011
          type: string
        llmConfig:
          $ref: '#/components/schemas/internal_agents.LLMConfigResponse'
        localeReferenceId:
          type: string
        name:
          type: string
        organisationId:
          example: 507f1f77bcf86cd799439011
          type: string
        personaReferenceId:
          type: string
        projectId:
          example: 507f1f77bcf86cd799439011
          type: string
        realtimeVoice:
          description: >-
            RealtimeVoice is the gpt-live-1 voice; absent means the default
            ("marin").
          type: string
        referenceId:
          type: string
        role:
          type: string
        skillReferenceIds:
          items:
            type: string
          type: array
        toolReferenceIds:
          items:
            type: string
          type: array
        voiceLargeLanguageModelReferenceId:
          description: >-
            VoiceLargeLanguageModelReferenceId links a realtime (V2V) LLM for
            voice sessions.

            Optional UUID; text turns never use it.
          type: string
        voicePromptTemplate:
          description: >-
            VoicePromptTemplate is the agent's own template; absent means the
            product default.
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest:
      properties:
        detail:
          example: request body validation failed
          type: string
        errors:
          items:
            $ref: >-
              #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError
          type: array
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 400
          type: integer
        title:
          example: Bad Request
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden:
      properties:
        detail:
          example: 'access denied: insufficient permissions'
          type: string
        instance:
          example: /v1/{resource}/{id}
          type: string
        status:
          example: 403
          type: integer
        title:
          example: Forbidden
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict:
      properties:
        detail:
          example: a resource with this identifier already exists
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 409
          type: integer
        title:
          example: Conflict
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError:
      properties:
        detail:
          example: internal server error
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 500
          type: integer
        title:
          example: Internal Server Error
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    internal_agents.GuardrailsRequest:
      properties:
        dataPrivacy:
          $ref: '#/components/schemas/internal_agents.DataPrivacyRequest'
        safetySettings:
          $ref: '#/components/schemas/internal_agents.SafetySettingsRequest'
      type: object
    internal_agents.HooksRequest:
      properties:
        preTurn:
          items:
            $ref: '#/components/schemas/internal_agents.PreTurnHook'
          type: array
      type: object
    internal_agents.KnowledgeRequest:
      properties:
        cognigyParameters:
          $ref: '#/components/schemas/internal_agents.CognigyRAGParametersDTO'
        context:
          type: string
        onSearchFailure:
          type: string
        ragMode:
          type: string
        ragType:
          type: string
      type: object
    internal_agents.LLMConfigRequest:
      properties:
        maxOutputTokens:
          type: integer
        reasoningEffort:
          description: >-
            ReasoningEffort controls the model's internal "thinking" budget.

            Allowed: "none", "minimal", "low", "medium", "high", "xhigh".
            Reasoning

            tokens are billed as completion tokens and reported as a subset of
            them.
          type: string
        temperature:
          type: number
      type: object
    internal_agents.GuardrailsResponse:
      properties:
        dataPrivacy:
          $ref: '#/components/schemas/internal_agents.DataPrivacyResponse'
        safetySettings:
          $ref: '#/components/schemas/internal_agents.SafetySettingsResponse'
      type: object
    internal_agents.HooksResponse:
      properties:
        preTurn:
          items:
            $ref: '#/components/schemas/internal_agents.PreTurnHook'
          type: array
      type: object
    internal_agents.KnowledgeResponse:
      properties:
        cognigyParameters:
          $ref: '#/components/schemas/internal_agents.CognigyRAGParametersDTO'
        context:
          type: string
        onSearchFailure:
          type: string
        ragMode:
          type: string
        ragType:
          type: string
      type: object
    internal_agents.LLMConfigResponse:
      properties:
        maxOutputTokens:
          type: integer
        reasoningEffort:
          type: string
        temperature:
          type: number
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.FieldError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
    internal_agents.DataPrivacyRequest:
      properties:
        contactProfilesOption:
          description: |-
            ContactProfilesOption is one of "none", "completeProfile",
            "profileMemoriesOnly" or "selectedProfileFields".
          example: completeProfile
          type: string
        selectedProfileFields:
          description: |-
            SelectedProfileFields names the profile keys to inject, and is read
            only under "selectedProfileFields". Names are not validated against
            the project's Profile Schema — that schema is owned by
            service-profiles and can change after the agent is saved, so a name
            that no longer resolves simply injects nothing.
          items:
            type: string
          type: array
      type: object
    internal_agents.SafetySettingsRequest:
      properties:
        avoidCopyrightInfringements:
          type: boolean
        avoidHarmfulContent:
          type: boolean
        avoidUngroundedContent:
          type: boolean
        preventJailbreakAndManipulation:
          type: boolean
      type: object
    internal_agents.PreTurnHook:
      properties:
        handler:
          $ref: '#/components/schemas/internal_agents.HookHandler'
      type: object
    internal_agents.CognigyRAGParametersDTO:
      properties:
        language:
          type: string
        stores:
          items:
            type: string
          type: array
        topK:
          type: integer
      type: object
    internal_agents.DataPrivacyResponse:
      properties:
        contactProfilesOption:
          example: completeProfile
          type: string
        selectedProfileFields:
          items:
            type: string
          type: array
      type: object
    internal_agents.SafetySettingsResponse:
      properties:
        avoidCopyrightInfringements:
          type: boolean
        avoidHarmfulContent:
          type: boolean
        avoidUngroundedContent:
          type: boolean
        preventJailbreakAndManipulation:
          type: boolean
      type: object
    internal_agents.HookHandler:
      properties:
        flowReferenceId:
          type: string
        kind:
          type: string
      type: object
  securitySchemes:
    ApiKey:
      description: '[Production] API key for production authentication'
      in: header
      name: X-API-Key
      type: apiKey

````