Agent/agent/execution

Agent Execution - 执行追踪系统

职责

执行追踪系统负责记录和可视化 Agent 的执行过程：

1. 数据模型 (models.py)

   • Trace - 一次完整的执行轨迹
   • Step - 执行过程中的一个原子操作（形成树结构）
   • StepType - 步骤类型（思考、动作、结果等）
   • Status - 步骤状态（计划中、执行中、完成、失败）

2. 存储接口 (protocols.py, store.py)

   • TraceStore - Trace 存储接口协议
   • MemoryTraceStore - 内存实现（用于测试）

3. 可视化工具 (tree_dump.py)

   • dump_tree() - 输出文本格式的 step tree
   • dump_markdown() - 输出 markdown 格式（可折叠）
   • dump_json() - 输出 JSON 格式

4. API 和实时推送 (api.py, websocket.py)

   • RESTful API - 查询 Trace 和 Step
   • WebSocket - 实时推送执行更新

模块边界

• 只依赖：core（事件系统）
• 被依赖：core.runner（记录 trace）
• 独立开发：可视化、API、WebSocket 可独立迭代

使用示例

from agent.execution import MemoryTraceStore, Trace, Step, dump_tree

# 创建存储
store = MemoryTraceStore()

# 创建 Trace
trace = Trace.create(mode="agent", task="Complete task")
trace_id = await store.create_trace(trace)

# 添加 Step
step = Step.create(
    trace_id=trace_id,
    step_type="thought",
    description="Analyzing task"
)
await store.add_step(step)

# 可视化
trace = await store.get_trace(trace_id)
steps = await store.get_trace_steps(trace_id)
dump_tree(trace, steps)

文件说明

• models.py - Trace 和 Step 数据模型
• protocols.py - TraceStore 接口定义
• store.py - MemoryTraceStore 实现
• tree_dump.py - Step tree 可视化工具
• api.py - RESTful API（可选，需要 FastAPI）
• websocket.py - WebSocket 推送（可选，需要 FastAPI）
• __init__.py - 模块导出

适合分工

• 算法同事：负责 tree_dump.py 可视化优化
• 后端同事：负责 api.py 和 websocket.py 开发