API工具配置使用指南

1、 功能概述

为解决MCP无法覆盖的集成场景，系统新增“外部API工具封装”能力。您可通过配置HTTP接口信息，将任何可通过HTTP访问的服务（如内部系统API）封装成一个标准的工具，使大模型能在适当时机调用该接口，并将返回结果用于后续推理与回复。

2、核心功能与配置项

API工具的配置主要分为以下几个部分：基础信息配置、请求端点、请求参数配置和认证。

2.1 基础信息配置

此部分用于定义API工具的基本属性。
配置项说明限制示例
工具名称必填，用于Agent识别和调用此API工具的唯一标识。限50字符，仅支持英文。queryOrderInfo
描述必填，详细说明此API工具的功能和用途。限1000字符。用于查询客户订单详情的API接口
适用对象定义哪些类型的Agent可以调用此API工具。可选：通用、Text agent、Voice agent。通用
    通用文本和语音Agent均可调用。
    Text agent仅限文本Agent调用。
    Voice agent仅限语音Agent调用。

2.2 请求端点

配置项说明限制示例
方法必填，指定HTTP请求方法。目前仅支持GET和POST两种。POST
URL必填，外部API的完整访问地址。必须是有效的URL。https://api.example.com/order/query
对于 GET 请求，参数请配置在params中对于post请求，参数请配置在body中

2.3 请求参数配置

此部分用于定义API请求时需要传递的参数、请求头和请求体。

2.3.1 Params (URL参数)

配置项说明示例
参数名URL查询参数的名称。orderId
类型参数的数据类型（如String, Integer等）。String
是否必填标记此参数是否为必需。是
在配置 Params 或 Body 时，无需填写具体的参数值。这是因为该工具是供 AI Agent 调用的：参数值动态填充：AI 会根据用户在对话中提供的实际信息（如订单号、手机号），在运行时自动提取并填充这些参数。配置重点：您只需确保参数名（Key）与您的接口要求完全一致，AI 即可识别并完成数据对接。

2.3.2 Headers (请求头)

用于传递请求的元信息（metadata），如内容类型、身份认证、鉴权等。系统提供预设的Content-Type选项，也支持自定义请求头。
预设Content-Type选项：
  • application/json
  • application/x-www-form-urlencoded
自定义请求头： 您可以根据API要求添加其他自定义请求头，例如用于身份验证的Authorization。
配置项说明示例
Header名请求头的名称。Content-Type
Header值请求头的值。application/json

2.3.3 Body (请求体)

用于POST等请求方法，传递API请求的主体数据。支持两种数据格式，由Headers中的Content-Type决定数据传输的格式。
  • JSON：默认推荐格式，适用于传输结构化数据。
  • 表单 (x-www-form-urlencoded)：适用于传输简单的键值对数据。
为什么配置 Body 时不直接写 JSON 代码，而是通过表单添加字段？”我们特意将配置过程从“写代码”简化为了“填表单”，主要基于以下三个考虑：
  1. 所见即所得，避免语法错误：直接编写 JSON 源码非常容易因为少了一个引号或括号导致整个接口失效。通过表单配置，您只需要关注参数本身，系统会自动帮您生成标准格式，实现“零代码”配置。
  2. 强约束保证高成功率：通过字段校验（如区分数字、字符串、是否必填），我们能给接口加上一层“保护罩”。这能确保 AI 提取到的数据始终符合您后台接口的要求，从而大幅提升 API 调用的成功率。
“为什么 Body 只有一种填写方式，却能支持 JSON 和表单两种格式？”我们的平台为了降低您的配置负担，采用了“统一配置、按需转换”的策略：
  1. 统一的配置体验：无论您的接口要求的是 JSON 还是表单格式（x-www-form-urlencoded），您在 Body 区域都只需要通过点击“添加参数”来定义字段。这样您无需学习两套配置逻辑，只需关注您的业务数据。
  2. 数据格式由 Header 决定“翻译”方式：系统会自动识别您在 Headers 中设置的 Content-Type：如果您选择了 application/json，系统会在发起请求时，自动将您填写的这些字段“翻译”成标准的 JSON 结构。如果您选择了 application/x-www-form-urlencoded，系统则会将这些字段自动“翻译”成标准的 表单键值对。
  3. 如果您选择了 application/json，系统会在发起请求时，自动将您填写的这些字段“翻译”成标准的 JSON 结构。
  4. 如果您选择了 application/x-www-form-urlencoded，系统则会将这些字段自动“翻译”成标准的 表单键值对。

2.4 认证 (Auth)

认证类型是否支持关键配置参数
No Auth✔ 支持无
Basic Auth✔ 支持username, password
Bearer Token✔ 支持tokenBearer Token 是 OAuth 2.0 最常用的 Token 类型。
API Key✔ 支持key(参数名), value(密钥值)

3.Agent侧调用

添加API工具：在创建或编辑Agent（如Chat Agent、Email Agent或Voice Agent）时，进入添加工具的界面，选择使用已配置好的“API工具”。
提示词中指定调用场景：选择对应工具后，您可以在Agent的提示词（Prompt）中明确指定调用此API工具的场景和条件。Agent将根据用户意图在运行时自动调用该API。
提示词示例：
“当用户咨询订单时，先向用户索要订单号，再调用“API tool name”查询并告知客户的订单信息；如果用户未提供订单号，请引导用户提供。”
2026-08-05
© 2026 QuickCEP 版权所有 京ICP备2021037140号-4