英飞思想家帮助中心

创建个人 Agentic API 智能体

英飞团队···5,481 字·浏览量 932

什么是 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 平台的「应用」类型；

● Bot ID：「智能体」类型的智能体，需要填写 Bot ID 信息，可参考对接平台的 API 文档获取。

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 智能体将失效，并会提醒用户使用新版本智能体

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 不能互相切换，已经选过其中一种平台的智能体，不能再改成另一种，需要新建智能体。

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

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