AI Agent平台CoPaw源码学习——系统层级概览:04 Agent运行层

Agent 运行层是 CoPaw 的核心业务层，负责接收用户查询、创建和执行 AI Agent、管理会话历史，并流式返回执行结果。它是渠道和 AI 能力之间的桥梁。

这是 CoPaw 系统的大脑。

核心职责

1. 查询处理：接收并处理用户查询
2. Agent 创建：每次查询创建新的 Agent 实例
3. ReAct 循环：执行推理-行动-观察循环
4. 会话管理：通过 JSON 文件持久化会话状态
5. 流式输出：异步流式返回执行结果

核心组件

1. AgentRunner（Agent 运行器）

路径：src/copaw/app/runner/runner.py

职责：系统核心调度器，管理 Agent 查询的完整生命周期

核心功能：

• stream_query(request)：核心方法 — 接收 AgentRequest，创建 CoPawAgent，执行查询，流式返回事件
• Session 管理：通过 SafeJSONSession 进行 JSON 文件持久化
• MCP 客户端注入：注入 MCP 工具到 Agent
• Chat Manager 集成

2. CoPawAgent（ReAct Agent）

路径：src/copaw/agents/react_agent.py

核心功能：

• 构建 Toolkit：注册 14 个内置工具 + MCP 工具 + Skills
• 加载技能：从 3 级目录系统加载 Markdown 技能文件
• ReAct 循环：Reasoning → Action → Observation 迭代
• 命令处理：特殊指令处理（如 /help、/clear、/compact、/new）

关键特性：每次查询创建新实例，无跨查询状态

3. ChatManager（聊天管理器）

路径：src/copaw/app/runner/session.py（实际为 Session 管理）

职责：聊天会话的持久化管理

4. Session（会话持久化）

路径：src/copaw/app/runner/session.py

职责：会话状态的序列化和反序列化

实现：SafeJSONSession — JSON 文件读写，保证原子性

5. Model Factory（模型工厂）

路径：src/copaw/agents/model_factory.py

职责：根据配置创建对应的 LLM 模型实例

支持：云端供应商 + 本地模型

6. Prompt Builder（提示词构建器）

路径：src/copaw/agents/prompt.py

职责：构建 Agent 的系统提示词

功能：组合基础提示 + 技能描述 + 工具说明

7. Command Handler（命令处理器）

路径：src/copaw/agents/command_handler.py

职责：处理用户特殊命令（非 AI 推理的直接指令）

查询执行流程

1. 接收 AgentRequest    ↓2. 加载/创建 Session    ↓3. 创建新 CoPawAgent 实例    ↓4. 注册工具和技能    ↓5. 注入 MCP 客户端    ↓6. 执行 ReAct 循环    ├─ Reasoning：LLM 推理当前状态    ├─ Action：调用 Tool 或 Skill    └─ Observation：获取结果，继续推理或完成    ↓7. 流式返回事件    ↓8. 保存 Session

关键代码路径

src/copaw/├─ agents/│ ├─ react_agent.py          # CoPawAgent (ReAct)│ ├─ model_factory.py        # 模型工厂│ ├─ prompt.py               # 提示词构建│ ├─ schema.py               # Agent 数据结构│ └─ command_handler.py      # 命令处理器├─ app/runner/│ ├─ runner.py               # AgentRunner 核心│ ├─ session.py              # 会话持久化│ ├─ manager.py               # ChatManager│ ├─ api.py                  # Runner API 路由│ ├─ models.py               # 数据模型│ ├─ utils.py                # 工具函数│ ├─ query_error_dump.py     # 错误转储│ └─ repo/                   # 持久化仓库

技术实现

核心设计模式：

1. 无状态 Agent：每次查询创建新 CoPawAgent 实例，状态通过 Session 文件持久化
2. ReAct 模式：Reasoning-Action-Observation 循环
3. 流式生成器：使用 AsyncGenerator 流式返回事件
4. 工厂模式：ModelFactory 根据配置动态创建模型实例

运行时限制：

• max_iters：最大迭代次数（默认 50）
• max_input_length：最大输入长度（默认 128K）

内置工具（CoPawAgent 初始化时注册，共 14 个）：

• execute_shell_command：Shell 命令执行
• read_file / write_file / edit_file：文件操作
• grep_search / glob_search：文件搜索
• browser_use：浏览器控制
• desktop_screenshot：桌面截图
• view_image / view_video：媒体查看
• send_file_to_user：文件发送
• get_current_time：获取时间
• set_user_timezone：设置时区
• get_token_usage：Token 统计

与其他层的交互

上层依赖（被调用）：

• API 路由层：通过 app.state.runner 调用
• 渠道通信层：通过 runner.stream_query 作为 process 回调
• 定时任务系统：定时触发查询

下层调用：

• 技能与工具层：Agent 调用注册的工具和技能
• 记忆系统：Agent 读写记忆上下文
• 模型层：通过 Model Factory 调用 LLM
• MCP 集成：注册 MCP 工具到 Toolkit
• 配置层：读取 Agent 配置参数

重要设计细节

1. 无状态设计：保证了并发安全，每次查询独立处理

2. SafeJSON 保证原子性：Session 文件写入不会损坏

3. 运行时切换模型：Model 工厂支持运行时切换 LLM 供应商

4. 错误转储：查询出错时自动保存错误转储（query_error_dump.py）

总结

Agent 运行层是 CoPaw 系统的核心引擎：

• 无状态设计：每次查询创建新实例，避免并发问题
• ReAct 循环：推理-行动-观察，标准 Agent 范式
• 流式输出：AsyncGenerator 异步返回，减少等待
• Session 持久化：SafeJSON 保证数据安全
• 工具集成：8 个内置工具 + MCP 工具 + 技能
• 运行时限制：防止无限循环

这层把来自渠道的原始请求，转化为 AI 能理解的任务，执行推理，返回结果。是 CoPaw 智能能力的来源。