业务平台 · Agent 列表 API

供运营管理后台等业务系统查询聊天机器人已配置的 hqharness Agent 列表。 响应中不包含 api_key，仅返回 id、名称、连接参数等元数据。 鉴权方式与 用户同步、聊天记录 API 一致， 使用 X-Chatbot-Webhook-Secret 请求头。

接口基址：/api/public/chatbot/agents

鉴权

请求头	必填	说明
X-Chatbot-Webhook-Secret	是	与聊天机器人「用户同步」配置的 Webhook 密钥一致（环境变量 PLATFORM_SYNC_WEBHOOK_SECRET 或管理页保存的值）

查询 Agent 列表

Query 参数

参数	类型	说明
enabled 可选	boolean	按启用状态过滤：true 仅返回已启用 Agent；false 仅返回已禁用；不传则返回全部。

响应字段

字段	类型	说明
agents	array	Agent 列表，按 id 升序
agents[].id	long	Agent ID，跟进人 Agent 配置与默认兜底绑定均引用此 id
agents[].name	string	显示名称
agents[].host	string	hqharness 主机
agents[].prefix	string	通道 prefix
agents[].appId	string	应用 ID
agents[].restScheme	string	REST 协议，如 https
agents[].wsScheme	string	WebSocket 协议，如 wss
agents[].defaultGroup	string | null	默认 group
agents[].defaultModel	string | null	默认 model
agents[].enabled	boolean	是否启用
agents[].hasApiKey	boolean	是否已配置 api_key（不返回密钥本身）

响应示例

{
  "agents": [
    {
      "id": 1,
      "name": "客服 Agent",
      "host": "hqh.baidehealth.com",
      "prefix": "chatbot",
      "appId": "chatbot",
      "restScheme": "https",
      "wsScheme": "wss",
      "defaultGroup": null,
      "defaultModel": null,
      "enabled": true,
      "hasApiKey": true
    }
  ]
}

请求示例

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/agents' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>'

仅查询已启用 Agent

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/agents' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>' \
  --data-urlencode 'enabled=true'

错误码

HTTP	说明
401	缺少或错误的 X-Chatbot-Webhook-Secret
503	Webhook 未配置

前置条件

• 聊天机器人已启用企微通道（WECOM_ENABLED=true）
• 已在「用户同步」页配置 Webhook 密钥；业务平台调用时使用相同密钥
• Agent 配置在主平台 · Agent 管理中维护

相关页面：跟进人 Agent（按企微跟进人指定 Agent）； 内部管理接口为 /api/bindings（需登录，含增删改）。