调用协议说明（原生协议）-函数计算(FC)-阿里云帮助中心

本文说明如何使用原生协议调用 Flow Agent，包括请求地址与 Body 格式、输入变量映射、同步/流式两种调用方式以及响应字段含义。适用于需要将请求参数直接映射到流程开始节点、通过 URL 传入文件或多模态数据、或在流式模式下监控各节点执行进度的场景。

适用场景

自定义输入：流程中有多个自定义变量（如风格、字数、业务参数等），希望请求 Body 与开始节点字段一一对应。
多模态入参：通过 URL 传入图片、文档等文件供流程使用。
流式与节点监控：需要流式返回内容（如打字机效果）或按节点粒度监控开始/结束状态。

前置条件

已创建并发布 Flow Agent：在AgentRun控制台通过 Flow 创建并发布 Agent。操作步骤见低代码创建Agent快速入门。
已获取调用地址：在 Agent 详情页集成与发布 > 代码集成中查看 Endpoint与调用示例。下文示例中的Host与Flow名称需替换为您自己的值。

流程执行输入

请求Body为标准 JSON 格式。

变量映射规则

Body 中的 Key 必须与 Flow 开始节点中的声明对变量名完全一致。

变量类别	变量名示例	说明
内置系统变量	`sys.query`	用户当前输入的文本问题。
	`sys.user_id`	用户的唯一标识符，用于区分用户。
	`sys.conversation_id`	会话 ID，用于关联历史上下文。
自定义变量	`var_1`, `topic` 等	在开始节点中手动添加的变量。
文件变量	`file` 或 `files`	每项需包含可公网访问的URL。

调用示例

将以下占位符替换为实际值：

占位符	说明
`<your-account-id>`	账号 ID，与控制台 Endpoint 中的域名一致。
`<FlowName>`	流程名称。
`<EndpointName>`	端点名称。

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.user_id": "user_abc",
    "sys.conversation_id": "conversation_id",
    "topic": "田园风",
    "files": [
      {
        "url": "https://example.com/image.jpg"
      }
    ]
  }'

流程执行输出

流程的返回内容由执行结束时最后一个节点的输出决定。可在流程分支末尾添加结束节点，统一输出结构。

若结束节点声明了 output_1、output_2、output_3，请求示例与响应示例见下。

请求示例：

curl https://<your-account-id>.agentrun-data.cn-hangzhou.aliyuncs.com/flows/<FlowName>/endpoints/<EndpointName>/invocations -XPOST \
  -H "content-type: application/json" \
  -d '{
    "var_1":"value_1",
    "var_2":"value_2",
    "var_3":"value_3"
  }'

响应示例：

{
  "FlowName":"agent-flow-K9Dfu",
  "Name":"1bf58bef-e61b-4dbf-a400-b4ce2f30****",
  "SessionId":"",
  "Output":"{\"output_1\":\"value_1\",\"output_2\":\"value_2\",\"output_3\":\"value_3\"}",
  "ErrorCode":"","ErrorMessage":"",
  "Status":"Succeeded",
  "RequestId":"8c87f02e-7a40-e93c-6bec-4f4007ac****",
  "StartedTime":"2026-02-03T08:28:03.496Z",
  "StoppedTime":"2026-02-03T08:28:04.405Z",
  "Environment":{
    "Variables":[]
  }
}

调用方式

同步非流式调用

适用于一次性获取最终结果、无需实时展示生成过程的场景。

请求 Header: Content-Type: application/json
响应：等待流程全部执行完毕后返回完整的 JSON 响应。

响应示例：

{
  "FlowName": "spring_copy_agent",
  "Name": "exec_5037cf...",
  "Output": "{\"text\":\"春意盎然，万物复苏...\"}", 
  "Status": "Succeeded",
  "RequestId": "84fd9a0a-..."
}

注意：Output 字段是一个被转义的 JSON 字符串。开发者获取后需要对其进行第二次 JSON 解析，以提取内部的变量值。

同步流式调用

适用于需要逐字/逐段展示内容（如对话机器人）或按节点监控进度的场景。

请求 Header:
- Content-Type: application/json
- Accept: text/event-stream 或 x-fnf-param-stream: true

流式事件说明 (Event Types)

流式响应采用 SSE（Server-Sent Events）协议，每行 data: 对应一种事件类型：

事件类型	说明	核心字段解析
节点事件 (StateMachine)	流程节点的开始/结束	`StepName`（节点名）、`Action`（Started/Finished）
回复事件 (AnswerEvent)	流式输出节点输出的文本内容	`Text`（当前增量文本内容）
LLM 块事件 (LLMChunk)	模型节点的原始流式数据。	`Chunk`（符合 OpenAI 规范的片段内容）

响应流示例：

data: {"StateMachine": {"StepName": "LLM_Node", "Action": "Started"}, "EventId": "..."}

data: {"Answer": {"Text": "春"}, "EventId": "..."}

data: {"Answer": {"Text": "天"}, "EventId": "..."}

data: {"StateMachine": {"StepName": "LLM_Node", "Action": "Finished"}, "EventId": "..."}

响应字段说明

字段名	类型	描述
`FlowName`	string	所执行的流程名称。
`Name`	string	本次执行的唯一 ID（Execution ID）。
`SessionId`	string	会话 ID，与请求中的 `sys.conversation_id` 一致。
`Output`	string	结束节点的输出，为转义后的 JSON 字符串。
`Status`	string	执行状态：`Running`、`Succeeded`、`Failed`。
`ErrorCode`	string	错误码，成功时为空。
`ErrorMessage`	string	错误详情。
`RequestId`	string	平台请求追踪 ID。

注意事项

Output 解析：Output 为转义 JSON 字符串，通常需要两次解析（先解析响应体，再解析 Output 字符串）才能得到内部变量。
文件上传：原生协议不处理文件二进制流。需先将文件上传至 OSS 等存储并生成可公网访问的 URL，再在请求中传入该 URL（如 remote_url 或 url）。