Create Agent

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Display name for the agent"
    },
    "description": {
      "type": "string",
      "description": "Internal description of what the agent does"
    },
    "agent_type": {
      "type": "string",
      "description": "One of: Single_Prompt_Agent (default, one system prompt), Conversational_Flow_Agent (CFA — a more freeform persona-driven agent built from agent_identity + agent_background instead of a single scripted prompt), or IVR_Agent (a DTMF touch-tone menu — 'press 1 for sales' — that plays pre-rendered static audio and routes by keypad, with no LLM/STT/TTS until it optionally hands off to another agent). If you're building a CFA step by step with the user: first ask what the agent's role/identity is (who it is, its purpose), then what background/context it should know, then any specific behavior rules — set agent_identity, agent_background, and prompt_text from those answers respectively. Both agent_identity and agent_background are REQUIRED (non-empty) when agent_type is Conversational_Flow_Agent — the call fails otherwise. When agent_type is IVR_Agent you must also supply ivr_menu (see below); prompt_text/language_id/voice_id are still required (the voice renders the menu audio at publish)."
    },
    "ivr_menu": {
      "type": "object",
      "additionalProperties": {},
      "description": "Menu tree for an IVR_Agent (ignored for other agent types). Shape: { entry_node: <node id the call starts on>, nodes: { <node id>: <node> } }. Each node is { kind, prompt_text, no_input_prompt_text?, edges?, target_agent_id?, fallback_dynamic_variables? }. kind is one of: 'menu' (plays prompt_text, then routes on the caller's keypress via edges), 'collect' (gathers digits, e.g. an account number), 'connect_agent' (hands the live call off in-process to another agent — set target_agent_id to that agent's id, agent_ prefix ok; the target must be a NON-IVR agent in the same org that already has a published version. Also set fallback_dynamic_variables: a flat { variableName: value } map giving a fallback value for EVERY dynamic variable the target agent uses (its {{tokens}} plus any keys in its default_dynamic_variables) — publish is REJECTED unless each one has a non-empty value. These fill the transferred-to agent's prompt when the live call doesn't carry the value; the live call's own variables and any IVR-collected digits still take precedence at handoff), 'promote' (upgrades the call to a full AI voice agent), or 'hangup' (plays an optional farewell then ends the call). edges is a map of pressed digit -> target node id, e.g. { \"1\": \"sales\", \"2\": \"support\" } — every target must be a defined node. IMPORTANT: all IVR prompts must be STATIC text — no {{dynamic_variable}} tokens (they'd be spoken literally; publish rejects them). The menu is validated and its audio pre-rendered at publish, not at create/update, so an invalid menu surfaces when you call publish_agent."
    },
    "agent_identity": {
      "type": "string",
      "description": "Required (non-empty) when agent_type is Conversational_Flow_Agent — who the agent is and its role/purpose. Not used by Single_Prompt_Agent."
    },
    "agent_background": {
      "type": "string",
      "description": "Required (non-empty) when agent_type is Conversational_Flow_Agent — background/context the agent should know. Not used by Single_Prompt_Agent."
    },
    "folder_id": {
      "type": "string",
      "description": "Folder ID to file this agent under, e.g. from list_organization_folders"
    },
    "prompt_text": {
      "type": "string",
      "description": "The agent's system/behavior prompt (required)"
    },
    "welcome_message": {
      "type": "string",
      "description": "First thing the agent says when a call connects"
    },
    "language_id": {
      "type": "string",
      "description": "Language ID, e.g. lang_abc123 — from list_languages (required)"
    },
    "secondary_language_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 3,
      "description": "Up to 3 further language IDs (lang_...) the agent also answers in — from list_languages. The chosen voice must speak every one of them; any it cannot speak is dropped on save. Order matters: speech language hints follow it."
    },
    "language_default_message": {
      "type": "string",
      "description": "Sentence spoken, in the primary language voice, when a caller uses a language outside the primary and secondaries. Omit to let the agent answer normally."
    },
    "voice_id": {
      "type": "string",
      "description": "Voice ID, e.g. voice_abc123 — from list_voices (required)"
    },
    "llm_id": {
      "type": "string",
      "description": "LLM ID, e.g. llm_abc123 — from list_llms"
    },
    "transcriber_id": {
      "type": "string",
      "description": "Transcriber ID, e.g. trs_abc123 — from list_transcribers"
    },
    "extra_config": {
      "type": "object",
      "additionalProperties": {},
      "description": "Any other CreateAgentDto/UpdateAgentDto field not listed above (voice_speed, kb_max_chunks, fallback settings, etc.). ID-shaped fields are normalized the same as the named fields above — pass them in their normal prefixed form as returned by other tools: knowledge_base_ids (kb_..., from list_knowledge_base_documents), inbound_phone_number_id/outbound_phone_number_id (phn_...), webhook_id (webhook_...), llm_fallback_model/fall_back_llm_id/post_call_analysis_llm_id (llm_...), stt_fallback_transcriber_id (trs_...), fallback_voices[].voice_id (voice_...). Everything else is passed through as-is. Use get_agent on a similar existing agent of the SAME agent_type to see the full field shape first — do not copy fields from a different agent_type. In particular, default_dynamic_variables.agent_transfer_destinations only applies to Conversational_Flow_Agent (its call-transfer node) and will be rejected on a Single_Prompt_Agent."
    }
  },
  "required": [
    "prompt_text",
    "language_id",
    "voice_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "description": "The new agent ID, prefixed agent_"
    },
    "agent_type": {
      "description": "Single_Prompt_Agent, Conversational_Flow_Agent, or IVR_Agent"
    },
    "current_version_number": {
      "description": "Version number currently considered current"
    },
    "versions": {
      "description": "Versions of the new agent, each with its prompt, functions, and settings"
    },
    "prompt_health": {
      "description": "Prompt size against the selected model's latency bands: status (green/yellow/red/not_applicable), prompt_tokens (an estimate), limit_tokens, system_prompt_reserved_tokens, limited_by, comment. A prompt past the hard ceiling is rejected outright rather than reported here."
    }
  },
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_agent",
    "arguments": {
      "prompt_text": "Describe how the agent should behave.",
      "language_id": "lang_abc123",
      "voice_id": "voice_abc123"
    }
  }
}