create-agent

创建 Bolna Agent

使用当前 API

• 端点：POST https://api.bolna.ai/v2/agent
• 身份验证：Authorization: Bearer $BOLNA_API_KEY
• 请求体根字段：agent_config 和 agent_prompts
• 响应：agent_id 和 status: created
• 新建 Agent 时不要使用已弃用的 /agent v1 端点。

最简创建流程

1. 确认用户已设置 BOLNA_API_KEY。
2. 收集：Agent 名称、用例、语言、欢迎消息、系统提示词、LLM 提供商/模型、语音/TTS 提供商、转录/STT 提供商、电话服务提供商，以及需要时的 webhook URL。
3. 除非用户明确要求提取、摘要或高级工作流，否则只构建一个 conversation 任务。
4. 在提示词中使用花括号添加动态变量，例如 {customer_name}。
5. 发起通话时，稍后通过 user_data 添加对应的值。
6. 配置保守的通话控制：静音后挂断、中断词、最长通话时长、语音信箱行为、入站通话限制。
7. POST 请求负载，然后保存返回的 agent_id。

请求结构

{
  "agent_config": {
    "agent_name": "Support Agent",
    "agent_welcome_message": "Hi {customer_name}, this is Tara from Acme.",
    "webhook_url": null,
    "agent_type": "other",
    "tasks": [
      {
        "task_type": "conversation",
        "tools_config": {
          "llm_agent": {},
          "synthesizer": {},
          "transcriber": {},
          "input": {},
          "output": {},
          "api_tools": null
        },
        "toolchain": {
          "execution": "parallel",
          "pipelines": [["transcriber", "llm", "synthesizer"]]
        },
        "task_config": {}
      }
    ],
    "ingest_source_config": null,
    "calling_guardrails": {
      "call_start_hour": 9,
      "call_end_hour": 18
    }
  },
  "agent_prompts": {
    "task_1": {
      "system_prompt": "You are a concise, helpful voice agent..."
    }
  }
}

必需的任务块

• llm_agent：普通提示词使用 simple_llm_agent，附加 RAG 时使用 knowledgebase_agent。实时通话使用 agent_flow_type: streaming。
• synthesizer：TTS 提供商、语音、模型、流式传输、缓冲区大小、音频格式。
• transcriber：STT 提供商、模型、语言、流式传输、采样率、编码、端点检测。
• input 和 output：电话服务提供商和音频格式。
• toolchain：通常使用一个管道：transcriber -> llm -> synthesizer。
• task_config：真人对话控制项，例如静音超时、中断阈值、附和语、语音信箱、通话最长时长、白名单，以及未知来电者的处理方式。

知识库

1. 使用 create-knowledgebase 技能创建或列出知识库。
2. 等待状态变为 processed。
3. 在 Agent 的 LLM 向量存储配置中使用返回的 vector_id。
4. 只有当语音 Agent 必须根据文档、常见问题、URL、政策或产品文档作答时，才使用知识库 Agent。

函数工具

当 Agent 必须转接通话、调用外部 HTTP API、获取或预订日历时段，或向 CRM 系统写入数据时，使用 setup-tools。函数架构应保持精简，包含清晰的说明和 JSON 参数。

创建复杂 Agent 前需阅读的内容

阅读 references/agent-config-fields.md，了解完整的字段指南、提供商选项、动态变量、RAG 配置和注意事项。

脚本

python3 create-agent/scripts/create_minimal_agent.py \
  --name "Demo Support Agent" \
  --welcome "Hi {customer_name}, how can I help?" \
  --prompt "You are a helpful support agent. Keep answers brief."

印地语 / 印度语言 Agent

为使用印地语服务印度来电者的 Agent：

