create-agent

Bolna エージェントの作成

現在の API を使用する

• エンドポイント：POST https://api.bolna.ai/v2/agent
• 認証：Authorization: Bearer $BOLNA_API_KEY
• リクエストボディのルート：agent_config と agent_prompts
• レスポンス：agent_id と status: created
• 新しいエージェントには、非推奨の /agent v1 エンドポイントを使用しないでください。

最小限の作成フロー

1. ユーザーが BOLNA_API_KEY を設定していることを確認します。
2. エージェント名、ユースケース、言語、ウェルカムメッセージ、システムプロンプト、LLM プロバイダー／モデル、音声／TTS プロバイダー、文字起こし／STT プロバイダー、テレフォニープロバイダー、必要に応じて Webhook URL を確認します。
3. ユーザーが抽出、要約、高度なフローを明示的に求めている場合を除き、conversation タスクを 1 つ作成します。
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 のパイプラインを 1 つ設定します。
• task_config：無音タイムアウト、割り込みしきい値、相づち、留守番電話、通話の最大時間、許可リスト、未登録の発信者の動作など、人間との会話に関する制御を設定します。

ナレッジベース

1. create-knowledgebase スキルを使ってナレッジベースを作成または一覧表示します。
2. ステータスが processed になるまで待ちます。
3. 返された vector_id をエージェントの LLM ベクトルストア設定で使用します。
4. 音声エージェントがドキュメント、FAQ、URL、ポリシー、または製品ドキュメントに基づいて回答する必要がある場合にのみ、ナレッジベースエージェントを使用します。

関数ツール

エージェントが通話の転送、外部 HTTP API の呼び出し、カレンダーの空き枠の取得や予約、CRM システムへの書き込みを行う必要がある場合は、setup-tools を使用します。関数スキーマは範囲を絞り、明確な説明と JSON パラメーターを指定してください。

複雑なエージェントを作成する前に読む項目

フィールドの詳細、プロバイダーの選択肢、動的変数、RAG の接続方法、注意点については、references/agent-config-fields.md を読んでください。

スクリプト

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_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 は、ヒンディー語と英語のコードスイッチング（ヒングリッシュ）を適切に処理します。
• ネイティブなヒンディー語の発音には Sarvam TTS を使用します。
• インドの 160 系列番号（160 はトランザクション用）には Plivo テレフォニーを使用します。140 系列のプロモーション用には Vobiz を使用してください。
• システムプロンプトにはネイティブのデーヴァナーガリー文字を使用し、英語の音声表記は使用しないでください。
• endpointing: 700 は、ヒンディー語の通話でよく見られる長めの間に対応します。

多言語対応の手順全体については、../prompt-writing/references/multilingual.md を参照してください。

多言語エージェント（1つのエージェントで、1回の通話中に複数の言語に対応）

言語ごとにエージェントを用意するのではなく、会話中に言語が切り替わる可能性のある通話を1つのエージェントで担当したい場合は、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を使えます。	エージェントごとにSTT/TTSのペアを1つだけ設定するという考え方は適切ではありません。言語ごとに最適なものを選んでください。
handoff_messageは、プレースホルダー{agent_name}と{language}に対応しています。	エージェントが通話中に言語を切り替える際に再生されます。
switch_tool_descriptionは、ダッシュボードのLanguage Switching Instructionsフィールドです。	これは、言語を切り替えるかどうかを判断するためにLLMが従うルールです。「ユーザーが現在使っている言語で応答してください。デフォルトはヒンディー語です」のように、明確に指定してください。
active_languageは、通話を開始する言語を決定します。	信頼度が最も高いデフォルトの言語を選び、残りはswitch_tool_descriptionに任せてください。
task_config.call_hangup_messageとtask_config.check_user_online_messageには、言語コードをキーとする辞書（{"en": "...", "hi": "..."}）を指定できます。agent_welcome_messageはstrのみです。active_languageの言語で記述してください。	言語ごとのウェルカムメッセージには、各言語のsystem_promptの冒頭部分と、言語切り替え用の言語別handoff_messageを利用してください。
agent_nameとhandoff_messageは、そのまま発信者に送られます。	実際に使う値を設定してください。空の文字列や無意味な文字列（"qwegf iqghyf"）が本番環境に届いてしまいます。

言語ごとにSTT/TTSを設定した3言語対応の詳しい実例（Snabbit形式）については、references/multilingual-config.mdを参照してください。

2つ目のタスク：通話後の抽出（summarization）

tasks[]配列には、通話終了後に文字起こしデータを対象として実行する2つ目のタスクを含められます。これは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は、Webhook／GET /executions/{id}向けの構造化されたextracted_dataを生成するフラグです。Disposition（create-disposition）と従来のgpt_assistants.custom_questionsは、どちらもこのタスクを利用します。

task_configの全設定項目

task_configブロックには、遅延、割り込み、留守番電話、無音処理、着信制限、ノイズ抑制をカバーする約25個のフィールドがあります。ほとんどのデフォルト値は適切です。変更する場合は、意図を持って調整してください。

詳細なリファレンス：references/task-config-fields.md。

ナレッジベースエージェント（RAG）

エージェントがドキュメント（FAQ、ポリシー、製品ドキュメント）に基づいて回答する必要がある場合：

{
  "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[]（配列）を使うと、1つのエージェントに複数のナレッジベースを紐付けられます。
• ナレッジベースエージェントにはgpt-4oを推奨します。取得したチャンクを横断して統合する能力が、gpt-4.1-miniより優れています。

セマンティックルート（FAQのショートサーキット）

大量に寄せられるFAQやポリシーに基づく回答拒否には、llm_agent.routesを使って、よくある質問に事前定義済みの回答を返すショートサーキットを設定できます。LLMのコストはゼロで、遅延もほぼゼロです。

{
  "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
      }
    ]
  }
}

ルートはLLMの実行前に適用されます。FAQ、明確な回答拒否（価格、競合他社に関する質問）、変わることのないポリシー回答に使用してください。発信者ごとに動的な内容が必要なケースには使用しないでください。

関連項目

• references/agent-config-fields.md — すべてのフィールドのリファレンスです。
• references/multilingual-config.md — 1 つのエージェントで複数の言語に対応する、完全な実例です。
• references/task-config-fields.md — 各 task_config の設定項目について、デフォルト値と使用例を紹介します。
• make-call — 作成後に実際に発信する方法です。
• bolna-graph-agents — 単一のプロンプトからノードベースのフローに切り替えます。
• setup-tools — transfer_call、カスタム HTTP、Cal.com の予約を追加します。
• create-knowledgebase — ナレッジベースエージェントで使用する vector_id を生成します。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/providers-matrix.md — LLM × STT × TTS × テレフォニーの組み合わせを選ぶ方法です。
• ../prompt-writing — system_prompt の書き方です。