从 OpenAPI 规范创建工具

在本指南中，您可以了解如何将 OpenAPI 3.0 文档转换为代理工具。使用 agentengine agent create-tool 命令将文档编译为连接器文件。当您构建代理时，Atlas 代理引擎会从这些文件中创建连接器，以便您的代理可以调用 OpenAPI 代理工具。

注意

agentengine agent create-tool 命令是实验性的。标志、输出格式和生成的文件格式可能会更改，恕不另行通知。

关于此任务

agentengine agent create-tool 命令会在您指定的文件夹中生成两个文件：

tool_defs.yaml：该命令从 OpenAPI 文档中编译的工具目录。该目录包含每个操作的工具名称、输入模式以及 HTTP 方法和路径。
tool.yaml：将目录绑定到您的 API 终结点和凭证，并选择您的代理要公开哪些工具的创作文件。该命令会构建此文件。当您重新生成目录时，该命令不会覆盖您对该文件所做的编辑。

当代理调用连接器工具时，该工具会在隔离的 Tool Pod 中运行。该调用会通过与其他工具相同的 Orchestration 引擎审批网关。凭证值永远不会写入生成的文件中，文件会引用工作区密钥的名称。

您必须向该命令传递以下输入之一：

--spec: 将 OpenAPI 3.0 文档编译为目录，如果不存在，则生成 tool.yaml 文件。该值可以是本地文件或 HTTPS URL。
--tool-defs：仅为现有本地目录构建 tool.yaml 文件。该命令不会重写目录。
--config：从声明 source.spec 字段的 tool.yaml 文件中重新生成本地拥有的目录。

要查看所有标志，请参阅 agentengine_create-tool CLI 文档。

开始之前

在开始之前，请确保您具备以下资源：

agentengine CLI 已安装并已认证。要了解更多信息，请参阅安装和身份验证。
一个包含 agent.yaml 文件的有效代理项目。要了解更多信息，请参阅创建项目。
Docker 在本地运行。
一个用于您要调用的 REST API 的 OpenAPI 3.0 文档，可以是本地文件或 HTTPS URL。
用于 REST API 的身份验证 Bearer token。

步骤

生成连接器文件。

在您的代理项目目录中，运行带有连接器名称和 --spec 标志的 agentengine agent create-tool 命令。以下示例将规范编译到 connectors/orders 文件夹中，并配置 Bearer token 身份验证：

agentengine agent create-tool orders \  --spec <openapi-document-url-or-path> \  --out-dir connectors/orders \  --auth bearer

该命令以连接器命名 Bearer token 的工作区密钥。对于 orders 连接器，密钥名称为 ORDERS_TOKEN。如果您省略 --auth 标志，该命令将根据文档声明的安全方案在 tool.yaml 文件中生成 auth 块。

该命令使用文档中第一个非模板化服务器作为基本 URL。如果文档未声明服务器，或者您想调用不同的终结点，请将 --base-url 标志添加到命令中。

如果文档包含生成器无法表示的操作，该命令将失败并打印操作名称。要改为排除这些操作，请将 --skip-unsupported 标志添加到命令中。该命令会打印每个跳过的操作并将其记录在目录中。

查看 `tool.yaml` 文件。

打开 connectors/orders/tool.yaml 文件。文件顶部的注释指明了终结点目标以及您的代理必须声明的凭证密钥。

要限制代理可以调用的工具，请在 expose.allow 字段中列出特定的工具名称。如果省略此列表，代理可以调用每个生成的工具。以下示例显示了一个公开一个工具的 tool.yaml 文件：

name: orderstool_defs: tool_defs.yamlsource:  type: openapi  base_url: https://api.example.comexpose:  allow: [orders_getOrder]auth:  bearer: ORDERS_TOKEN

注册连接器。

在 agent.yaml 文件中，添加一个指向 tool.yaml 文件的 connectors 条目。该路径相对于 agent.yaml 文件。

version: 1connectors:  - source: connectors/orders/tool.yaml

将 API 凭证存储为工作区密钥。

创建一个名称与 tool.yaml 文件中的 auth 块所引用的名称相同的密钥。在此示例中，密钥名称为 ORDERS_TOKEN。要了解如何存储密钥，请参阅预配云密钥。

授予工具沙盒访问该密钥和 API 的权限。

tool.yaml 文件顶部的注释仅报告要求，不授予任何权限。在 agent.yaml 文件中，将密钥添加到 sandboxes.tool.secrets 字段，将 API 托管添加到 sandboxes.tool.network.egress 字段。保留其他工具已使用的密钥和目标。以下示例添加了 ORDERS_TOKEN 密钥和 api.example.com 托管：

sandboxes:  tool:    secrets:      - ORDERS_TOKEN    network:      egress_mode: allow_list      egress:        - fqdn: api.example.com          ports: [443]

将 api.example.com 和 443 替换为您 tool.yaml 文件中基本 URL 的主机名和端口。要了解更多信息，请参阅代理 YAML 模式和管理网络出口策略。

构建并部署您的代理。

像往常一样构建和部署您的代理。构建过程会根据您的 tool.yaml 和 tool_defs.yaml 文件创建连接器。要了解更多信息，请参阅构建代理镜像。

行为和限制

查看生成的连接器工具的以下行为和限制：

tool.yaml 文件中的基本 URL 适用于每个操作。生成器会忽略 OpenAPI 文档中路径级和操作级的 servers 条目。
生成器读取本地文件。CLI 会根据平台传输策略下载您通过 URL 指定的文档。
该生成器支持 Bearer token、API 密钥和 HTTP Basic 身份验证。以下内容在生成边界之外：
- OAuth 令牌获取与刷新
- 交互式或会话登录
- 按请求签名
- 仅 mTLS 身份验证
- 多部分文件上传
连接器会截断大于 200,000 个解码字节的响应，并将其标记为已截断。
每次工具调用在 30 秒后超时。