以代码管理工具
通过 Python 和 JavaScript SDK 构建、编辑和版本管理智能体工具
概览
工具以配置形式存储,其中包含参数的嵌套 JSON 架构。手动编写配置时,需要让路径参数与 URL 保持一致、让 required 列表与其属性对应,并为每个参数恰好指定一个值来源。Python 和 JavaScript SDK 中的工具构建器可通过链式方法调用描述同一工具,然后生成 tools.create() 和 tools.update() 已接受的请求。
可用于:
- 在代码中定义 webhook、客户端和系统工具,并像审查其他代码改动一样审查它们。
- 加载工具、修改一个参数后推送回去,而不影响其余配置。
- 将工具以 JSON 格式存入版本控制,并在 CI 中验证。
构建器完全在 SDK 中运行。它不会调用新的 API 端点,构建的任何内容都可在控制台中 打开和编辑。
要求
- Python:
elevenlabs包。构建器从elevenlabs.agent_tools导入。 - JavaScript:
@elevenlabs/elevenlabs-js包。构建器从包根目录导出。
构建 webhook 工具
Tool.webhook(name, description) 创建一个 webhook 工具。名称和描述是 LLM 决定是否调用工具时看到的内容。此示例会根据调用者提供的订单号查询订单,从工作区密钥中发送 API 密钥,并将订单状态存入动态变量:
请求方法用于设置 HTTP 方法和 URL。URL 中的 {name} 占位符会由路径参数填充:
设置名称已存在的参数或标头会替换它,并保留其位置。remove_path_param()、remove_query_param()、remove_header() 和 remove_assignment()(JavaScript 中为 removePathParam() 等)会将其移除。路径、查询和请求体中的参数名称必须唯一。
请求体是逐个属性构建的对象架构:
参数架构
Schema 用于构建 webhook 和客户端工具所用的参数架构。每个方法都会返回一个新架构,不会修改调用它的架构,因此可定义一次架构并在多个工具中使用。
值的来源
无论字面量出现在哪里——参数、请求体、响应架构或对象、数组内部——都必须恰好有一个值来源。对象或数组本身也可有一个值来源,用于提供整个值。
对于对象或数组,describe() 会为 LLM 说明容器,而每个属性或元素仍有自己的来源。
其他架构方法
标头与身份验证
标头值可来自以下 4 个位置之一。敏感内容请使用密钥或环境变量,避免值出现在工具配置中:
AuthConnection.id(id) 使用工作区中具有该 ID 的身份验证连接。AuthConnection.env_var(label) / AuthConnection.envVar(label) 从环境变量中选择连接,因此同一工具配置可在每个环境中使用不同连接。
构建客户端工具
Tool.client(name, description) 创建一个客户端工具,它在应用中而非服务器上运行。使用 param(name, schema) 添加参数。当智能体应等待应用返回结果时,设置 expects_response / expectsResponse:
构建系统工具
系统工具内置于平台中。SystemTool 上每个工具都有自己的构造器,接收该工具的设置:
两个转接工具通过 transfer(condition, destination, options) 接收目标。条件告知 LLM 何时转接,目标使用与以代码管理工作流相同的 Destination。转接到 SIP URI 需要使用 SIP REFER 转接:
工具选项
所有工具类型共用的设置放在 options() 中:Python 使用关键字参数,JavaScript 使用对象。其名称与 API 中工具配置字段一致:
Webhook 工具的响应超时范围为 5 至 300 秒。客户端工具的范围为 1 至 120 秒,或设为 -1 以无限等待,此时需要 expects_response / expectsResponse。follow_redirects / followRedirects 需要提供允许的域名列表。
将工具附加到智能体
Webhook 和客户端工具通过 tools.create() 单独创建,再通过 ID 附加到智能体,因此一个工具可由多个智能体共享。系统工具属于智能体配置:build_config() / buildConfig() 返回智能体内置工具的条目。
智能体的 prompt.tools 字段用于内联保存工具配置,现已弃用。它不能与 tool_ids 组合使用;
请求中包含此字段时,智能体的内置工具会被其中包含的系统工具替换。
请改用 tools.create() 创建工具,并通过 ID 附加。
编辑现有工具
Tool.from_response() / Tool.fromResponse() 加载由 tools.get() 返回的工具。构建器未建模的字段以及 API 填充的默认值都会保留,因此推送回去时只会修改你改动的部分。as_webhook()、as_client() 和 as_system()(JavaScript 中为 asWebhook() 等)会提供可编辑的类型化工具;如果属于其他类型,则返回 None / undefined。
要修改请求体属性,请读取请求体架构,再次设置该属性,然后设置请求体:
在版本控制中存储工具
to_json_string() / toJSONString() 以 API 的线格式写入工具:使用 snake_case 键、每一层排序,并采用 2 空格缩进。其结构与 CLI 在 tool_configs/ 目录中保存的内容相同;两个 SDK 为相同工具写入的文件也完全一致,因此差异很小。Tool.from_json() / Tool.fromJSON() 可将其读回。
典型设置与工作流相同:先通过 elevenlabs tools pull 初始化文件,直接编辑或使用构建器编辑,在每个拉取请求中于 CI 运行 Tool.from_json(file).build() / Tool.fromJSON(file).build(),合并时再通过 tools.update() 或 elevenlabs tools push 推送。
验证
链式调用本身不会失败。build()、build_config() / buildConfig()、to_json() / toJSON() 和 to_json_string() / toJSONString() 会检查整个工具,并引发或抛出单个 ToolValidationError。其 issues 会列出每个问题,每项均包含 code、message 以及相关部分的 path,例如 body.reason。
错误包括:
- URL 占位符没有对应的路径参数,或路径参数没有对应占位符。
{{system__env_api_host}}等环境变量模板不是占位符。 - 字面量没有值来源,或有多个值来源。
GET包含请求体,或POST、PUT、PATCH没有请求体。- 路径、查询和请求体中有多个参数使用相同名称。
- 必填属性使用
omit()、非字符串架构使用choices(),或常量与架构类型不匹配。 - 转接工具没有目标、目标类型错误,或 SIP URI 目标未使用 SIP REFER 转接。
- 选项不适用于该工具类型,或超时超出范围。
SDK 中较新的工具类型
从 API 或文件加载的工具,可能属于构建器无法编辑的类型,例如 MCP 工具。它会以 "other" 类型加载,并可通过 from_json() / fromJSON() 和 to_json_string() / toJSONString() 原样往返处理;build() 则会通过 on_warning / onWarning 将其报告为警告。