> ## 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. # Get a conversational agent ## OpenAPI ````yaml api-reference/openapi3.json get /conversational_agents/{id} 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/{id}: get: tags: - Conversational agents summary: Get 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' - name: id in: path required: true schema: description: >- The ID of the agent to retrieve. Use `ca_8qm9JBCiTe7` for the latest version, or `ca_8qm9JBCiTe7@v2` for a specific version. type: string description: >- The ID of the agent to retrieve. Use `ca_8qm9JBCiTe7` for the latest version, or `ca_8qm9JBCiTe7@v2` for a specific version. 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 name: description: Human-readable name for the agent. type: string description: description: Description of the agent. type: string version_status: description: >- Status of this agent version: 'released', 'draft', or 'archived'. enum: - released - draft - archived type: string config: $ref: '#/components/schemas/ConversationalAgentConfig' description: >- Full configuration for the agent (e.g. voice, runtime, tools). title: conversational.agent.config postprocess_agents: description: >- List of postprocessing procedural agent IDs that run after the conversation ends, e.g. `["pa_8qm9JBCiTe7"]` items: type: string type: array required: - id - version_id - name - description - version_status - config - postprocess_agents type: object '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 ````