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

# Create a conversational agent



## OpenAPI

````yaml api-reference/openapi3.json post /conversational_agents
openapi: 3.0.0
info:
  title: Operator API
  version: '2025-06-19'
  description: API for Operator
servers:
  - url: https://api.operator.xyz
security: []
paths:
  /conversational_agents:
    post:
      tags:
        - Conversational agents
      summary: Create a conversational agent
      parameters:
        - name: Operator-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-06-19'
          description: The API version to use.
          example: '2025-06-19'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Human-readable name for the agent.
                  type: string
                description:
                  description: Description of the agent.
                  type: string
                config:
                  $ref: '#/components/schemas/ConversationalAgentConfig'
                  description: >-
                    Full configuration for the agent (e.g. voice, runtime,
                    tools).
                  title: conversational.agent.config
                postprocess_agents:
                  items:
                    type: string
                  type: array
                  default: null
                  description: >-
                    List of postprocessing procedural agent IDs that run after
                    the conversation ends, e.g. `["pa_8qm9JBCiTe7"]`
              required:
                - name
                - description
                - config
              type: object
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: Unique identifier for the agent, e.g. `ca_8qm9JBCiTe7`
                    type: string
                  version_id:
                    description: >-
                      Version-specific identifier for the agent instance, e.g.
                      `ca_8qm9JBCiTe7@v0`
                    type: string
                required:
                  - id
                  - version_id
                type: object
        '400':
          description: The agent configuration is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data: {}
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data: {}
      security:
        - BearerAuth: []