{
  "agent_config": {
    "agent_name": "Hindi Support Agent",
    "agent_welcome_message": "नमस्ते {customer_name}, मैं Acme से तारा बोल रही हूँ।",
    "tasks": [{
      "task_type": "conversation",
      "tools_config": {
        "llm_agent": {
          "agent_type": "simple_llm_agent",
          "agent_flow_type": "streaming",
          "llm_config": {
            "provider": "openai", "family": "openai", "model": "gpt-4.1-mini",
            "max_tokens": 200, "temperature": 0.2
          }
        },
        "synthesizer": {
          "provider": "sarvam",
          "provider_config": { "voice": "meera", "model": "bulbul-v2" },
          "stream": true, "audio_format": "wav"
        },
        "transcriber": {
          "provider": "deepgram", "model": "nova-3",
          "language": "multi-hi", "stream": true,
          "encoding": "linear16", "sampling_rate": 16000, "endpointing": 700
        },
        "input":  { "provider": "plivo", "format": "wav" },
        "output": { "provider": "plivo", "format": "wav" }
      },
      "toolchain": { "execution": "parallel", "pipelines": [["transcriber","llm","synthesizer"]] }
    }]
  },
  "agent_prompts": { "task_1": { "system_prompt": "आप तारा हैं, Acme की Voice AI सहायक। एक बार में 2 से अधिक वाक्य न बोलें। ग्राहक की भाषा में जवाब दें।" } }
}

关键选择：

• Deepgram multi-hi STT 可妥善处理印地语和英语之间的语码转换（Hinglish）。
• Sarvam TTS 可提供自然的印地语发音。
• 印度 160 系列号码（160 = 交易类）使用 Plivo 电话服务。推广类 140 系列号码使用 Vobiz。
• 系统提示词使用天城文原文，绝不要使用英语谐音拼写。
• endpointing: 700 可适应印地语通话中常见的较长停顿。

完整的多语言指南请参阅 ../prompt-writing/references/multilingual.md。

多语言 Agent（一个 Agent，一次通话支持多种语言）

如果你希望一个 Agent接听一通可能在对话中途切换语言的电话，而不是每种语言配一个 Agent，请启用 multilingual_config。Bolna 会根据用户当前使用的语言，为每轮对话选择合适的 STT/TTS。

{
  "tools_config": {
    "llm_agent": { /* shared LLM across languages */ },
    "synthesizer": { /* default TTS — used when no per-language override fires */ },
    "transcriber": { /* default STT */ },
    "multilingual_config": {
      "enabled": true,
      "active_language": "hi",                          // language the call OPENS in
      "switch_tool_description": "Respond in the language the user is currently speaking. Default to Hindi.",
      "languages": {
        "hi": {
          "agent_name": "Vidya",                        // optional, advanced
          "system_prompt": "आप विद्या हैं... <full Hindi prompt>",
          "synthesizer": {
            "provider": "sarvam",
            "buffer_size": 220,
            "provider_config": { "model": "bulbul:v3", "voice": "Ashutosh", "voice_id": "ashutosh" }
          },
          "transcriber": { "provider": "elevenlabs", "model": "scribe_v2_realtime", "language": "hi" },
          "handoff_message": "एक मिनट, मैं {agent_name} से connect करती हूँ जो {language} बोलती हैं।"
        },
        "en": {
          "agent_name": "Vidya (English)",
          "system_prompt": "You are Vidya, a calm, warm voice agent... <full English prompt>",
          "synthesizer": {
            "provider": "cartesia",
            "buffer_size": 40,
            "provider_config": { "model": "sonic-3.5", "voice": "Callie - Encourager", "voice_id": "00a77add-48d5-4ef6-8157-71e5437b282d" }
          },
          "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
          "handoff_message": "One moment, connecting you with {agent_name} who speaks {language}."
        }
      }
    }
  }
}

容易忽略的规则：

规则	原因
languages.<code>.system_prompt 是完整的提示词，不是翻译文本。	每种语言都可以有自己的角色设定、异议处理表和说服逻辑。
你可以为不同语言搭配不同服务提供商——en 使用 Deepgram+Cartesia，hi 使用 ElevenLabs+Sarvam，nl 使用 Azure+ElevenLabs。	认为每个 Agent 只能使用一组 STT/TTS 是错误的。应为每种语言选择最合适的组合。
handoff_message 支持占位符 {agent_name} 和 {language}。	Agent 在通话中途切换语言时会播放此消息。
switch_tool_description 是控制面板中的 Language Switching Instructions 字段。	大模型会遵循此规则来判断是否切换语言。请明确说明：「使用用户当前所用的语言回复。默认使用印地语。」
active_language 决定通话开始时使用的语言。	选择置信度最高的默认语言；其余情况交由 switch_tool_description 处理。
task_config.call_hangup_message 和 task_config.check_user_online_message 可以是以语言代码为键的 dict（{"en": "...", "hi": "..."}）。agent_welcome_message 只能是 str——请使用 active_language 编写。	如果需要为不同语言设置欢迎语，请使用各语言的 system_prompt 开场内容，并在切换语言时使用相应语言的 handoff_message。
agent_name 和 handoff_message 会原样发送给呼叫者。	请填写真实内容——空字符串或无意义字符串（"qwegf iqghyf"）也会进入生产环境。

