使用 AI 网关调用 Flow Agent-函数计算(FC)-阿里云帮助中心

适用场景

需要将已发布的 Flow Agent 以标准 HTTP API 对外提供、供前端、移动端或第三方系统集成的场景。通过 AI 网关接入后，支持同步/流式响应、会话保持、鉴权限流、日志监控等能力。

短描述

若已通过 Flow 创建并发布了 Agent，希望以统一 HTTP 入口对外暴露、供多端调用，可将 Flow Agent 接入 AI 网关。操作包括：创建 AI 网关实例、绑定 Flow Agent、配置路由，以及通过 HTTP POST 调用。

前置条件

已创建并发布 Flow Agent：在AgentRun控制台通过 Flow 创建并发布 Agent。操作步骤见低代码创建Agent快速入门。

创建AI网关实例

进入AI 网关控制台，在左侧目录中选择AI 网关>实例；
点击页面上方的地域选项，选择与Flow Agent同一地域；
点击创建实例进入购买页，实际生产过程中，建议参考创建网关实例按需配置，本文中的配置如下（满足测试要求的最低规格配置）：
1. 商品类型：选择Serverless(按量付费)；
2. 地域：选择与Flow Agent同一地域；
3. 网关名称：自定义设置网关的名称，如：aistudio_wg_demo;
4. 网络访问类型：本文选择公网；
  说明
  通过公网访问网关时，将会产生相应的公网流量费用，公网流量将基于云数据传输CDT进行统一计费和出账，采用BGP（多线）模式，详情可参考公网流量
5. 根据调用AI网关的客户端网络，选择AI 网关实例运行所在的专有网络环境，在上一步网络访问类型如果选择私网，则需要保证AI网关与调用端在同一专有网络环境下；
点击立即购买，完成购买，返回AI网关>实例列表，等待创建完成；

AI 网关接入配置

步骤1：配置网关服务（绑定Flow Agent）

进入AI 网关控制台，点击页面上方地域选择框，选择AI 网关实例所在地域；
在实例列表，点击目标实例，进入实例概览页面；
在左侧目录点击服务>创建服务，并在创建服务页面，进行如下配置：
1. 服务来源：选择云工作流CloudFlow；
2. 工作流程：根据实际情况选择需要接入的Flow Agent；
3. 点击确定，完成创建。

步骤2：配置Agent API

在左侧目录点击Agent API>创建Agent API
在创建Agent API页面进行如下配置：
1. API名称：自定义设置，支持英文、数字、下划线“_”、“-”，不超过64个字符，如：aistudio_api；
2. 选择域名：如没有可选域名，需要点击添加域名，参考创建域名创建，也可以直接在点击添加域名后，在域名输入框中，输入“*”；
  重要
  - 仅用于暂无域名的场景，支持使用IP和使用AI 网关实例接入点访问，存在安全风险，请谨慎使用；
  - 接入点访问域名可在网关实例详情的概览页面查看；
  - 访问域名是网关实例的访问入口，在生产使用中，您需要将业务域名通过DNS服务CNAME至访问域名。直接通过访问域名访问每天有1000次访问限制，可用于测试，请勿直接用于生产环境。
3. Base Path：保持默认即可，也可以按需配置，如：/example_base；（注意：此处base path按照需求填写即可，对工作流接入没有影响）
4. 协议：选择自定义；
点击确定完成Agent API创建。

步骤3：配置路由（定义调用路径）

完成步骤2：配置Agent API后，会进入到Agent API详情页，需要继续完成路由配置

在Agent API详情页，选择路由列表>创建路由；
在创建路由页面，进行如下配置：
1. 路由名称：自定义路由名称，创建后路由名称不可修改；
2. 路径（Path）：按需配置，如：/example_path，后续使用API调用工作流时，路径需与此处配置一致；（注意：此处路径按照需求填写即可，对工作流接入没有影响）
3. Agent服务：服务类型选择单服务，服务名称选择步骤1：配置网关服务（绑定Flow Agent）中创建的服务名称；
4. 点击更多匹配规则，方法（Method）选择POST；
点击添加，完成路由创建；
在路由详情页，点击发布路由，并单击确定；
左侧路由列表显示已发布，表示发布成功。

使用API调用Flow Agent（最简示例）

完成上述配置后，可通过 HTTP POST 调用已接入 AI 网关的 Flow Agent；请求 body 将作为工作流输入。

调用示例

