# 创建和调试 HTTP 工具

> 将 HTTP 服务配置成可调用工具，验证认证、输入和响应。

Source: https://doc.fastgpt.cn/zh-CN/guide/build/tools/http_tools

HTTP 工具支持通过 **OpenAPI Schema 批量导入**或**手动配置单接口**两种方式，将企业内部 REST 服务或第三方 HTTP 接口转化为可供对话 Agent、Agent V2 及工作流调用的标准工具。

## 前置条件与创建模式对比

需要团队内的工具创建权限，并确保 FastGPT 服务端网络可访问目标 API 地址。两种模式都是新建 HTTP 工具集时 **创建方式** 中的单选项，选择后不支持修改。

| 创建模式                     | 适用场景                        | 配置特点                                                                                |
| ------------------------ | --------------------------- | ----------------------------------------------------------------------------------- |
| **批量创建**（OpenAPI Schema） | 同一后端服务包含多个相关接口（如订单查询、创建、取消） | 共享 Base URL 与鉴权 Header，支持粘贴 OpenAPI 3.0 / Swagger JSON 或 YAML，或从 URL 导入，自动解析全部子工具   |
| **手动创建**（curl 导入或手动填写）   | 仅需接入单一特定接口                  | 通过 curl 导入，或直接在表单中配置请求方法（`GET` / `POST` / `PUT` / `DELETE` / `PATCH`）、URL、参数表与请求体模板 |

## 配置

1. 进入 **工作台 → 我的工具**，点击右上角 **新建 → HTTP 工具**，在 **创建方式** 中选择 **批量创建** 或 **手动创建**。
2. 填写服务地址、工具名称和描述。手动创建时通过 curl 导入或手动配置请求方法与路径；批量创建时检查解析出的工具列表。
3. 配置认证请求头（支持无鉴权、`Bearer Token`、`Basic Auth` 或自定义 Header 键值对），将固定凭证保存在认证配置中；定义调用者可提供的参数、类型、说明与必填项。
4. 检查请求参数、请求体和输出结构，保存配置。
5. 选中一个工具，在调试区输入已知参数运行，检查响应结构及错误。

![OpenAPI Schema 批量创建 HTTP 工具集](/imgs/optimized/current/http-tool-schema.png.webp)

![手动创建与配置单接口 HTTP 工具](/imgs/optimized/current/http-tool-manual.png.webp)

例如，把自有测试服务的只读 `GET /status` 配置为工具。预期返回由该服务契约定义的状态字段；先用同一凭证确认服务端能够访问，再验证 FastGPT 的调试结果。

## 鉴权方式与参数映射规范

| 配置区域                      | 字段说明                                                                       | 安全与传参建议                                                      |
| ------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **工具集鉴权（Header Secret）**  | 支持 `Authorization: Bearer <token>`、`Basic` 或自定义 Header                     | 密钥保存在工具集服务端配置中，对调用方与终端用户隐藏，避免将密钥设为模型入参                       |
| **路径与查询参数（Path / Query）** | 在 URL 中使用路径占位符或在 Params 表声明查询项                                             | 为每个参数提供清晰的类型（`string` / `number` / `boolean`）与取值说明，提升模型填参准确率 |
| **请求体（Body）**             | 支持 `application/json`、`form-data`、`x-www-form-urlencoded`、`xml`、`raw-text` | JSON Body 中可通过变量引用绑定工具输入参数                                   |

## 接入应用

在应用的工具选择中添加该工具，明确描述适用场景。用一个需要调用它的问题测试，检查模型传参和返回内容。工作流中的单次 HTTP 请求配置见 [HTTP 请求节点](/zh-CN/guide/build/workflow/nodes/http)。

## 排障

| 错误                             | 检查                                                                       |
| ------------------------------ | ------------------------------------------------------------------------ |
| 401 / 403                      | 认证值、目标服务授权范围与过期时间                                                        |
| 404                            | 服务地址、路径及请求方法                                                             |
| 非 2xx 业务状态码（如 400 / 422 / 500） | 系统会将下游返回的响应正文（Response Body）一并写入工具错误消息；展开对话运行详情即可根据接口返回的错误码与提示定位参数或服务端异常 |
| 超时或网络错误                        | FastGPT 服务端的 DNS、出口、TLS 和目标服务状态                                          |
| 参数或结构错误                        | 输入类型、必填值、请求体格式与服务返回的实际结构                                                 |

调试可能真实调用外部服务，操作效果由目标接口决定。正式使用写操作前，验证目标权限和业务确认流程。排障材料中隐藏认证头与个人数据。