components:
  schemas:
    ConversationalAgentConfig:
      properties:
        personas:
          description: Defines how the agent presents itself to users.
          items:
            $ref: '#/components/schemas/Persona'
            title: persona
          type: array
        voice:
          $ref: '#/components/schemas/VoiceConfig'
          description: >-
            Controls ambient and thinking sounds, and which words are emphasized
            in speech.
          title: voice.config
        runtime:
          $ref: '#/components/schemas/RuntimeConfig'
          description: >-
            Specifies the system prompt and model used to drive the agent's
            behavior.
          title: runtime.config
        tool:
          $ref: '#/components/schemas/ToolConfig'
          description: >-
            Declares the tools and transfer targets available to the agent at
            runtime.
          title: tool.config
        language:
          $ref: '#/components/schemas/LanguageConfig'
          description: Sets the default and supported languages for the agent.
          title: language.config
        channel:
          $ref: '#/components/schemas/ChannelConfig'
          description: Configures channel-specific settings.
          title: channel.config
      required:
        - personas
        - voice
        - runtime
        - tool
        - language
        - channel
      type: object
      description: ''
    Persona:
      properties:
        name:
          description: Display name of the persona shown to the user in conversation.
          type: string
        voice:
          description: Voice model to use for the persona.
          discriminator:
            mapping:
              operator: '#/components/schemas/OperatorVoice'
            propertyName: provider
          oneOf:
            - $ref: '#/components/schemas/OperatorVoice'
              title: operator.voice
      required:
        - name
        - voice
      type: object
      description: ''
    VoiceConfig:
      properties:
        ambient_sound:
          type: string
          default: null
          description: Background ambient sound for the agent's environment.
          enum:
            - office
        busy_sound:
          type: string
          default: null
          description: Sound played while the agent is thinking or performing tool calls.
          enum:
            - keyboard_typing
        boosted_keywords:
          description: Words to emphasize during speech transcription.
          items:
            type: string
          type: array
      required:
        - boosted_keywords
      type: object
      description: ''
    RuntimeConfig:
      properties:
        model:
          description: The language model to use for the agent.
          enum:
            - openai/gpt-4o
            - openai/gpt-4o-realtime
            - openai/gpt-realtime
            - openai/gpt-4.1
            - openai/gpt-4.1-mini
            - openai/gpt-5
            - openai/gpt-5-mini
            - google/gemini-2.5-flash
            - google/gemini-2.5-flash-lite
          type: string
        prompt:
          description: >-
            The prompt and model configuration used to drive the agent's
            behavior.
          discriminator:
            mapping:
              fixed: '#/components/schemas/FixedPrompt'
              routed: '#/components/schemas/RoutedPrompt'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/FixedPrompt'
              title: fixed.prompt
            - $ref: '#/components/schemas/RoutedPrompt'
              title: routed.prompt
        variables:
          description: Template variables that can be dynamically populated at runtime.
          items:
            $ref: '#/components/schemas/PromptVariable'
            title: prompt.variable
          type: array
      required:
        - model
        - prompt
        - variables
      type: object
      description: ''
    ToolConfig:
      properties:
        tools:
          description: List of tools the agent can use.
          items:
            discriminator:
              mapping:
                crm: '#/components/schemas/SyscallToolID'
                extapi: '#/components/schemas/ApiToolID'
                procedural: '#/components/schemas/ProceduralAgentToolID'
                syscall: '#/components/schemas/SyscallToolID'
                thirdparty: '#/components/schemas/ThirdPartyToolID'
              propertyName: ns
            oneOf:
              - $ref: '#/components/schemas/SyscallToolID'
                title: syscall.tool.id
              - $ref: '#/components/schemas/ApiToolID'
                title: api.tool.id
              - $ref: '#/components/schemas/ProceduralAgentToolID'
                title: procedural.agent.tool.id
              - $ref: '#/components/schemas/ThirdPartyToolID'
                title: third.party.tool.id
          type: array
        transfers:
          description: List of transfers the agent can make.
          items:
            $ref: '#/components/schemas/TransferID'
            title: transfer.id
          type: array
      required:
        - tools
        - transfers
      type: object
      description: ''
    LanguageConfig:
      properties:
        default_language:
          description: Default language for the agent.
          enum:
            - English
            - Spanish
          type: string
        supported_languages:
          description: Languages the agent can support.
          items:
            enum:
              - English
              - Spanish
            type: string
          type: array
      required:
        - default_language
        - supported_languages
      type: object
      description: ''
    ChannelConfig:
      properties:
        is_voicemail_enabled:
          description: Whether the agent will leave voicemails.
          type: boolean
      required:
        - is_voicemail_enabled
      type: object
      description: ''
    OperatorVoice:
      properties:
        provider:
          default: operator
          type: string
          enum:
            - operator
        id:
          enum:
            - Female 1
            - Female 2
            - Female 3
            - Male 1
            - Male 2
            - Male 3
          type: string
      required:
        - id
      type: object
      description: ''
    FixedPrompt:
      description: >-
        Prompt configuration for a conversational agent with a single static
        prompt.
      properties:
        text:
          description: The system prompt that guides the agent's behavior.
          type: string
        type:
          default: fixed
          description: Type of prompt. Set to 'fixed' for a static prompt.
          type: string
          enum:
            - fixed
      required:
        - text
      type: object
    RoutedPrompt:
      description: >-
        Prompt configuration that routes between multiple sub-prompts based on
        user intent.
      properties:
        text:
          description: The router prompt that determines which route to invoke.
          type: string
        routes:
          description: Available routes, each with its own system prompt.
          items:
            $ref: '#/components/schemas/RoutedPromptRoute'
            title: routed.prompt.route
          type: array
        type:
          default: routed
          description: Type of prompt. Set to 'routed' for intent-based routing.
          type: string
          enum:
            - routed
      required:
        - text
        - routes
      type: object
    PromptVariable:
      properties:
        name:
          description: The name of the variable, as referenced in the prompt template.
          type: string
        description:
          description: What this variable controls or represents in the prompt.
          type: string
        default_value:
          type: string
          default: null
          description: Default value if none is provided at runtime.
      required:
        - name
        - description
      type: object
      description: ''
    SyscallToolID:
      description: Identifier for a System tool.
      properties:
        ns:
          enum:
            - syscall
            - crm
          type: string
        name:
          description: Name of the tool.
          type: string
      required:
        - ns
        - name
      type: object
    ApiToolID:
      description: Identifier for an API tool.
      properties:
        ns:
          default: extapi
          type: string
          enum:
            - extapi
        entity_id:
          description: Unique identifier for the API tool.
          type: string
      required:
        - entity_id
      type: object
    ProceduralAgentToolID:
      description: Identifier for a procedural agent as tool.
      properties:
        ns:
          default: procedural
          type: string
          enum:
            - procedural
        entity_id:
          description: Unique identifier of the procedural agent as tool.
          type: string
      required:
        - entity_id
      type: object
    ThirdPartyToolID:
      description: Identifier for a third-party tool.
      properties:
        ns:
          default: thirdparty
          type: string
          enum:
            - thirdparty
        name:
          description: Name of the third-party tool.
          type: string
      required:
        - name
      type: object
    TransferID:
      properties:
        id:
          description: Unique identifier for the transfer.
          type: string
      required:
        - id
      type: object
      description: ''
    RoutedPromptRoute:
      properties:
        id:
          description: Unique identifier for the route.
          type: string
        name:
          description: Human-readable name for the route.
          type: string
        is_enabled:
          description: Whether this route is currently active.
          type: boolean
        description:
          description: Describes the use case or purpose of the route.
          type: string
        text:
          description: The system prompt text used when this route is selected.
          type: string
      required:
        - id
        - name
        - is_enabled
        - description
        - text
      type: object
      description: ''
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````