英飞思想家帮助中心

创建企业 Agentic API 智能体

英飞团队···5,432 字·浏览量 815

什么是 Agentic API 智能体

Agentic API 智能体是平台中专门用于 “对接第三方平台智能体/系统接口” 的智能体类型，通过标准化配置将外部智能体、API（如Dify的智能体等）封装为平台可直接使用的模块，无需手动编写接口调用代码，即可实现与外部系统的数据交互和功能联动。

适用场景

API 式调用场景：将外部 API 封装后，在平台内通过 “一键调用” 实现功能触发（如调用报表接口生成数据统计文件等）。

创建 Agentic API 智能体

智能体开发管理平台创建智能体时，选择 Agentic API 类型智能体，即可进入 Agentic API 智能体的创建流程。

“创建智能体”配置页面中需填写以下信息：

  • 智能体名称：智能体名称要尽量体现智能体的核心功能或使用场景（如：天气查询、发送短信等）；
  • 智能体描述：简要说明智能体的核心能力与适用范围，该内容除了再智能体开发管理平台中显示外，也会在商店以及画布使用时向使用智能体的用户进行展示，帮助用户快速识别和了解智能体的用途与使用方式；
  • 智能体分类：选择智能体所属的分类，用于后续智能体的分类展示、筛选与管理；
  • 图标：为智能体设置图标，可手动上传本地图片文件，也可以由AI通过智能体名称与描述信息进行智能生成。

配置 Agentic API 智能体

Agentic API 智能体的配置，需完成三方平台选型、API 访问地址设置、鉴权方式配置，以及输入输出参数等信息的配置，全部完成后，方可与外部系统的API进行对接和数据交互。

1. 平台配置

智能体平台选择：通过下拉框选择要对接的智能体平台。不同平台的 API 对接规则与参数要求存在差异，需根据实际对接需求准确选择。不同的平台/系统，需要配置的平台信息以及参数配置方式可能存在不同。

1.1. Dify 平台

  • BaseUrl 填写：BaseUrl 是 Dify 平台 API 接口的根地址，后续具体接口路径将基于此进行拼接。需确保填写的 URL 准确无误，可参考对接平台的 API 文档获取
  • 认证方式选择：Dify 平台当前仅支持 API-Key 的认证方式，需要填写平台上配置的 API-Key 信息。需确保填写的 API-Key 准确无误，可参考对接平台的 API 文档获取；
  • 智能体类型选择：系统当前支持 Dify 平台的智能体类型有：聊天助手、文本生成应用、Chatflow、工作流，暂不支持 Agent 类型智能体。不同的智能体类型，其在进行 API 调用时，请求与响应的报文结构不同，需确保选择的智能体类型与 Dify 平台中对应智能体的类型相匹配。

注意：系统当前的 API 响应模式仅支持 Blocking 模式，由于 Dify 平台 Agent 类型智能体并不支持 Blocking 响应模式，所以系统暂不做支持。

1.2. Coze 平台

  • 请求地址填写：Coze 平台 API 访问的根地址，Coze 平台智能体的调用过程将基于此地址进行调用。需确保填写的 URL 准确无误，可参考对接平台的 API 文档获取
  • 认证方式选择：Coze 平台当前仅支持「服务访问令牌」的认证方式，需要填写平台上配置的「服务访问令牌」信息。需确保填写的「服务访问令牌」准确无误，可参考 Coze 平台的 API 文档获取
  • 智能体类型选择：系统当前仅支持 Coze 平台的「智能体」，暂不支持 Coze 平台的「应用」类型

1.3 OpenAPI

OpenAPI 用于把一份 OpenAPI 3.0 接口文档封装成画布智能体。它对接文档里的某一个公网 HTTPS 接口，不限于 Dify、Coze 这类智能体平台。

内测提示：OpenAPI 目前处于内测（Beta）阶段，仅对已开通的企业显示。如需开通，请联系我们。功能和限制在内测期间可能调整。

使用前须知

项目说明
接口文档格式仅支持 OpenAPI 3.0.x，格式为 JSON 或 YAML，大小不超过 1 MB
接口范围一个智能体只绑定文档中的一个接口。需要调用多个接口时，请分别创建多个智能体
调用方式仅支持同步接口，且必须有明确的 2xx 同步响应
服务地址必须是公网 HTTPS、443 端口的地址，无法调用企业内网接口
请求体仅支持 application/json，不支持表单和文件上传
响应支持 JSON 或纯文本（text/plain）。图片、音视频、文件流不支持，也不能作为画布上的原生媒体输出
鉴权支持单一的 Basic、Bearer、API Key（Header 或 Query）。不支持 OAuth2，也不支持同时要求多种鉴权
引用仅支持文档内部以 #/ 开头的引用，不支持外部文件、外部 URL 和循环引用
平台切换OpenAPI 与 Dify、Coze 不能互相切换。已经选过其中一种平台的智能体，不能再改成另一种，需要新建智能体

