企业官网建设流程全解析

本篇技术指南以 RocketRide 仓库中的agent_llamaindex节点为核心，讲解如何用 LlamaIndex 的 ReAct 循环实现"逐步推理 + 按需调用工具"的 Agent 节点：它接收questions通道的问题，自主决定何时调用已连接的 LLM 与工具，最终在answers通道输出答案，并可作为子 Agent 被父级 Agent 通过run_agent工具编排调用。读完本文，你将掌握该节点的连接方式、三种典型管线（HTTP 问答、向量库检索、分层 Agent 编排）、全部配置参数的作用边界，以及 ReAct 推理循环与防幻觉守卫在源码层面的实现机制。

节点定位：基于 LlamaIndex ReAct 的通用 Agent

agent_llamaindex是一个 RocketRide Agent 节点（节点目录），其职责非常聚焦：接收一个问题，通过 ReAct 循环逐步推理并调用已连接的工具，直到得到最终答案，再把答案写回answers通道。它在services.json中被声明为classType: ["agent", "tool"]，即既可以作为普通管线节点运行，也可以被其他 Agent 当作工具调用。

底层依赖是 LlamaIndex 生态中的检索与索引工具包，尤其是其 ReAct 风格的 Agent——它把"推理（reasoning）"与"工具调用（tool use）"交错进行，让模型在回答前先收集自己需要的信息。这是该节点的设计灵魂：推理循环是纯文本格式（模型输出Thought / Action / Action Input），因此不要求 LLM 原生支持 function-calling，任何能遵循该格式的模型（包括本地小模型）都可以驱动它。

在 RocketRide 的 Agent 框架中，该节点通过LlamaIndexDriver实现共享的ai.common.agent.AgentBase接口（见 llamaindex.py），框架标识FRAMEWORK = 'llamaindex'。它复用了AgentBase.run_agent统一入口（agent.py）来处理配置解析、指令合并、工具发现与答案输出。

连接与通道：两进一出的最小拓扑

节点的连接与通道定义在 services.json 中，控制平面（control-plane）有两个通道：

数据平面（lane）只有一个方向对：

值得强调的是：不连工具节点也能运行——此时它退化为"一次性问答器"（single-shot question answerer）。工具才是 ReAct 循环真正发挥价值的地方：模型可以按需决定是否调用、调用哪个工具、如何解读工具返回的观察（observation），而不是让每个问题都被强制走一遍检索流程。

三个示例管线：从 HTTP 问答到分层 Agent

仓库中的 example.pipe 给出了一个可直接导入的完整画布配置，拓扑为：

chat → agent_llamaindex → response_answers

其中llm_anthropic（profile 为claude-sonnet-4-6，API Key 取自${ROCKETRIDE_ANTHROPIC_KEY}环境变量）接到节点的llm通道，tool_http_request接到tool通道。问题从 chat 进入，Agent 自主决定何时调用 API、读取响应，最终给出有依据（grounded）的答案。

场景一：用 HTTP 工具回答实时问题

将tool_http_request接到tool通道即可。适用于"答案依赖外部 API 实时数据"的管线，例如查询天气、汇率、文档接口等。Agent 会先在推理中判断"需要调用 API"，然后执行工具并基于返回内容组织答案。

场景二：基于自有文档的研究型 Agent

把 HTTP 工具换成store_qdrant（向量数据库节点）：Agent 按需搜索向量库，而不是让每个问题都强制经过检索，然后基于检索结果回答。这种"按需检索"模式在长文档、知识库问答中非常常见——模型先推理"这个问题需要查资料吗"，再决定是否触发检索，比固定 RAG 流程更省调用、也更灵活。

场景三：作为专业子 Agent 嵌入更大 Agent 层级

将一个agent_rocketride节点作为父 Agent，把本节点连到其tool通道，并务必填写Agent description（见下文配置节）。父 Agent 通过<nodeId>.run_agent调用子 Agent 并取回答案，实现"总控 Agent 分工调度多个专业子 Agent"的层级编排。

配置详解：三个字段塑造行为

默认 profile（"default"）无需任何配置即可运行——连上 LLM 即可。Schema 中可配置字段如下（services.json 与 README 中自动生成的 Schema 表一致）：

Agent description：父 Agent 选人时的唯一依据

仅在本节点作为工具被父 Agent 调用时才有意义。父 Agent 决定是否委派时只能读到这段文字——它看不到你的 Instructions、工具清单或 LLM 配置。所以它必须具体、行动导向：像 "Searches internal documentation and answers with citations" 这样的描述会被采纳，而 "helper agent" 这种泛泛描述永远不会被选中。在源码中，它会被拼进run_agent工具函数的 description（见 IInstance.py），父 Agent 正是在所有子 Agent 的run_agent描述之间做选择的。如果没有任何 Agent 会以工具方式调用本节点，留空即可。

Instructions：领域规则与语气，而非工具用法

每一行都会被追加到内置 ReAct prompt 之后（基础类已在run_agent中完成指令合并，见 llamaindex.py 的注释）。内置 prompt 已经处理好了推理脚手架（Thought/Action 格式），所以这里适合写领域规则与语气，例如 "prefer primary sources"（优先使用一手来源）、"answer in the user's language"（用用户的语言回答）——不要去复述如何使用工具，那是循环本身已经覆盖的部分。同时要注意：对较小的模型，指令加得过多反而有害，因为其指令遵循能力会随 prompt 变长而退化。