curl \
  -H "Content-Type: application/json" \
  http://<YOUR_AI_GW_ENDPOINT>/<base_path>/<route_path> \
  -d '{
    "sys.query": "Hello, who are you?"
  }'

请求参数说明

参数	说明	示例
`<YOUR_AI_GW_ENDPOINT>`	生产环境替换为 Agent API 中配置的自定义域名；测试可使用 AI 网关接入点。	`ai******-gw.cn-hangzhou.fcapp.run` 或 `api.yourcompany.com`
`<base_path>`	Agent API 中配置的 Base Path。	`/example_base`
`<route_path>`	路由中配置的路径。	`/example_path`
`sys.query`	通过 body 传入的内置变量（在 Flow 开始节点可查看）；也可传入自定义变量。	`{ "sys.query": "Hello, who are you?", "context": "your_context", "doc_md": "doc_md", "number": 123, "type": "a" }`

响应示例：

{
  "FlowName":"agent-flow-KRbWd",
  "Name":"0758c9e9-808c-****-a3b2-18c86d3453e2",
  "SessionId":"",
  "Output":"{\"answer\":\"Hello! I'm Qwen, a large-scale language model independently developed by the Tongyi Lab under Alibaba Group. I can assist you with answering questions, writing, logical reasoning, programming, and more. I support multiple languages and am happy to help you! Is there anything I can assist you with?\"}",
  "ErrorCode":"",
  "ErrorMessage":"",
  "Status":"Succeeded",
  "RequestId":"becb807b-****-49cc-3604-20a823a8f599",
  "StartedTime":"2026-02-03T09:31:56.092Z",
  "StoppedTime":"2026-02-03T09:32:00.531Z",
  "Environment":{
    "Variables":[]
  }
}

参数说明

名称	类型	描述
FlowName	string	流程名称
Name	string	执行名称，服务端生成
SessionID	string	SessionID，会话模式中返回
Output	string	流程的执行输出
ErrorCode	string	流程执行的错误码，流程执行失败时返回
ErrorMessage	string	流程执行的错误信息，流程执行失败时返回
Status	string	流程的执行状态
RequestId	string	请求 ID
StartedTime	string	流程执行开始时间
StoppedTime	string	流程执行结束时间
Environment	Environment	流程执行时使用的环境变量配置信息

兼容协议说明

通过 AI 网关调用Flow Agent与使用 Endpoint 调用 Flow Agent兼容的协议以及调用方式一致，每种协议均支持流式/非流式，调用时将Endpoint地址替换为对应的URL：http://<YOUR_AI_GW_ENDPOINT>/<base_path>/<route_path>。

AgentRun Endpoint调用示例（原生非流式）

AI网关调用示例（原生非流式）

curl https://<your-account-id>.agentrun-data.cn-hangzhou.aliyuncs.com/flows/<FlowName>/endpoints/<EndpointName>/invocations -XPOST \
  -H "content-type: application/json" \
  -d '{
    "sys.query": "你好",
    "sys.conversation_id": "conversation_id",
    "sys.user": "user-abc"
  }'

curl http://<YOUR_AI_GW_ENDPOINT>/<base_path>/<route_path> -XPOST \
  -H "content-type: application/json" \
  -d '{
    "sys.query": "你好",
    "sys.conversation_id": "conversation_id",
    "sys.user": "user-abc"
  }'

支持的协议与对应的请求头：

协议	说明	典型用途	必需的请求头 (x-fnf-flow-agent-protocol)
Dify Workflow	与 Dify 工作流运行接口兼容	从 Dify 或自建系统以工作流方式调用	`dify-workflow-compatible`
Dify Chatflow	与 Dify 对话流接口兼容	对话/聊天场景，支持会话与流式输出	`dify-chatflow-compatible`
OpenAI	与 OpenAI Chat Completions 兼容	使用 OpenAI SDK 或兼容客户端调用	`openai-chat-completion-compatible`
原生协议	AgentRun 原生入参格式	直接映射到 Flow 开始节点声明的字段	不需要

说明：

协议指定头（x-fnf-flow-agent-protocol）：对于 Dify Workflow、Dify Chatflow、OpenAI 这三种协议，必须设置此请求头，其值必须是表格中列出的对应字符串。不指定时默认为原生协议。
原生协议：原生协议没有内置的流式控制标志。启用流式输出只能通过设置请求头 x-fnf-param-stream: true 来实现。