选择 OpenAPI

创建 Agentic API 智能体的时候，在「智能体平台选择」中选择 OpenAPI（带有 Beta 标记）。

选择后，配置分为两步：

  1. 1确认连通性：导入接口文档，选择接口，填写请求参数和凭证，测试连通。
  2. 2配置参数针脚：把接口的参数和返回内容映射到画布智能体的输入、输出针脚。
OpenAPI 确认连通性

导入接口文档

在「1. 确认连通性」中，用下面任一方式提供文档：

  • 把 OpenAPI 3.0 的 JSON 或 YAML 粘贴到文本框，点击文本框外部后开始解析；
  • 点击「选择文件」，导入 .json、.yaml 或 .yml 文件。文件不能超过 1 MiB。

整份文档解析失败时，页面会弹出错误，接口列表不会出现。常见原因见 FAQ：文档解析失败。

确认服务地址和选择接口

解析成功后会出现：

  • 服务地址：取自文档中的 servers，可以修改。地址必须是公网 HTTPS、443 端口。文档中没有 servers 时留空，需要手动填写，不填则不能测试连通。取值规则见 FAQ：服务地址。
  • 接口信息：从文档解析出的接口中选择一个。无法使用的接口会保留在列表中但不可选，名称后面会注明原因。常见原因和处理办法见 FAQ：接口不可选。

非 HTTPS 地址不会让接口变灰。接口仍可选，地址会填进「服务地址」，到测试连通或发布时才会被拒绝。

如果文档中的路径含有固定片段，例如 /pets/123 中的 123，可以点击该片段旁的「作为输入参数」，把它变成调用时由画布传入的参数。误操作后，可以「还原」为原来的固定值。

填写请求参数

「请求参数」列出该接口需要的参数。带 * 的为必填。

  • 布尔值从下拉列表选择 true 或 false；
  • 对象、数组按 JSON 填写；
  • 其他类型直接填写文本。

接口带有请求体时，可以点击「粘贴 JSON」，把一份 JSON 对象贴进去，系统会按字段路径填入对应参数。匹配规则见 FAQ：粘贴 JSON。

这里填写的是连通测试用的值。后面如果某个参数没有映射到画布针脚，发布后就固定使用这里填写的值。

填写凭证

接口文档声明了鉴权时，才需要填写凭证。凭证只写入、不回显。

  • Basic：填写用户名和密码；
  • Bearer：填写令牌；
  • API Key：填写密钥（位置由文档声明，支持 Header 或 Query）；
  • 文档未要求鉴权时，不出现凭证输入。

请不要把密钥写在「请求参数」里。请求参数的值不会被隐藏，密钥应填在凭证栏。

再次编辑已发布的智能体时，可以选择「保留已有凭证」，或「填写新凭证」替换。

测试连通

勾选确认项后，「测试连通」才会可用。确认项会写明即将真实调用的方法和地址。测试会真的请求该接口，可能产生数据写入或费用，建议优先使用测试环境，或先选择只读接口。

测试前请确认：

  • 已解析文档并选择了接口；
  • 已填写服务地址，且为公网 HTTPS 443 地址；
  • 必填参数已填写，且格式正确；
  • 需要凭证时，已填写新凭证或选择保留已有凭证。

连通成功后，页面提示「连通成功，可以进入针脚配置」，并展示这次返回的内容。没有响应体的接口不会展示返回内容。

修改文档、服务地址、所选接口、请求参数或凭证后，之前的连通结果会失效，需要重新测试，才能点击「下一步」。

测试失败时，可参考 FAQ：地址被拒绝 排查。

与 Dify、Coze 不同：OpenAPI 不会在点击「下一步」时自动检测连通，必须先在本页点击「测试连通」并成功。

1.4 连通性检测

当用户完成平台配置并点击 “下一步” 时，系统会依据所配置的平台信息，自动开展连通性检测，以此验证平台配置的准确性。若连通性检测通过，即可顺利进入参数配置环节；反之，系统会弹出报错提示，指引用户排查配置问题。

Dify、Coze 在平台信息填写完成并点击「下一步」时自动检测连通。OpenAPI 的连通测试见「1.3 OpenAPI」，需手动点击「测试连通」。

2. 参数配置

此环节用于设置画布智能体的输入、输出参数与三方平台智能体输入、输出参数的映射关系。界面左侧为画布智能体参数设置区，右侧为三方平台智能体参数设置区，通过对同一参数在两侧进行映射配置，可实现画布智能体与三方平台智能体之间的参数映射及联动。

2.1. 画布智能体的参数配置

