manage-agents

Bolna エージェントを管理する

エンドポイント

• エージェント一覧：GET https://api.bolna.ai/v2/agent/all
• エージェントを取得：GET https://api.bolna.ai/v2/agent/{agent_id}
• 全体を更新：PUT https://api.bolna.ai/v2/agent/{agent_id}
• 部分更新：PATCH https://api.bolna.ai/v2/agent/{agent_id}
• エージェントを削除：DELETE https://api.bolna.ai/v2/agent/{agent_id}
• 1つのエージェントのキュー内の通話を停止：POST https://api.bolna.ai/v2/agent/{agent_id}/stop

常に Authorization: Bearer $BOLNA_API_KEY を送信してください。PUT と PATCH では Content-Type: application/json を送信してください。

ワークフロー

1. エージェントを変更する前に、一覧表示または取得を行います。
2. プロンプト、ウェルカムメッセージ、Webhook URL、シンセサイザー、着信ソース設定、または SIP テレフォニープロバイダーの小さな変更には、PATCH を優先してください。
3. PUT は、目的のエージェントドキュメント全体が揃っている場合にのみ使用してください。一部のみの PUT では、既存のネストされた設定が失われることがあります。
4. 破壊的な変更を行う前に、既存の設定のコピーを保存してください。
5. キュー内の通話を実行させたくない場合は、削除前に停止してください。
6. エージェントと関連する運用データが削除されることをユーザーが理解していると確認してから、削除してください。

エージェント一覧

curl --request GET \
  --url https://api.bolna.ai/v2/agent/all \
  --header "Authorization: Bearer $BOLNA_API_KEY"

プロンプトまたはウェルカムメッセージの部分更新

curl --request PATCH \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_config": {
      "agent_name": "Support Agent",
      "agent_welcome_message": "Hi {customer_name}, this is Tara from Acme."
    },
    "agent_prompts": {
      "task_1": {
        "system_prompt": "You are a concise support agent. Ask one question at a time."
      }
    }
  }'

SIP テレフォニープロバイダーの部分更新

curl --request PATCH \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agent_config":{"telephony_provider":"sip-trunk"}}'

この後、着信通話には setup-inbound を使用して SIP トランクの電話番号をマッピングするか、発信者 ID としてトランクの DID を使用します。

キュー内の通話を停止

curl --request POST \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID/stop" \
  --header "Authorization: Bearer $BOLNA_API_KEY"

これにより、そのエージェントのキュー内の通話が停止します。1件の通話または1つのバッチを停止する操作とは異なります。

エージェントを削除

curl --request DELETE \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY"

PUT と PATCH の違い

条件	使用するもの
名前の変更、音声の差し替え、Webhook URL の更新、システムプロンプトの変更、task_config フラグの切り替え	PATCH
バックアップしたドキュメントを使用した agent_config の全面的な置き換え	PUT

PUT には 完全な agent_config 本文が必要です。省略した項目はすべて削除されます。よくある不具合：部分的な本文で PUT すると、tools_config.api_tools または ingest_source_config が失われます。一部のフィールドしか把握していない場合は、PATCH を優先してください。

関連項目

• create-agent — 初期作成用。PUT が想定するものと同じ形式です。
• make-call — POST /v2/agent/{id}/stop は、エージェントを削除せずに、そのエージェントのキュー内の通話をキャンセルします。
• bolna-graph-agents — llm_agent.nodes とエッジ構造を編集する場合に使用します。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/bolna-core.md — 認証、ヘッダー、ページネーションのデフォルト設定。