Require tool call：防幻觉守卫

默认关闭。开启后，如果一次运行在没有调用任何工具的情况下就产出答案，会以RocketRide.agent.guard.v1错误代替文本返回，而不是把未经验证的内容交出去。

这个守卫针对的是一个真实存在的失败模式：较弱的规划模型有时会用散文"叙述"工具链——描述它"搜索过"但其实从未执行——并产出一个看似合理但无依据的答案。建议在确定性至关重要的管线（不允许出现无依据答案）中开启它。注意两点：

• 它只统计真实的工具调用；内部本地读取不算数。
• 对于可以合法地凭模型自身知识作答的 Agent，保持关闭。

在实现层面，守卫由AgentBase统一执行：parse_bool(config.get('require_tool_call'), False)解析配置（agent.py），未调用工具即作答时抛出ToolCallRequiredError，由run_agent捕获并转为RocketRide.agent.guard.v1错误答案。仓库测试 test_agent_base.py 与 test_require_tool_call_integration.py 分别从单元与端到端两个层面验证了该行为。

作为工具被调用：run_agent的输入输出契约

当本节点连接到父 Agent 时，它对外暴露一个函数：

输入为{query: string, context?: object}：

• query必须是非空字符串（源码中做了严格校验，见 IInstance.py）；
• 可选的context对象会以类型为RocketRide.agent.tool_context.v1的 context entry 传给子 Agent（序列化逻辑见 IInstance.py）。

输出为{content, meta, stack}，其中stack是本次运行经历的推理步骤列表。关键行为：作为工具被调用时，答案返回给调用方，而不是写到answers通道——这正是run_agent中emit_answers_lane=False的作用（IInstance.py）。

推理循环的内部原理：手驱 ReAct，最多 10 步

README 明确说明了实现细节（llamaindex.py 可逐一印证）：节点使用llama-index-core提供 ReAct 脚手架（ReActChatFormatter负责把工具与历史格式化进 prompt，ReActOutputParser负责解析模型的输出），但循环本身由节点驱动，而非 LlamaIndex 的异步 Agent。原因是 RocketRide 的 LLM 调用通道是同步返回纯文本的，所以每个回合的执行顺序是：

1. 用ReActChatFormatter格式化 prompt（工具描述 + 对话历史 + 当前推理步骤）；
2. 调用宿主 LLM，以Observation:作为停止词（stop_words=['Observation:']，见 llamaindex.py）；
3. 用ReActOutputParser解析模型输出的Thought / Action / Action Input，或直接识别为最终Answer。

工具执行走的是宿主的控制平面call_tool，而不是 LlamaIndex——已连接的工具被包装成仅含元数据的FunctionTool：_build_tools从工具描述符中提取名称、描述与输入 JSON schema，把 schema 序列化进描述字符串后交给FunctionTool（实际执行时再通过call_tool转发，见 llamaindex.py）。这样模型能在 prompt 里看到每个工具的输入 JSON schema，从而正确构造Action Input。

几个关键边界行为：

• 迭代预算：循环最多运行10 次（_MAX_ITERATIONS = 10，llamaindex.py）。若耗尽预算仍无最终答案，节点返回"Agent stopped after reaching the maximum number of reasoning steps."。
• 不可解析输出：无法被解析为 ReAct 步骤的输出会被当作直接答案；如果以Thought:开头，会先剥离该前缀（_clean_answer），避免推理脚手架泄漏给读者。
• 工具异常可恢复：工具调用抛错并不会致命——错误会被作为观察（observation）反馈给模型，格式为{tool, error, type}，让模型有机会自我纠正后继续推理（llamaindex.py）。

进度与可追踪性

• 进度流：运行过程中的关键事件通过thinkingSSE 通道实时流式推送，例如"Starting LlamaIndex agent..."和"Calling <tool>..."（llamaindex.py 与 #L121）。
• 推理栈：每一步工具调用都被记录为{action, action_input, observation}三元组并追加进返回的stack（llamaindex.py）。这意味着无论答案最终走answers通道还是作为工具返回值，你都能拿到完整的推理轨迹用于调试与审计。

运行时依赖与快速上手

• 依赖：节点唯一的 Python 依赖是llama-index-core（见 requirements.txt），在IGlobal.beginGlobal中通过depends(requirements)按需解析（IGlobal.py），CONFIG 模式下跳过加载以支持配置预览。
• 快速验证：导入 example.pipe 到画布，按上文三个场景之一接线即可运行；默认 profile 零配置，连上 LLM 就能问答，接上工具即获得完整 ReAct 能力。

小结：agent_llamaindex把 LlamaIndex 的 ReAct 循环以"手驱 + 宿主控制平面执行"的方式接入 RocketRide 管线，换来的是对任意 LLM 的兼容性、按需工具调用的灵活性，以及通过run_agent融入多层 Agent 编排的能力。三个配置字段（描述、指令、强制工具调用守卫）分别回答了"父 Agent 怎么选我""我按什么规则推理""无依据答案是否被允许"三个问题——理解它们的边界，就能让这个节点在从简单问答到确定性严格管线的各类场景中都表现可靠。