三方平台智能体若想在画布中使用，需先转化为画布智能体 —— 通过画布智能体的标准化形式，将三方平台智能体的功能开放给用户操作。

如图所示，配置环节中设置的 “画布智能体输入 / 输出参数名称”，最终会直接作为画布智能体的输入 / 输出针脚在画布界面显示；用户可通过针脚直观识别该智能体的可用数据接口，快速明确如何连接上下游节点、传递数据，降低使用门槛。

参数名称：画布智能体针脚上要显示出来的名称

参数描述：对每个参数的详细描述内容

2.2. 三方平台智能体的参数配置

Dify 平台

  • 输入参数配置

Dify 智能体支持输入参数的自动获取功能，所以在 Dify API 输入参数配置时，可通过下拉列表进行 Dify 智能体输入参数的选择，而无需手动输入参数名和参数类型。

  • 输出参数配置

Dify 智能体的输出参数需要手动填写参数名与参数类型，需确保填写的参数名、参数类型与Dify 平台上的配置相匹配，否则后续智能体在画布使用时会出现错误。

Coze 平台

Coze 智能体采用了一问一答的方式进行调用，所以它的输入输出参数配置无需配置。仅针对画布智能体参数部分进行配置即可。

OpenAPI

OpenAPI 的参数配置在连通成功并进入下一步后进行。左侧仍是画布智能体的输入、输出设置，右侧是这份接口的参数。

页面顶部会提示：没有映射到画布的参数，发布后使用连通测试里填写的值。

OpenAPI 参数针脚配置

输入参数

  • 参数名称、参数描述：显示在画布输入针脚上的名称和说明。名称不能为空，也不能重复。
  • OpenAPI 输入参数：从当前接口的参数中选择，即上一步「请求参数」列出的参数。同一个接口参数不能绑到多个针脚。
  • 必填参数：必须满足下面二者之一，否则无法发布：
    • 映射到画布的输入针脚；
    • 在连通测试中填写了值（发布后固定使用该值）。
  • 接口本身没有输入参数时，可以不配置输入针脚。

输出参数

输出字段来自刚才那次连通成功返回的内容，不是手写字段名。

  • 可以选择「整个响应」，或选择返回内容中的某一个字段。多个输出不能选择同一个字段。响应为纯文本时，选择「整个响应」。
  • 每个输出还需要选择画布上的类型：字符串、数字，或 转为 JSON 文本。字段内容是对象、数组等复杂结构时，可选择「转为 JSON 文本」。
  • 参数名称不能为空，也不能重复。
  • 如果该接口只执行动作、没有响应内容，则没有输出针脚，页面会提示「此接口仅执行动作，无输出针脚」。

配置完成后点击「发布」。已经发布过的智能体，按钮为「发布更新」。

Agentic API 智能体发布

Agentic API 智能体配置完成后，需通过 “发布” 操作，将智能体发布到应用商店后，才可以对智能体进行后续的上架动作。

发布操作

用户完成了 Agentic API 智能体的配置后，可点击页面右下角的“发布”按钮，即可对智能体进行版本发布。

注意：Agentic API 智能体一经发布，会直接更新商店中已经上架的智能体版本；画布中已经在使用的老版本 Agentic API 智能体将失效，并会提醒用户使用新版本智能体

Tips：智能体上架流程见智能体上架部分描述

OpenAPI 智能体发布

企业应用中心

在组织里创建的 OpenAPI 智能体，发布成功后还不能直接在画布运行，需要按原有上架流程把智能体上架到应用中心。上架完成后，用户在应用中心安装，再到智能体中心使用。

个人画布

在画布内创建的个人 OpenAPI 智能体，配置步骤与上面相同。发布后即可在当前画布使用，不需要再上架到企业应用中心。

在画布中使用

使用方式与其他 Agentic API 智能体相同：在画布中通过输入、输出针脚连接上下游。

  • 映射过的输入：由上游传入；
  • 没有映射、但在连通测试里填过值的参数：调用时使用那个固定值。

更新已发布的智能体

再次发布会更新已经上架的版本。画布里正在使用的旧版本会失效，并提示改用新版本。这一点与 Dify、Coze 的 Agentic API 智能体一致。

OpenAPI 常见问题（FAQ）

文档解析失败，页面弹出 [CONFIG_INVALID]

整份文档解析失败时，页面弹出错误，不会出现接口列表。错误以 [CONFIG_INVALID] 开头，后面是具体原因：

提示处理办法
JSON/YAML 解析失败检查文档的 JSON 或 YAML 语法，如括号、缩进、引号
YAML 含重复键、别名或过深结构去掉重复的键，展开 YAML 的锚点和别名，简化过深的嵌套
仅支持 OpenAPI 3.0.x确认文档的 openapi 字段是 3.0.x。Swagger 2.0、OpenAPI 3.1 不支持
文档缺少 paths补充 paths 节点
文档超过 1 MB删减不需要的接口和描述后重新导入

