CreateAgentRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/call2me-app/json-schema/call2me-app-create-agent-request-schema.json",
  "title": "CreateAgentRequest",
  "description": "Request to create a new voice agent.",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/call2me-app-openapi.json#/components/schemas/CreateAgentRequest",
  "properties": {
    "agent_name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "title": "Agent Name",
      "description": "Human-readable name for the agent"
    },
    "voice_id": {
      "type": "string",
      "title": "Voice Id",
      "description": "Voice identifier (e.g., 'openai-nova', 'azure-tr-emel')"
    },
    "response_engine": {
      "anyOf": [
        {
          "$ref": "#/$defs/BuiltinLLMEngine"
        },
        {
          "$ref": "#/$defs/CustomLLMEngine"
        }
      ],
      "title": "Response Engine",
      "description": "LLM configuration (built-in or custom)"
    },
    "language": {
      "type": "string",
      "title": "Language",
      "description": "BCP-47 language code",
      "default": "tr-TR"
    },
    "voice_speed": {
      "type": "number",
      "maximum": 2.0,
      "minimum": 0.5,
      "title": "Voice Speed",
      "description": "Voice playback speed",
      "default": 1.0
    },
    "responsiveness": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Responsiveness",
      "description": "How quickly agent responds (0=slow, 1=immediate)",
      "default": 0.5
    },
    "interruption_sensitivity": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Interruption Sensitivity",
      "description": "How easily user can interrupt (0=hard, 1=easy)",
      "default": 0.5
    },
    "enable_backchannel": {
      "type": "boolean",
      "title": "Enable Backchannel",
      "description": "Enable 'uh-huh', 'hmm' responses",
      "default": true
    },
    "backchannel_frequency": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Backchannel Frequency",
      "description": "How often to backchannel (0=never, 1=always)",
      "default": 0.8
    },
    "backchannel_words": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Backchannel Words",
      "description": "Custom backchannel words (empty = use defaults for language)"
    },
    "begin_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Begin Message",
      "description": "First message when call starts (used when begin_message_mode='static')"
    },
    "begin_message_mode": {
      "type": "string",
      "title": "Begin Message Mode",
      "description": "'static': use begin_message as-is, 'dynamic': LLM generates greeting based on system prompt and call context",
      "default": "dynamic"
    },
    "reminder_message_frequency_ms": {
      "type": "integer",
      "maximum": 60000.0,
      "minimum": 3000.0,
      "title": "Reminder Message Frequency Ms",
      "description": "Send reminder after this much silence (ms)",
      "default": 10000
    },
    "reminder_max_count": {
      "type": "integer",
      "maximum": 5.0,
      "minimum": 0.0,
      "title": "Reminder Max Count",
      "description": "Max reminder messages before ending call (0=disabled)",
      "default": 2
    },
    "end_call_after_silence_ms": {
      "type": "integer",
      "maximum": 120000.0,
      "minimum": 10000.0,
      "title": "End Call After Silence Ms",
      "description": "End call after this much silence (ms)",
      "default": 30000
    },
    "max_call_duration_ms": {
      "type": "integer",
      "maximum": 7200000.0,
      "minimum": 60000.0,
      "title": "Max Call Duration Ms",
      "description": "Maximum call duration (ms)",
      "default": 3600000
    },
    "enable_recording": {
      "type": "boolean",
      "title": "Enable Recording",
      "description": "Enable call recording",
      "default": false
    },
    "enable_vcon_export": {
      "type": "boolean",
      "title": "Enable Vcon Export",
      "description": "Allow exporting this agent's calls as vCon containers",
      "default": false
    },
    "webhook_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Webhook Url",
      "description": "URL for webhook events"
    },
    "transfer_targets": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Transfer Targets",
      "description": "Transfer targets: [{'name': 'Support', 'type': 'phone|sip|agent|external|queue', 'value': '...'}]"
    },
    "post_call_extraction": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Post Call Extraction",
      "description": "Fields to extract from call (e.g., [{'name': 'customer_name', 'type': 'string', 'description': 'Customer name'}])"
    },
    "post_call_extraction_model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Post Call Extraction Model",
      "description": "LLM model for post-call extraction",
      "default": "gpt-4o-mini"
    },
    "post_call_actions": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Post Call Actions",
      "description": "Actions triggered after call analysis. Format:\n        [{'type': 'schedule_call', 'condition': 'callback_requested == true', 'config': {'delay_minutes': 60}},\n         {'type': 'webhook', 'condition': 'sale_completed == true', 'config': {'url': 'https://...'}},\n         {'type': 'schedule_call', 'condition': 'appointment_time != null', 'config': {'use_field': 'appointment_time'}}]\n        Types: schedule_call, webhook, tag_contact"
    },
    "knowledge_base_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Knowledge Base Ids",
      "description": "Knowledge base IDs linked to this agent for RAG"
    },
    "kb_chunks_count": {
      "type": "integer",
      "maximum": 10.0,
      "minimum": 1.0,
      "title": "Kb Chunks Count",
      "description": "Number of chunks to retrieve from knowledge base (1-10)",
      "default": 3
    },
    "kb_similarity_threshold": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Kb Similarity Threshold",
      "description": "Minimum similarity score for KB results (0.0-1.0)",
      "default": 0.6
    },
    "background_sound": {
      "type": "string",
      "enum": [
        "none",
        "office",
        "keyboard"
      ],
      "title": "Background Sound",
      "description": "Background ambient sound during calls",
      "default": "none"
    },
    "end_call_mode": {
      "type": "string",
      "enum": [
        "static",
        "dynamic"
      ],
      "title": "End Call Mode",
      "description": "End call message mode: 'static' for fixed message, 'dynamic' for AI-generated based on conversation",
      "default": "static"
    },
    "end_call_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Call Message",
      "description": "Static goodbye message (used when end_call_mode='static'). If empty, uses default localized message."
    },
    "end_call_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Call Prompt",
      "description": "Prompt for generating dynamic goodbye message (used when end_call_mode='dynamic'). Example: 'Konuşmayı özetle ve nazik bir veda mesajı söyle.'"
    },
    "voicemail_detection_enabled": {
      "type": "boolean",
      "title": "Voicemail Detection Enabled",
      "description": "Enable voicemail/answering machine detection",
      "default": false
    },
    "voicemail_detection_timeout_ms": {
      "type": "integer",
      "maximum": 15000.0,
      "minimum": 2000.0,
      "title": "Voicemail Detection Timeout Ms",
      "description": "How long after the greeting to listen for an answering-machine greeting (ms). Detection is phrase-based; silence alone is not voicemail.",
      "default": 5000
    },
    "voicemail_action": {
      "type": "string",
      "enum": [
        "hangup",
        "leave_message"
      ],
      "title": "Voicemail Action",
      "description": "Action when voicemail detected: 'hangup' = end call, 'leave_message' = play message and hang up",
      "default": "hangup"
    },
    "voicemail_message": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "title": "Voicemail Message",
      "description": "Message to leave on voicemail (used when voicemail_action='leave_message')"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata",
      "description": "Custom metadata for the agent"
    }
  },
  "type": "object",
  "required": [
    "agent_name",
    "voice_id",
    "response_engine"
  ],
  "$defs": {
    "BuiltinLLMEngine": {
      "properties": {
        "type": {
          "type": "string",
          "const": "call2me-llm",
          "title": "Type",
          "default": "call2me-llm"
        },
        "system_prompt": {
          "type": "string",
          "title": "System Prompt",
          "description": "System prompt that defines agent behavior"
        },
        "llm_provider": {
          "type": "string",
          "enum": [
            "openai",
            "gemini",
            "anthropic",
            "openrouter"
          ],
          "title": "Llm Provider",
          "description": "LLM provider to use",
          "default": "openrouter"
        },
        "llm_model": {
          "type": "string",
          "title": "Llm Model",
          "description": "Model identifier",
          "default": "gpt-4-turbo"
        },
        "temperature": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.0,
          "title": "Temperature",
          "description": "Sampling temperature",
          "default": 0.7
        },
        "engine": {
          "type": "string",
          "enum": [
            "cascade",
            "realtime"
          ],
          "title": "Engine",
          "description": "Voice engine: cascade (STT→LLM→TTS) or realtime (GPT Realtime speech-to-speech).",
          "default": "cascade"
        },
        "max_tokens": {
          "type": "integer",
          "maximum": 4096.0,
          "minimum": 1.0,
          "title": "Max Tokens",
          "description": "Maximum tokens in response",
          "default": 500
        },
        "builtin_functions": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Builtin Functions",
          "description": "Enabled built-in functions: end_call, transfer_call, hold_call, dtmf_input"
        },
        "functions": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Functions",
          "description": "Function definitions for tool calling"
        }
      },
      "type": "object",
      "required": [
        "system_prompt"
      ],
      "title": "BuiltinLLMEngine",
      "description": "Built-in LLM configuration using platform's LLM service."
    },
    "CustomLLMEngine": {
      "properties": {
        "type": {
          "type": "string",
          "const": "custom-llm",
          "title": "Type",
          "default": "custom-llm"
        },
        "llm_websocket_url": {
          "type": "string",
          "title": "Llm Websocket Url",
          "description": "WebSocket URL for custom LLM server"
        }
      },
      "type": "object",
      "required": [
        "llm_websocket_url"
      ],
      "title": "CustomLLMEngine",
      "description": "Custom LLM configuration via WebSocket."
    }
  }
}