SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场architect-create-webhook-tool

architect-create-webhook-tool

智能体与模型

查看项目

更新于 10-16 06:55

技能介绍

用途

该技能用于在 ElevenLabs 平台上为智能体（agent）创建一个新的 webhook / server / HTTP 工具，让智能体能够调用外部 API，例如查询客户、创建工单、检查状态等。创建 webhook 工具是连接智能体与外部 API 最常见的方式，但失败率很高，几乎都源于 api_schema.request_body_schema 中的 schema 错误。该技能的目标是让工具在第一次写入时就正确。

所有调用均使用 xi-api-key: $API_KEY，请求 https://api.elevenlabs.io。

主要能力

  1. 先收集当前状态：在写入任何内容之前，并行执行必要的读取操作。

    • GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID，确认智能体，并判断它是单节点智能体还是工作流（工作流配置会影响后续工具挂载的位置）。
    • GET /v1/convai/tools，检查工具是否已存在，并匹配现有命名风格。
    • 在构造工具之前，从用户处获取端点 URL、方法、认证方式以及请求/响应结构。若缺失，先向用户或 API 文档索取。

  2. 创建工具：POST /v1/convai/tools，工具配置按 type（webhook/server）区分。webhook 配置位于 api_schema 下，而不是顶层。

  3. 处理 schema 陷阱（导致失败的具体问题）：

    • 静态 URL：api_schema.url 必须是静态字符串，不要在路径中放入 {{variables}}。动态值应放入 request_body_schema（或 path_params_schema / query_params_schema），绝不能插值到 URL 中。
    • 每个属性只能有一个取值来源：request_body_schema.properties 中的每个属性，其值只能来自以下之一：非空 description（由 LLM 填充）、dynamic_variable（如 "user_phone_number" 或系统变量 "system__conversation_id"）、constant_value（固定字面量）、is_system_provided: true。一个属性有两个来源是最常见的校验失败；零个来源同样无效。裸的 {"type":"string"} 或唯一非类型字段是空 constant_value 的属性都算零来源，会被拒绝。constant_value: "" 不算作常量。
    • path_params_schema / query_params_schema 是参数对象的数组，不是 {properties:{...}} 对象。每一项需要：id、type（裸字符串 "string"|"number"|"integer"|"boolean"；可空使用两元素数组如 ["string","null"]，绝不用 {"type":"string"}）、description、value_type（"llm_prompt"|"dynamic_variable"|"constant"）、dynamic_variable（未绑定时为空字符串）、constant_value（始终为字符串/数字/布尔值，绝不为 null 或省略）、required（布尔值）。一个可用的 llm_prompt 项示例：{"id":"city","type":"string","description":"The city to look up.","value_type":"llm_prompt","dynamic_variable":"","constant_value":"","required":true}。
    • 数组属性必须带 items schema，且不得携带 constant_value。
    • required 只能引用 properties 中存在的属性名。
    • request_headers 是对象，不是数组。对于密钥 API key，应通过 id 引用工作区密钥（{"secret_id": "..."}，可通过 GET /v1/convai/secrets 列出现有密钥），而不是直接粘贴密钥。
    • response_timeout_secs 默认 20，最大 120。仅对确实缓慢的 API 提高该值；高超时会损害语音延迟。
    • 名称和描述驱动调用。描述要具体（如 "Look up a customer by phone number"，而不是 "Customer lookup"）；描述含糊是工具正确保存却从未被调用的首要原因。

  4. 将响应值提取到对话中：要把 API 响应字段送入 {{dynamic_variables}}，需在工具顶层 assignments 数组（api_schema 的同级）中添加条目。每个条目将响应字段映射到变量：source 为 response，使用点号表示法的 value_path（如 data.items.0.id，而不是 data.items[0].id，方括号索引会静默失败），以及目标 dynamic_variable。然后在提示词中引用 {{customer_name}}，让智能体说出来。

  5. 挂载并接通使用：创建后，将工具挂载到智能体。单节点智能体将其 id 加入基础 tool_ids；工作流智能体保持基础 tool_ids: []，将其加入正确节点的 additional_tool_ids，使其仅在触发处生效。通过针对相关路径的 PATCH /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID 应用挂载。在提示词中，明确告诉智能体何时调用该工具，并添加回退语句（如 "If the lookup returns an error or no results, apologize and offer to take a message"）。

  6. 错误恢复：

    • schema_mismatch（通常无字段细节）：逐条重新检查第 3 节规则，最常见的是一个属性有两个取值来源、URL 中有 {{var}}、或数组上有 constant_value。修复后重新发送；不要盲目重试相同载荷。
    • validation：某个具体参数错误（required 名称没有匹配属性、数组缺少 items、value_path 错误、request_headers 非对象）。消息会指出字段；修正该字段。
    • not_found：智能体 id 错误或工作流节点 id 不存在。重新读取当前 id 并重试。

使用方式

该技能通过 ElevenLabs API 操作，使用 xi-api-key 认证。流程为：先读取智能体与工具现状，再创建工具，处理 schema 细节，配置响应值提取，最后挂载到智能体并编写提示词。

适用场景

适用于需要为 ElevenLabs 智能体接入外部 API 的场景，例如查询客户、创建工单、检查状态等。

限制

资料未提供该技能的收费、价格、平台支持范围或效果保证等信息。