接口名称后面显示了原因，无法选择怎么办？

文档能打开，但某个接口无法解析或不受支持时，该接口会留在「接口信息」中，名称后面接上原因。其他接口不受影响。

提示含义与处理办法
请求体仅支持 application/json接口使用了 multipart/form-data、application/x-www-form-urlencoded 等。文件上传和表单不支持
参数序列化不支持参数用 content 描述了文件或复杂序列化，或开启了 allowReserved、allowEmptyValue
响应仅支持 JSON 或 text/plainapplication/json、application/*+json 和 text/plain 可以；图片、文件流不行
需要明确的同步 2xx 响应接口只有 202，或只有 4xx/5xx 响应。需要文档里声明一个同步的 2xx 成功响应
没有支持的单一静态鉴权方案鉴权是 OAuth2，或同时要求多种鉴权。仅支持单一的 Bearer、Basic 或 API Key（Header/Query）
format 不支持字段使用了 binary、byte 等。支持的 format 为 int32、int64、float、double、date、date-time、uuid、uri
不支持外部或循环引用、不支持外部/循环 schema接口用了外部引用或循环引用，见下一条
引用不存在$ref 指向的位置在文档中找不到，检查路径拼写
server 变量缺少默认值该接口的 servers 中有变量未设置 default，见「服务地址是怎么确定的」

支持哪些 $ref？

只支持文档内部、以 #/ 开头的引用，例如 #/components/schemas/Pet。

以下情况都不支持：外部文件、外部 URL、循环引用、YAML 的锚点和别名。

服务地址是怎么确定的？

文档里可以在三个位置声明 servers。系统按下面的优先级取值：

  1. 1接口自己的 servers；
  2. 2路径（path）上的 servers；
  3. 3文档根上的 servers。

规则补充：

  • 每一级只取第一项，后面的忽略。
  • 地址里的变量用 default 替换。某个变量没有默认值时，该接口不可选，原因是「server 变量缺少默认值」。
  • 文档里没有 servers 时，服务地址留空，需要手动填写。

测试连通或发布时提示地址被拒绝怎么办？

服务地址必须是公网 HTTPS、443 端口。不满足时，测试连通和发布都会失败：

提示原因
仅允许公网 HTTPS 443 地址地址是 http://、端口不是 443，或带有用户名密码
不允许非公网地址地址直接写成了 10.x、192.168.x、127.0.0.1 这类内网或本机 IP
目标地址不允许访问域名看起来合法，但解析到了内网、本机或链路本地地址
目标域名解析失败域名无法解析，检查域名拼写和 DNS

能调用企业内网接口吗？

不能。运行时会对域名做 DNS 解析，解析结果只要落在内网、本机、链路本地地址上就会拒绝，也不会跟随重定向。

目前没有「把某个内网域名加入白名单」的配置。联系我们开通的是 OpenAPI 入口，只决定哪些企业能看到这个功能，不影响可访问的地址范围。

请求体和响应支持哪些 Content-Type？

  • 请求体：只支持 application/json。键名必须正好是这个，带 charset 的写法（如 application/json; charset=utf-8）对不上。不支持表单，也不支持文件上传。
  • 响应：支持 application/json、application/*+json 和 text/plain。

「粘贴 JSON」是怎么匹配字段的？

  • 粘贴内容的顶层必须是一个 JSON 对象，不能是数组。
  • 按每个请求体字段的路径取值，不只是顶层字段名。文档里的对象属性会被拆成叶子字段。例如字段路径 /pet/name 会从粘贴内容的 pet.name 取值。
  • 数组，以及没有展开属性的对象，整段作为一条参数填入。
  • 路径参数、查询参数、Header 不会被这次粘贴填上，需要手动填写。
  • 类型对不上的字段会被跳过，并提示字段名。

为什么「下一步」点不了？

之前的连通结果失效了。修改文档、服务地址、所选接口、请求参数或凭证后，都需要重新「测试连通」并成功，才能进入下一步。

为什么无法发布？

常见原因：

  • 有必填参数，既没有映射到画布输入针脚，连通测试里也没有填写值；
  • 参数名称为空或重复；
  • 同一个接口参数绑定了多个针脚，或多个输出选择了同一个字段；
  • 服务地址不满足公网 HTTPS 443 的要求。

能把 OpenAPI 智能体改成 Dify 或 Coze 吗？

不能。OpenAPI 与 Dify、Coze 不能互相切换，已经选过其中一种平台的智能体，不能再改成另一种，需要新建智能体。

一个智能体能调用多个接口吗？

不能。一个智能体只绑定一个接口。需要调用多个接口时，请分别创建多个智能体，在画布中用针脚连接。