把 OpenAPI 接口描述交给 AI 编程工具，生成集成代码。公开 API、工作台和 MCP 管理入口使用同一工作区资源与权限。
| 功能 | 接口 |
|---|---|
| 可复用工具 | GET / POST /api/v1/voice/tools |
| 查看 / 修改 / 删除工具 | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| 预览或实测工具 | POST /api/v1/voice/tools/{id}/test |
| 绑定到 Agent | PUT /api/v1/voice/agents/{id}/tools |
| 知识库 | GET / POST /api/v1/voice/knowledge-bases |
| 查看 / 修改 / 删除知识库 | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| 添加 / 列出文档 | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| 查看 / 删除文档 | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| 通话事件订阅 | GET / POST /api/v1/voice/webhooks |
| 查看 / 修改 / 删除订阅 | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| 发送带签名的测试事件 | POST /api/v1/voice/webhooks/{id}/test |
| 发现外部 MCP 工具 | POST /api/v1/voice/mcp/discover |
| MCP 管理入口 | /api/v1/voice/mcp |
通过 POST /tools 注册自己的 CRM 查询接口，例如：
{
"name": "lookup_customer",
"description": "确认客户编号后查询客户资料。",
"kind": "http",
"url": "https://crm.example.com/customers/{{customer_id}}",
"method": "GET",
"read_only": true,
"credential_ref": "crm",
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
},
"response_path": "data"
}
创建结果为 { "data": { "id": "TOOL_ID", ... } }。向 PUT /agents/AGENT_ID/tools 发送 { "tool_ids": ["TOOL_ID"] }，将工具定义的快照绑定到 Agent，并替换其全部工具。工具库更新后需重新绑定；删除库中定义会保留已绑定的快照。也可以通过 Agent API 的 tools 字段读取和替换内联工具定义，通过 analysis_config、widget_config 配置分析与挂件。
工具支持 GET、POST、PUT、PATCH、DELETE。query 和 request_body 可使用嵌套 JSON 模板，例如 { "customer": { "id": "{{customer_id}}" } }；完整占位符保留原始 JSON 类型。URL 参数会编码，域名必须是固定的公网 HTTPS 地址。未设置 request_body 时，非 GET 请求发送 { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }。response_path 用点号选择返回字段。简单 parameters 继续兼容；input_schema 还支持嵌套对象、数组、枚举和数字范围，不支持外部 Schema 引用或正则表达式。
static_args：每次调用都带上的值，模型不能改，比如门店编号；也可以在地址和请求体里用 {{名称}} 引用。extract：[{name, path}] 从函数返回里取出字段（如 data.id），后面的函数可以用 {{name}} 引用，比如先查客户得到 customer_id 再用它下单，不用模型复述。通话开始时查询返回的字段也同样保存。reject_when：最多 5 条规则 {on: caller|agent, pattern, negate}，全部成立时不执行函数，并把 reject_message 告诉 Agent。model_says：每次调用时由模型写一句话，在函数运行时说给来电者，代替固定的 speak_before。在“集成 → Webhook 与通知 → 连接的应用”里连接应用，再到 Agent 的“知识库与工具”里点“添加现成工具”，不用自己写接口：
check_availability（按日期查空闲时段）和 book_appointment（来电者选定后直接预约）。Google 日历按你设置的时区、营业日、营业时间和每次时长计算空闲时段；Cal.com 使用活动类型自己的可预约时间，来电者没有提供邮箱时使用你设置的备用邮箱。save_to_sheet，按你列出的表头逐列填写一行，并自动补上通话 ID 和时间。notify_team，把 Agent 写的一条消息发到 Slack 频道（Incoming Webhook）。这些函数由 EvaSay 控制面使用你连接的账号执行，Worker 和 Agent 定义里都不保存应用的凭据。通过 API 读取 Agent 时它们显示为 kind: "app"（带 app、action、connection_id、app_config）；替换 tools 时原样带回即可保留。连接应用只能在工作台完成。
给 Agent 的某个工具设置 run_at_start: true，每通电话一开始、Agent 打招呼或回答之前就会先调用它。参数名为 caller_number、called_number、direction、channel 或 call_id 时会自动填入。返回的字段会填进 first_message、system_prompt 和 idle_messages 里的 {{变量}}（下一层的字段写成 {{customer.name}}），整个结果也作为背景交给 Agent。开场白里有变量时最多等 3 秒；查不到的变量留空。每个 Agent 只能有一个这样的工具。
凭据由服务器环境按工作区和目标地址配置，需要时联系 support@evasay.com 开通 credential_ref。不要把密钥写入 Agent 定义、Header、提示词或工具参数。CRM 本身的密钥也可以留在你自己的接口服务环境里。
向 POST /tools/TOOL_ID/test 发送以下内容，先预览请求：
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
预览会校验参数并显示请求映射，不运行对话，也不请求业务系统。设置 dry_run=false 才会真实执行。真实写操作还需要 confirmed=true 和 idempotency_key（8–128 位字母、数字、点、下划线、冒号或连字符）。结果包括 ok、status、duration_ms 和有大小限制的结果，不返回凭据。读取和写入工具的测试均要求工作区写权限。
通话中的业务请求带稳定的 Idempotency-Key，你的接口应按它去重。同一通话里相同参数的写操作会去重，超时后结果未知的操作也不会自动重放。确实需要执行另一笔相同业务时，应使用不同业务参数，如 operation_id。调用事件记录状态和耗时；现有“对话测试”仍是文本模拟，不能代替工具接口实测。
向 POST /mcp/discover 发送 { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } 获取工具列表和参数 Schema，然后只注册所需工具：
{
"name": "lookup_customer",
"description": "按已确认的客户编号查询 CRM。",
"kind": "mcp",
"url": "https://crm.example.com/mcp",
"mcp_tool": "get_customer",
"credential_ref": "crm",
"read_only": true,
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"]
}
}
只有注册的工具会开放给 Agent。外部连接支持 Streamable HTTP、请求的 JSON 或 SSE 响应、公网 HTTPS 地址和预先配置的凭据。暂不支持旧式 SSE 入口、OAuth 协商、服务端发起的 sampling/elicitation 或二进制附件。发现工具不会自动开放全部权限；远端工具的 Schema 需要是受支持的内联 JSON Schema。