用 PolyAI REST API 程序化构建和运营智能体

REST API 的定位

ADK 和 Agent Studio 适合构建和维护智能体——把配置拉下来、编辑、推回去。REST API 适合程序化运营——用代码在运行时创建智能体、触发 Flow、查询会话记录、拉取分析数据。

两种方式不是替代关系：

场景	推荐用
开发团队写 Python 函数、调 Flow 细节	ADK
产品经理 / 运营配置话题、测试	Agent Studio
另一个系统想实时创建 / 配置智能体	REST API
批量拉取会话数据做自定义分析	REST API
CI/CD 流水线触发部署	REST API

认证

所有 API 请求都需要 API Key 放在 HTTP Header 里：

Authorization: Bearer <your-api-key>
Content-Type: application/json

API Key 从 studio.poly.ai → 用户设置 → API Keys 页面生成，和 ADK 用的是同一个 Key。

主要 API 端点

分组	核心端点	典型用途
智能体管理	`POST /agents`、`GET /agents`、`PUT /agents/{id}`	程序化创建、查询、更新智能体
Flow 操作	`POST /agents/{id}/flows`、`PUT /flows/{flow-id}`	程序化创建 / 更新 Flow
话题操作	`POST /agents/{id}/topics`	批量导入知识话题
触发对话	`POST /agents/{id}/conversations`	外部系统启动一个对话会话
会话查询	`GET /agents/{id}/conversations`	拉取历史会话记录做分析
分析数据	`GET /agents/{id}/analytics/*`	拉取 Dashboard 上的各类指标
部署操作	`POST /agents/{id}/deployments/publish`	程序化触发发布到 Live
号码管理	`GET /agents/{id}/numbers`	查询绑定的电话号码

和 ADK 的配合

REST API 和 ADK 可以配合使用。一个典型场景：

开发团队用 ADK 在本地开发好一个智能体的完整配置，push 到 Studio
运营系统用 REST API 拉取该智能体的会话数据、分析指标，做自定义报表
CI/CD 流水线在代码合入后，用 REST API 触发发布到 Live

ADK 的 Python 函数也可以调用外部 API——比如你的 Python 转场函数可以调用 CRM 的 REST API 查客户数据，CRM 系统反过来也可以用 PolyAI 的 REST API 触发智能体对话。

无 SDK，纯 REST

PolyAI 目前没有官方 SDK——API 就是纯 REST + JSON，任何能发 HTTP 请求的语言都可以调用。这降低了集成门槛，你不需要安装额外依赖。

Python 调用示例：

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

# 拉取最近 100 条会话
resp = requests.get("https://api.poly.ai/v1/agents/{agent-id}/conversations?limit=100", headers=headers)
conversations = resp.json()

和 MCP 协议

PolyAI 也是较早支持 MCP（Model Context Protocol） 的企业平台——MCP 让 LLM coding assistant（比如 Claude Desktop、Cursor）可以直接调用 PolyAI 的 REST API，把"用 AI 改智能体配置"的体验无缝嵌入到 IDE 里。这和 Agent Builder（Studio 里的 AI 助手）是互补——一个在 Studio 里，一个在 IDE 里。