完整示例（Snabbit 风格，三种语言，每种语言使用独立的 STT/TTS）请参阅 references/multilingual-config.md。

第二项任务：通话后提取（summarization）

tasks[] 数组可以包含第二项任务，在通话结束后根据通话记录运行。这是 create-disposition 背后的底层机制。

{
  "tasks": [
    { "task_type": "conversation", /* the live call */ },
    {
      "task_type": "summarization",
      "toolchain": { "execution": "parallel", "pipelines": [["llm"]] },
      "tools_config": {
        "llm_agent": {
          "agent_type": "simple_llm_agent",
          "llm_config": {
            "provider": "openai",
            "model": "gpt-4o-mini",
            "max_tokens": 100,
            "temperature": 0.1,
            "request_json": true     // emit structured JSON instead of free text
          }
        }
      },
      "task_config": { "call_terminate": 90 }
    }
  ]
}

request_json: true 是生成结构化 extracted_data 的标志，可用于 webhook / GET /executions/{id}。处置结果（create-disposition）和旧版 gpt_assistants.custom_questions 都通过此任务实现。

task_config 的所有参数

task_config 块包含约 25 个字段，涉及延迟、中断、语音信箱、静音处理、呼入限制和噪声抑制。大多数默认值都很合理。请谨慎调整。

完整参考：references/task-config-fields.md。

知识库 Agent（RAG）

如果 Agent 必须依据文档（常见问题、政策、产品文档）作答：

{
  "tools_config": {
    "llm_agent": {
      "agent_type": "knowledgebase_agent",
      "agent_flow_type": "streaming",
      "llm_config": { "provider": "openai", "model": "gpt-4o", "max_tokens": 200, "temperature": 0.3 },
      "vector_store": {
        "provider": "lancedb",
        "provider_config": {
          "vector_ids": ["<rag_id_1>", "<rag_id_2>"],
          "similarity_top_k": 8
        }
      }
    }
  }
}

• 先通过 create-knowledgebase 创建知识库，并等待 status == "processed"。
• 使用 vector_ids[]（数组）将多个知识库关联到一个 Agent。
• 推荐知识库 Agent 使用 gpt-4o——它综合检索到的文本块的能力优于 gpt-4.1-mini。

语义路由（常见问题快速响应）

对于高频常见问题和政策拒绝，llm_agent.routes 可以通过预设答案快速响应常见问题——无需消耗大模型费用，延迟也几乎为零：

{
  "llm_agent": {
    "agent_type": "simple_llm_agent",
    "agent_flow_type": "streaming",
    "llm_config": { "provider": "openai", "model": "gpt-4.1-mini", "max_tokens": 200 },
    "routes": [
      {
        "name": "refund_policy",
        "utterances": ["what's your refund policy", "can I get a refund", "how do returns work"],
        "response": "We offer full refunds within 30 days of purchase. I can email you the policy document — want that?",
        "similarity_threshold": 0.85
      },
      {
        "name": "business_hours",
        "utterances": ["what are your hours", "when are you open", "operating hours"],
        "response": "We're open 9 AM to 7 PM IST, Monday through Saturday.",
        "similarity_threshold": 0.85
      }
    ]
  }
}

路由会在大模型运行之前触发。适用于常见问题、明确拒绝（定价、竞争对手相关问题）和稳定的政策答复。不要用于需要针对不同呼叫者动态调整的内容。

另请参阅

• references/agent-config-fields.md — 完整的字段参考。
• references/multilingual-config.md — 一个 Agent，多种语言，完整示例。
• references/task-config-fields.md — 每个 task_config 参数及其默认值和使用场景。
• make-call — 创建后如何实际拨打电话。
• bolna-graph-agents — 从单个提示词切换为基于节点的流程。
• setup-tools — 添加 transfer_call、自定义 HTTP、Cal.com 预约。
• create-knowledgebase — 为知识库 Agent 生成 vector_id。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/providers-matrix.md — 选择 LLM × STT × TTS × 电话服务组合。
• ../prompt-writing — 如何编写 system_prompt。