---
title: "Agent 运行时追踪（Runtime Trace）"
created: 2026-07-03
updated: 2026-07-03
type: concept
tags: ["agent", "runtime", "observability", "postgresql"]
sources: ["https://mp.weixin.qq.com/s/iiTmgbtrYHMMjQ7dn7CDrg"]
---

# Agent 运行时追踪

> 每一次循环都应该留下可复盘的轨迹——运行状态持久化到数据库，而非只在进程内存里跑一遍就丢掉。

## 核心定义

**Agent 运行时追踪** 是 [[zleap-workspace-harness-2026|Zleap-Agent]] 的 runtime 模块设计：将 Agent 循环的每一步操作（上下文读取、工具选择、工具调用、结果接收、策略修正）持久化到 PostgreSQL，使运行轨迹可审计、可回滚、可复盘。

## 为什么需要

一次真实 Agent 运行中：
- 模型读上下文 → 选工具 → 调用工具 → 接收结果 → 修正计划 → 再次调用工具
- 中间可能失败、重试、切换策略
- 也可能写入记忆或修改文件

如果只在内存里跑，出错后很难判断问题是：模型能力不够？工具说明不清楚？上下文带错了？记忆读错了？工具返回误导信息？

## 持久化内容

- 每一步读了什么文件/上下文
- 调用了什么工具、传了什么参数
- 拿到了什么返回结果
- 下一轮基于什么信息调整方案
- 最终是否成功

## 实验证据

- **WildClawBench**: 同一模型切换不同 harness，表现最高差 18 个百分点
- **Agentic Harness Engineering**: 通过多轮 harness 演化，Terminal-Bench 2 pass@1 从 69.7% 提升到 77.0%，收益主要来自 tools、middleware、long-term memory

## 与 Prompt 的分工

Prompt 主要作用于单轮输入输出；Harness 的 Runtime 层管理执行过程、状态变化、失败恢复和后续优化。二者是不同的工程表面。

## 参考

- [[zleap-workspace-harness-2026|Zleap-Agent Harness 设计]]
- [[agent-harness-engineering|Agent Harness Engineering]]
- [[loop-engineering|Loop Engineering]]
