aiagent/docs/architecture/AI agent改造计划.md

从工作流引擎到自主 AI Agent：改造方案 核心思路：不要重构，要"寄生式"生长 现有引擎 5788 行，WorkflowEditor.vue 9140 行——不要重构它们。而是寄生在已有的 ToolRegistry、LLM Service、Memory Service 之上，新建一个独立的 Agent Runtime。

第一步：构建 Agent Runtime 内核（1 周）

新建 backend/app/agent_runtime/ 包：

backend/app/agent_runtime/ ├── init.py ├── core.py # Agent 主循环 ├── context.py # Agent 上下文（会话状态） ├── memory.py # 记忆管理（连接已有记忆服务） ├── tool_manager.py # 工具选择与执行（连接已有 ToolRegistry） └── schemas.py # Agent 配置 Schema

核心循环 (core.py)：

class AgentRuntime: """ 自主 Agent 循环（ReAct）

  loop:
      1. LLM 思考 → 返回文本或工具调用
      2. 如果返回文本 → 结束，返回最终回答
      3. 如果调用工具 → 执行工具 → 结果追加到 messages → 回到 1
      4. 超过 max_iterations → 强制结束
  """

  async def run(self, user_input: str) -> AgentResult:
      while self.iteration < self.max_iterations:
          response = await self.llm.chat(messages, tools)
          if response.has_tool_calls:
              for tool_call in response.tool_calls:
                  result = tool_registry.execute(tool_call)
                  messages.append(tool_result_message)
          else:
              return AgentResult(text=response.content)
      return AgentResult(text="已达最大迭代次数", truncated=True)

关键设计点：

┌────────────┬─────────────────────────────────────────────────┬───────────────────────┐ │ 组件 │ 复用什么 │ 新写什么 │ ├────────────┼─────────────────────────────────────────────────┼───────────────────────┤ │ LLM 调用 │ llm_service.call_openai_with_tools() 已有 ReAct │ 不用写 │ ├────────────┼─────────────────────────────────────────────────┼───────────────────────┤ │ 工具执行 │ ToolRegistry.get_tool_function() │ 不用写 │ ├────────────┼─────────────────────────────────────────────────┼───────────────────────┤ │ 记忆存储 │ persistent_memory_service.py │ 记忆检索 + 自动压缩 │ ├────────────┼─────────────────────────────────────────────────┼───────────────────────┤ │ 系统提示词 │ — │ Agent 人格/指令系统 │ ├────────────┼─────────────────────────────────────────────────┼───────────────────────┤ │ 会话管理 │ — │ 状态保持 + 多轮上下文 │ └────────────┴─────────────────────────────────────────────────┴───────────────────────┘

工作量：约 300 行代码。已有轮子都在，只要串起来。

---

第二步：让 Agent Runtime 能用上已有工具（3 天）

现有 ToolRegistry 有 20+ 内置工具，但只通过 llm_service.py 的 _execute_tool 私有方法调用。需要：

新增 agent_runtime/tool_manager.py

class AgentToolManager: def init(self, tool_registry): self.registry = tool_registry

  def get_tools_for_llm(self) -> list:
      # 把 ToolRegistry 的 schema 转为 OpenAI tool format
      return self.registry.get_all_tool_schemas()

  async def execute(self, name: str, args: dict) -> str:
      func = self.registry.get_tool_function(name)
      if func is None:
          return f"错误：工具 {name} 不存在"
      result = await func(**args)  # 已有，直接复用
      return str(result)

注意：现有 _execute_tool 在 llm_service.py 中，需要提取成公共方法或让 ToolManager 直接调用已有实现。

---

第三步：接入记忆系统（3 天）

现有记忆系统已经可以读写用户画像和对话历史（persistent_memory_service.py），但只在 Cache 节点中被动使用。

需要：

agent_runtime/memory.py

