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

适用场景

自定义输入：流程中有多个自定义变量（如风格、字数、业务参数等），希望请求 Body 与开始节点字段一一对应。
多模态入参：在请求中传入图片、文档等文件的公网 URL。
流式与节点监控：需要流式返回内容（如打字机效果）或按节点粒度监控开始/结束状态。
会话亲和性：多轮对话场景下保持上下文连续，确保同一会话的请求路由到同一执行实例。

前置条件

已创建并发布 Flow Agent：在AgentRun 控制台通过 Flow 创建并发布 Agent。操作步骤参见。
已获取调用地址：在 Agent 详情页中查看 Endpoint 与调用示例。下文中的 Host 与 Flow 名称需替换为实际值。

流程执行输入

请求 Body 为标准 JSON 格式，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 请求 Header。
- x-agentrun-session-id: <session-id>（可选）设置会话 ID，以保持会话亲和。同一会话的多次请求应使用相同的值，以确保上下文连续性和执行实例的一致性。

流式事件说明

流式响应采用 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` 一致。当请求中未传 `sys.conversation_id` 时，返回空字符串。
`Output`	string	结束节点的输出，为转义后的 JSON 字符串。
`Status`	string	执行状态：`Running`（仅在流式调用中间状态出现）、`Succeeded`、`Failed`。同步调用返回时 Status 为 Succeeded 或 Failed。
`ErrorCode`	string	错误码，成功时为空。
`ErrorMessage`	string	错误详情。
`RequestId`	string	平台请求追踪 ID。

验证调用结果

调用完成后，检查响应中的以下字段确认调用是否成功：

Status 字段值为 Succeeded。
ErrorCode 字段为空。

若 Status 为 Failed，请查看 ErrorMessage 字段获取错误详情。

注意事项

Output 解析：Output 为转义 JSON 字符串，通常需要两次解析（先解析响应体，再解析 Output 字符串）才能得到内部变量。
文件上传：请将文件上传至 OSS 等存储，生成可公网访问的 URL 后，在请求中传入该 URL。原生协议不支持直接传输文件二进制数据。
会话亲和性：使用 x-agentrun-session-id 时，同一会话的多次请求应保持该值不变。建议在客户端侧生成并缓存会话 ID，而非每次生成新值。