[Bug]: Using the official interface to call the agent application in Ragflow, the parameters in the initial component cannot be passed in

问题场景

用户在 RAGFlow v0.20.1 中，通过官方提供的 HTTP API 从外部 Java 程序调用 Agent 应用。按照官方文档拼接请求参数并发起调用后，请求在 RAGFlow 中返回 102 状态码，提示缺少参数。同时用户发现应用内调用的接口与官方文档展示的接口不一致，且即使请求成功，也存在参数值为 null 的情况。

报错原文

[Bug]: Using the official interface to call the agent application in Ragflow, the parameters in the initial component cannot be passed in

The interface request in the application can be successful, but there may be cases where the value is passed as null

Debugging shows that the parameters have been concatenated and passed to the RagFlow interface. However, RagFlow returns a 102 status code, indicating that a certain parameter is missing

原因分析

根据 Issue 讨论与 RAGFlow 源码逻辑，此问题的可能原因是：

• 请求体结构不符合后端预期：Agent 的 API 期望 Begin（开始）节点的参数通过请求体中的 inputs 对象传入，并且每个参数值本身必须是一个包含 type 和 value 的嵌套对象。如果缺失 inputs 外层包裹，或者参数值直接以字符串等原始类型传入，后端校验会失败，返回 102。
• 参数名不匹配：后端对参数名校验区分大小写，且必须与工作流中 Start（开始）节点定义的参数名严格一致。
• 接口文档与实际后端逻辑不同步：用户在 v0.20.1 中看到的接口行为可能与最新文档不一致，存在文档更新滞后、前端与后端参数映射不一致的情况。

环境排查

• 确认 RAGFlow 镜像版本是否为 v0.20.1，以及后端 API 服务版本。
• 确认 Java 程序请求的 HTTP 方法（如 POST）和接口路径是否与 RAGFlow 当前版本实际暴露的端点一致。
• 检查工作流中 Start（开始）节点实际定义的参数名、参数类型（如 line、paragraph、file 等）。
• 确认请求体中 inputs 对象的嵌套层级和大小写是否正确。

解决步骤

1. 修改请求体结构：将 Begin 组件的所有参数放入顶层 inputs 对象中，且每个参数值使用 type 和 value 字段包裹。参考格式如下：

   {
     "inputs": {
       "typexie": {
         "type": "line",
         "value": "your_value_here"
       }
       // ... 其他参数
     }
   }

2. 核对参数名和类型：确保请求体中的参数名与工作流 Start（开始）节点配置的完全一致（区分大小写），且 type 字段与节点配置的参数类型匹配。
3. 通过接口确认必需参数：可在调试时调用 GET /api/v1/agents/{agent_id}/inputs，查看当前 Agent 的输入参数定义，确认需要在请求体中携带哪些参数。
4. 升级 RAGFlow 版本：v0.20.1 存在前端与后端参数映射和校验的已知修复（如 PR #8950、#9506）。如果部署环境允许，优先升级到最新稳定版本，并在新版本下重新测试接口调用的参数传递。
5. 核对文档与接口差异：若仍需在 v0.20.1 中工作，需要以源码或实际调试结果为准，而非完全依赖官方文档中的请求示例，必要时可抓包查看 WebUI 前端实际发送的请求格式作为参照。

验证方法

按照上述步骤调整请求体后，重新发起接口调用，观察返回状态码。若不再返回 102 且流程正常执行，说明参数传递成功。同时检查 Agent 运行日志中 Begin 节点接收到的参数值，确认不再出现 null 或缺失的情况。

参考来源

infiniflow/ragflow #9617

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。