manage-agents

管理 Bolna Agent

端点

• 列出 Agent：GET https://api.bolna.ai/v2/agent/all
• 获取 Agent：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}
• 删除 Agent：DELETE https://api.bolna.ai/v2/agent/{agent_id}
• 停止一个 Agent 的排队呼叫：POST https://api.bolna.ai/v2/agent/{agent_id}/stop

始终发送 Authorization: Bearer $BOLNA_API_KEY。对 PUT 和 PATCH 请求发送 Content-Type: application/json。

工作流

1. 更改 Agent 前，先使用列表或获取接口。
2. 对提示词、欢迎消息、Webhook URL、语音合成器、入站来源配置或 SIP 电话服务提供商进行小幅修改时，优先使用 PATCH。
3. 只有在拥有完整的目标 Agent 文档时才使用 PUT。不完整的 PUT 可能会丢弃现有的嵌套配置。
4. 进行破坏性更改前，保存一份现有配置的副本。
5. 如果不应执行排队的呼叫，请在删除前使用停止接口。
6. 只有在确认用户了解此操作会清理 Agent 及相关运营数据后，才删除 Agent。

列出 Agent

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 中继电话号码映射到入站呼叫，或者将中继 DID 用作出站呼叫的主叫 ID。

停止排队的呼叫

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

这会停止该 Agent 的排队呼叫。此操作不同于停止单个呼叫或单个批次。

删除 Agent

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 可取消单个 Agent 的排队呼叫，而无需删除该 Agent。
• bolna-graph-agents — 用于编辑 llm_agent.nodes 和边结构。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/bolna-core.md — 认证、请求头和分页默认设置。