class AgentMemory: """ 分层记忆： - 工作记忆：当前会话的 messages - 长期记忆：从 DB/Redis 加载的历史画像 + 重要事实 - 工具记忆：哪些工具调用成功/失败（辅助 LLM 决策） """

  async def load_context(self, user_id: str) -> str:
      # 从 persistent_memory_service 加载用户画像
      profile = get_user_profile(user_id)
      # 从数据库加载最近对话摘要
      history = get_conversation_summary(user_id)
      return f"用户画像：{profile}\n历史记录：{history}"

  async def save(self, messages: list):
      # 自动总结关键信息写入长期记忆
      summary = await self.llm.summarize(messages)
      save_user_profile(user_id, summary)

---

第四步：在现有工作流中启用 Agent 节点（3 天）

在 workflow_engine.py 的 execute_node 中新增 agent 类型：

现有 5788 行引擎只需加一个分支

elif node_type == 'agent': # 初始化 Agent Runtime runtime = AgentRuntime( system_prompt=node_data.get('system_prompt'), tools=node_data.get('tools', []), # 可选，默认全部 memory_enabled=node_data.get('memory', True), ) result = await runtime.run(input_data.get('query', ''))

这样不用动现有任何节点，用户可以在工作流中拖一个 Agent 节点，它就能：

1. 自动 ReAct 循环
2. 调用任意内置工具
3. 使用长期记忆
4. 自我纠错

---

第五步：独立 Agent 运行模式（1 周）

不依赖工作流 DAG，可以直接启动 Agent：

POST /api/v1/agents/{id}/chat {"message": "帮我写一个Python脚本读取日志"}

后端： runtime = AgentRuntime(agent_config) result = await runtime.run(message) return result

前端可以加一个聊天界面（类似 ChatGPT）：

• 已有 AgentChatPreview.vue 可以改造
• 复用现有 Agents.vue 的列表和配置

---

第六步：多智能体编排（2 周）

agent_runtime/orchestrator.py

class AgentOrchestrator: """ 多 Agent 协作模式：

  1. 路由模式：用户问题 → Router Agent → 分发到子 Agent
  2. 顺序模式：Agent A 输出 → Agent B 输入
  3. 辩论模式：多个 Agent 独立回答 → 汇总
  """

  async def route(self, question: str) -> str:
      # Router Agent 判断应该用哪个 Specialist Agent
      specialist = await self.router_agent.choose(question)
      return await specialist.run(question)

---

整体路线图

┌──────┬────────────────────────┬──────┬────────────┐ │ 阶段 │ 内容 │ 时间 │ 前提 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P0 │ Agent Runtime 内核 │ 1 周 │ 无，纯新增 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P0 │ 工具接入 │ 3 天 │ P0 完成 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P1 │ 记忆接入 │ 3 天 │ P0 完成 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P1 │ Agent 节点（工作流内） │ 3 天 │ P0+P1 完成 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P2 │ 独立 Agent 聊天模式 │ 1 周 │ P0+P1 完成 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P3 │ 多 Agent 编排 │ 2 周 │ P0-P2 完成 │ ├──────┼────────────────────────┼──────┼────────────┤ │ P3 │ Agent 工作台/监控 │ 1 周 │ P0-P2 完成 │ └──────┴────────────────────────┴──────┴────────────┘

---

为什么这个方案可行

你代码库中 关键能力已经就绪：

┌─────────────────────────┬─────────────────────────────────────┬──────────────────┬────────────────┐ │ 已有能力 │ 位置 │ 当前用途 │ 新计划用途 │ ├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤ │ ReAct 循环 │ llm_service.py:646 │ LLM 节点单次调用 │ Agent 核心循环 │ ├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤ │ ToolRegistry + 20+ 工具 │ tool_registry.py + builtin_tools.py │ 工作流内使用 │ Agent 自主调用 │ ├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤ │ 持久化记忆 │ persistent_memory_service.py │ Cache 节点 │ 长期记忆层 │ ├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤ │ 对话历史注入 │ workflow_engine.py:986 │ LLM 节点 │ Agent 上下文 │ ├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤ │ Agent 配置 │ models/agent.py │ 工作流包装 │ Agent 本体配置 │ └─────────────────────────┴─────────────────────────────────────┴──────────────────┴────────────────┘

新增代码控制在 1500 行以内，不动现有 5788 行的引擎和 9140 行的编辑器。

需要我从第一步的 Agent Runtime 核心代码开始写吗？