规划引擎模块设计¶

当前通用数据任务主要由 Flex/ReAct 引擎承载。用户通过 YAML 配置模型、场景说明、工作流节点和工具，运行时由 Planner 与 Executor 交替完成“规划-执行-观察-继续规划”的循环。

1. 配置入口¶

AGENT_CONFIG:
  name: "data agent"
  backend: "langgraph"
  type: "react"

PRE_WORKFLOW: []

ACTOR_LOOP:
  - node: "planner"
    module: "dataagent.core.flex.nodes.planner.Planner"
    chat_model:
      name: "chat_model"
  - node: "executor"
    module: "dataagent.core.flex.nodes.executor.Executor"

POST_WORKFLOW: []

type: "react" 会选择当前 Flex/ReAct 实现。ACTOR_LOOP 中的 Planner 负责生成下一步动作或最终回答，Executor 负责执行工具调用并把结果写回状态。

1. 整体架构¶

规划引擎基于有向图工作流构建，由三个顺序阶段组成：

阶段	说明
前置工作流	进入主循环前执行的一组固定节点，通常用于环境准备或上下文初始化
主循环	核心 ReAct 循环，由规划节点和执行节点交替运行
后置工作流	主循环结束后执行的收尾节点，用于结果整理或资源释放

多数场景下前置和后置工作流保持为空，仅需配置标准的主循环节点。

2. 配置驱动¶

用户通过 YAML 声明式配置定义 Agent 的全部行为。入口配置包含以下关键部分：

Agent 基础配置：指定后端引擎类型（如 LangGraph）、运行模式、调试开关等。
场景描述：定义 Agent 的角色身份、任务边界、行为约束和输出规范。这是调整 Agent 行为的首要切入点。
模型配置：指定各节点使用的对话模型。
工具与环境配置：声明可用的工具集合和执行环境。

主循环节点在配置中以列表形式声明，每个节点指定其模块路径和所需的模型绑定。框架按列表顺序构建节点间的路由关系。

3. 工作流路由¶

主循环内部由路由器控制节点间的转移逻辑：

循环路由：在规划节点和执行节点之间形成闭环。规划节点产出的工具调用被路由到执行节点；执行完成后结果返回规划节点继续推理。
终止判断：当模型给出最终回答（不再产生工具调用）、达到最大循环轮次、触发上下文长度限制或发生不可恢复错误时，循环自动结束。
人机交互：支持在主循环中插入人工确认节点，允许外部反馈干预 Agent 的决策流程。

路由器的核心参数包括最大迭代次数和token上限，均可在配置中覆写。

4. 规划节点¶

规划节点是推理的核心，负责：

提示组织：将场景指令、工具清单、历史消息和运行状态组装为结构化的提示，送入对话模型。
推理与决策：模型根据当前上下文决定下一步动作——调用某个工具，或直接给出最终回答。
多格式兼容：自动处理不同工具调用格式之间的转换，确保与底层模型解耦。

规划节点的提示模板采用分层设计：框架内置的基础提示提供通用能力描述，用户通过场景配置追加的指令会注入模板中的预留槽位，实现"只追加、不替换"的扩展方式。

5. 执行节点¶

执行节点负责将规划节点产出的工具调用落实为实际执行：

统一工具接口：所有工具——无论来自本地函数、MCP 服务还是 A2A Agent——均通过统一的调用协议执行。执行节点不关心工具的具体来源。
并发控制：支持对多个工具调用进行并发执行，并发度可通过配置调整。
参数校验：对工具调用参数进行模式校验，确保传入值符合工具定义的预期格式。
结果截断：对过长的工具返回内容进行长度限制，防止上下文膨胀。
错误分类：将执行异常归类为可重试错误、可恢复错误和不可恢复错误，辅助上游决定后续策略。

6. 工具体系¶

工具由统一的管理器注册和发现，当前支持的来源包括：

本地函数：直接注册的 Python 函数，框架将其包装为可调用工具。
MCP 服务：通过 MCP 协议接入的外部工具服务，支持标准输入输出和 HTTP 两种通信方式。
A2A Agent：其他 Agent 作为工具被当前 Agent 调用，实现 Agent 间协作。
框架内置工具：系统预置的通用工具。

所有工具均提供结构化的名称、描述、参数定义，供规划节点在推理时参考选调。

7. 运行状态¶

引擎在运行过程中维护一个统一的状态对象，贯穿所有节点：

消息历史：完整的对话记录，包括用户输入、模型回复和工具调用结果。
执行统计：累计的对话轮次、有效工具调用次数、无效调用次数等。
会话标识：用户、会话、运行实例等关联信息。
终止标记：标识当前任务是否已完成。
跨会话记忆：从历史会话中检索的摘要信息，用于长周期任务的上下文延续。

8. 调试建议¶

当 Agent 表现不符合预期时，建议优先排查以下方面：

场景指令：是否清晰约束了 Agent 的角色、边界和终止条件。指令过于模糊会导致模型漫无目的地调用工具；过于严格则可能提前终止。
工具描述：工具的名称和描述是否准确反映了其功能。模型依赖工具描述做出选调决策，不准确的描述会引发误调用。
循环限制：最大迭代次数和令牌上限是否过小，导致任务被截断；或过大，导致资源浪费。
工具返回：工具返回的内容是否足够简洁且信息充分，供模型准确判断下一步动作。