Agent丨如何评估 Agent 的执行效果和项目效果？

type

Post

status

Published

date

May 11, 2026

slug

agent36

summary

1. 为什么 Agent 评估比普通 LLM 评估更复杂？

普通 LLM 应用大多是：

Agent 应用通常是：

Claude Code 的 Agent SDK 文档明确提到，一个 session 不只是对话文本，还包含 prompt、每一次 tool call、tool result 和每次 response；这说明 Agent 评估天然应该基于完整轨迹，而不是只看最终输出。(Claude Code)

OpenAI 的 Agent eval 文档也强调，trace 会记录一次运行中的 model calls、tool calls、guardrails 和 handoffs，并建议先用 trace grading 发现 workflow 级问题，再沉淀为 dataset 和 eval run。(OpenAI开发者)

因此，Agent 评估对象应该是：

Final Answer + Tool Trajectory + State Change + Permission Decision + Cost/Latency + Human Feedback + Business Outcome

2. 先给结论：Agent 评估的五层指标体系

可以把 Agent 评估拆成五层。

层级	评估对象	核心问题	典型指标
L1 最终结果	Agent 最后有没有完成任务	“事情办成了吗？”	Goal Accuracy、Task Success、Pass@1
L2 执行轨迹	工具调用路径是否合理	“过程对吗？”	Tool Call Accuracy、Tool Call F1、错误工具率
L3 系统效率	成本、延迟、轮次是否可控	“做得贵不贵、慢不慢？”	Cost / Success、P95 Latency、Token / Run
L4 安全合规	是否越权、泄露、误操作	“有没有做不该做的事？”	Permission Deny Rate、Policy Violation、Sensitive Tool Use
L5 项目收益	上线后是否有真实价值	“值不值得继续投？”	人效提升、节省工时、转化率、缺陷率、DORA/SPACE 指标

这五层不能互相替代。

一个 Agent 最终答对了，但调用了危险工具、泄露了上下文、成本是人工的 3 倍，依然不是好 Agent。

3. 从成熟 Agent 项目看评估信号应该采集什么

3.1 Claude Code：评估入口是 Session、Trace、Hook、OTel

Claude Code 的 Agent SDK 提供了文件读取、命令执行、代码编辑等能力，官方文档说明 SDK 暴露的是与 Claude Code 相同的 tools、agent loop 和 context management。(Claude Code)

Claude Code 的观测能力也非常典型：官方文档说明它可以通过 OpenTelemetry 导出 usage、cost、tool activity；Agent SDK 侧则说明 Claude Code CLI 会围绕 model request 和 tool execution 记录 spans，并发出 token/cost metrics 和 prompt/tool result structured logs。(Claude Code) (Claude Code)

这给我们的启发是：

Agent 评估不能等任务结束后再猜。
必须在运行过程中采集 trace、tool span、permission span、cost metric、error event。

Claude Code hooks 也能在工具调用前后拦截行为，例如官方 hooks 文档说明，PreToolUse 可以返回 allow、deny、ask、defer 等权限决策；多个 hook 或权限规则同时命中时，deny 优先级最高。(Claude Code)

这意味着，评估系统可以把 hook 当作“可编程评审点”：

这类 hook 不只是安全能力，也可以作为评估采样点。

3.2 OpenCode：评估重点是 Agent 模式、权限和 GitHub 工作流

OpenCode 官方文档把 Agent 分为 primary agents 和 subagents，并说明 primary agents 通过 permissions 控制工具访问；内置的 Build 是开发用的全权限 Agent，Plan 是受限分析 Agent，默认对文件编辑和 bash 命令设置为 ask。(OpenCode)

OpenCode GitHub 集成也很适合作为项目效果评估入口：官方文档说明，用户可以在 issue 或 PR 评论中提到 /opencode 或 /oc，OpenCode 会在 GitHub Actions runner 中执行任务；它可以 triage issue、修复/实现功能，并在新分支提交 PR。(OpenCode)

这说明针对 Coding Agent，可以自然采集这些指标：

issue 是否被正确理解
PR 是否生成
CI 是否通过
Review 是否通过
是否引入回归
从 issue 到 PR 的 lead time 是否缩短
人工修改比例是多少
Agent 生成代码被接受的比例是多少

OpenCode 源码中的 ACP permission flow 也体现了一个成熟 Agent 系统常见模式：当 permission event 到来时，系统会按 session 管理 permission queue，向外部连接请求权限决策，然后根据选择结果回复 once、always 或 reject。源码中可以看到 permission event、session 查找、requestPermission、reject fallback、edit diff 预览、permission reply 等关键路径。(GitHub)

可以把这个流程抽象成如下评估代码：

这里的关键点不是“有没有权限系统”，而是：

权限请求本身也要进入评估数据集。
未来你要能回答：哪些工具最常被拒绝？哪些 Agent 最容易触发高风险动作？哪些任务因为权限设计过严而失败？

3.3 OpenClaw：评估重点是真实世界工具、信任边界和安全审计

OpenClaw 更像个人/企业助手型 Agent。它的 GitHub README 说明 OpenClaw 是运行在用户自己设备上的个人 AI assistant，可以通过已有渠道交互，并且 Gateway 只是控制平面。(GitHub)

OpenClaw 插件文档说明，插件可以扩展 channels、model providers、agent harnesses、tools、skills、speech、web fetch、web search 等运行时能力。(OpenClaw)

这类 Agent 的评估难点不是“回答质量”，而是：

它真的会操作邮件、日历、浏览器、文件系统、命令行。
所以项目评估必须包含安全边界、误操作率、人工确认率、撤销率、真实业务闭环率。

OpenClaw 安全文档明确指出，推荐模型是一个 gateway 对应一个用户/信任边界；如果多个不可信用户共享一个 tool-enabled agent，就应视为他们共享同一套 delegated tool authority。(OpenClaw)

它还提供 openclaw security audit，用于检查 Gateway auth 暴露、浏览器控制暴露、过高 allowlist、文件权限、宽松 exec approvals、open-channel tool exposure 等问题。(OpenClaw)

这说明生产 Agent 的评估必须单独有一类指标：

Security Posture Score：部署形态是否安全
Tool Authority Scope：Agent 实际拥有多少权限
Approval Coverage：高风险动作是否都经过确认
Rollback Ability：执行错误后能否恢复
Sensitive Data Exposure：日志、trace、tool output 是否泄露敏感信息

OpenClaw release notes 中还提到对诊断能力的增强，包括导出 bounded skill usage metrics/spans，以及为 core、plugin、MCP、channel tool execution 添加 source/owner labels，且不暴露 raw paths 或 session identifiers。(GitHub)

这正是 Agent 观测的成熟方向：

既要知道工具是谁调用的、来自哪个 skill/plugin/MCP/channel；
又不能把原始路径、session id、secret 泄露到观测系统里。

4. Agent 执行效果评估：从“最终结果”到“过程轨迹”

4.1 最终结果指标：Goal Accuracy / Task Success

Ragas 的 Agent Goal Accuracy 指标用于评估 LLM 是否识别并完成用户目标，是一个二值指标，1 表示完成，0 表示未完成。(Ragas)

对 Agent 来说，最终结果评估可以分成三种：

类型	例子	判断方式
可自动验证	修复 bug、SQL 查询、单元测试通过	测试、断言、CI
半自动验证	写邮件、生成方案、整理文档	LLM-as-Judge + 人审抽样
必须人工验证	谈判、销售、客服、复杂项目管理	专家标注 + 业务结果

Coding Agent 最容易自动评估。SWE-bench 就是典型例子，它用真实 GitHub issue 评估模型是否能生成解决问题的 patch；官方 leaderboard 使用 % Resolved 表示实例解决比例，并提供 Verified、Lite、Multimodal 等不同子集。(GitHub) (SWE-bench)

一个简单的 task success evaluator 可以这样写：

但只看 task_success 不够。因为 Agent 可能“运气好”完成了任务，但过程非常危险。

4.2 工具调用指标：Tool Call Accuracy / Tool Call F1

Ragas 的 Tool Call Accuracy 用来衡量 Agent 是否调用了正确工具、顺序是否正确、参数是否准确，尤其适合多步骤 workflow。(Ragas)

Ragas 的 Tool Call F1 则用 precision / recall / F1 衡量工具调用与期望工具调用集合的接近程度，比严格 exact match 更适合迭代阶段；它能惩罚漏调工具，也能惩罚多调无关工具。(Ragas)

可以把一次 Agent 的工具轨迹表示成：

工具调用评估核心逻辑：

在真实项目中，还要进一步拆：

工具选择正确率：是否选了正确工具
参数正确率：参数名、参数值、单位、ID 是否正确
调用顺序正确率：是否先读后写、先查后改
无效调用率：工具返回空、超时、权限拒绝、schema error
危险调用率：删除、支付、发邮件、执行命令等高风险动作占比
重复调用率：同一工具同一参数被重复调用多少次

4.3 轨迹指标：Agent 有没有走对路线？

OpenAI Agent eval 文档建议在调试阶段从 traces 开始，因为 trace grading 可以回答：Agent 是否选对工具、是否该 handoff、是否违反指令或安全策略、prompt 或 routing 变化是否改善端到端行为。(OpenAI开发者)

一个 Agent trace 可以抽象成 DAG：

轨迹评估可以关注：

指标	含义	常见失败
Step Count	完成任务用了多少步	小任务走了 20 步
Loop Count	是否重复调用同一工具	陷入搜索/修复循环
Recovery Rate	工具失败后是否能恢复	超时后直接编造答案
Handoff Accuracy	是否该转交子 Agent / 人类	不该转交却转交，或该转交不转交
Reflection Quality	是否根据观察结果修正计划	工具结果已经失败仍继续原计划
Context Usage	是否引用了正确上下文	读取了旧文件、旧检索结果

一个简化轨迹评分器：

5. RAG + Agent 的评估：不要把检索和行动混在一起

很多 Agent 内部都有 RAG。

如果只看最终答案，会搞不清失败原因：

是检索没召回？
是 rerank 排错？
是上下文太旧？
是 Agent 没用检索结果？
是工具调用失败？
是最终生成幻觉？

LangSmith 文档明确提到，RAG 评估应拆分 retrieval quality 和 generation quality，例如 context precision 与 faithfulness，以便分别定位检索和生成问题。(LangChain)

推荐拆成四段：

对应指标：

阶段	指标	解释
Retriever	Recall@k、MRR、NDCG	该找的文档有没有找到
Reranker	Context Precision、Top1 Accuracy	相关文档是否排在前面
Agent Decision	Evidence Usage Rate	Agent 是否真的使用检索证据
Final Answer	Faithfulness、Citation Accuracy	回答是否忠于上下文
Action	Grounded Action Rate	行动是否基于正确证据

在 Agent 场景里，还要增加一个指标：

Stale Context Usage Rate：Agent 使用过期上下文做决策的比例。

比如：

6. 观测系统设计：Trace 是 Agent 评估的事实来源

OpenTelemetry 的 GenAI semantic conventions 已经定义了 Generative AI 系统的 events、exceptions、metrics、model spans、agent spans 等信号，并包含 Anthropic、OpenAI、MCP 等技术相关约定。(OpenTelemetry)

这说明 Agent 评估最好不要自造一套孤立日志格式，而应该围绕 OpenTelemetry 或兼容的 span 模型设计。

一个推荐 trace schema：

Python 侧可以这样埋点：

LangSmith 的 Observability 页面也强调，Agent tracing 可以逐步看到 Agent 做了什么，用于定位 latency、cost、response quality 问题；生产监控还包括 cost tracking、online LLM-as-judge、code evals、tool and agent trajectory monitoring、alerts 等能力。(LangChain)

所以生产级 Agent 的评估平台至少要包含：

Trace Store
Eval Dataset
Grader / Evaluator
Online Monitor
Human Annotation Queue
Regression Dashboard
Cost Dashboard
Security Audit Dashboard

7. 离线评估、在线评估、CI 评估怎么分工？

LangSmith 文档把 offline evaluation 和 online evaluation 区分得很清楚：offline eval 用 curated datasets 在开发阶段捕捉回归，online eval 对真实生产流量实时打分以发现质量漂移。(LangChain)

推荐三类评估同时存在。

7.1 离线评估：用于模型、Prompt、工具策略对比

适合回答：

换模型后成功率是否提升？
改 prompt 后工具调用是否更稳？
新增 rerank 后幻觉是否下降？
新版 planner 是否减少无效步骤？

数据集格式：

7.2 CI 评估：用于防止回归

LangSmith 文档说明 eval 可以集成 pytest、Vitest 和 GitHub workflows，并在分数下降时让 pipeline fail。(LangChain)

CI 中可以设置门禁：

7.3 在线评估：用于发现真实流量问题

线上要看：

最近 1 小时工具错误率是否上升
某个模型成本是否异常
某个 skill 是否触发大量拒绝
某类用户任务是否失败率变高
是否出现 prompt injection / data exfiltration 风险
人工接管率是否上升

线上 eval 不一定每条都跑 LLM-as-Judge。可以分层：

流量类型	评估方式
全量流量	规则、成本、延迟、错误率
抽样流量	LLM-as-Judge
高风险流量	人审 + 安全审计
失败流量	自动聚类 + 复盘入库

8. 安全与权限评估：Agent 项目必须单独打分

Agent 和普通 Chatbot 最大区别是它会行动。

所以安全评估必须从第一天就进入指标体系。

Claude Code hooks 支持在工具调用前后拦截、修改输入、阻断操作，官方示例中甚至可以阻止修改 .env 文件。(Claude Code)

OpenClaw 安全文档也强调最小权限、定期 audit，以及明确谁能和 bot 对话、bot 可以在哪里行动、bot 能触碰什么。(OpenClaw)

推荐安全指标：

指标	含义
High Risk Tool Rate	高风险工具调用占比
Permission Ask Rate	需要用户确认的比例
Permission Deny Rate	被拒绝比例
Unauthorized Attempt Rate	试图越权访问的比例
Secret Exposure Count	trace/log/tool output 中出现 secret 的次数
Prompt Injection Hit Rate	检测到注入攻击的比例
Sandbox Escape Attempt	试图访问沙箱外资源的次数
Human Override Rate	人类推翻 Agent 决策的比例
Rollback Success Rate	错误行动后恢复成功比例

安全 evaluator：

9. 项目效果评估：Agent 到底有没有产生业务价值？

执行效果好，不代表项目成功。

项目成功要看业务指标、工程指标、用户指标和成本风险。

9.1 业务效果指标

场景	核心指标
客服 Agent	自动解决率、转人工率、一次解决率、CSAT、投诉率
销售 Agent	线索转化率、跟进时效、有效会话率、预约率
办公 Agent	节省工时、任务完成率、人工修改率
Coding Agent	PR 通过率、CI 通过率、review 修改量、缺陷率
RAG Agent	命中率、引用正确率、幻觉率、用户追问率

一个常用指标是：

更真实的 ROI：

9.2 工程项目可以接 DORA 和 SPACE

如果 Agent 用在研发效率场景，可以接入 DORA 和 SPACE。

DORA 官方指南定义了 change lead time、deployment frequency、failed deployment recovery time 等软件交付指标。(dora.dev)

SPACE 框架则从 Satisfaction and well-being、Performance、Activity、Communication and collaboration、Efficiency and flow 五个维度衡量开发者生产力，避免只用单一产出指标误判团队状态。(queue.acm.org)

所以 Coding Agent 项目不要只看：

Agent 写了多少行代码
Agent 生成了多少 PR
Agent 省了多少 token

而应该看：

PR lead time 是否缩短
Review 轮次是否减少
CI failure 是否增加
Change failure rate 是否变差
开发者满意度是否提升
中断次数是否降低
On-call 和返工是否减少

10. 一个完整的 Agent 评估闭环

推荐闭环如下：

对应落地步骤：

先埋点：记录 run、span、tool call、permission、cost、latency、error。

再抽样：把失败、高成本、高风险、用户差评样本抽出来。

做人审：建立 task success、tool correctness、安全性标签。

沉淀 dataset：构建回归测试集。

跑离线 eval：比较模型、prompt、工具策略。

接 CI gate：防止新版本让关键指标下降。

上线监控：看真实流量漂移、成本异常、安全异常。

反哺优化：更新 prompt、router、tool schema、权限策略、RAG 索引。

11. 生产级 Agent Eval 数据模型

推荐最小数据表：

关键点：

agent_runs 看整体效果。
agent_spans 看执行轨迹。
tool_calls 看工具质量和权限。
eval_scores 存自动评估和人工评估结果。

12. 常见误区

误区一：只看最终回答

最终回答可能正确，但过程可能越权、泄露、成本爆炸。Agent 必须看 trace。

误区二：只用 LLM-as-Judge

LLM-as-Judge 适合语义评价，但不适合替代所有判断。代码任务应该跑测试，SQL 任务应该执行查询，工具任务应该看真实 side effect。

误区三：只看平均值

Agent 的风险通常藏在 P95 / P99：

平均成本不高，但某些任务循环 100 步。
平均成功率不错，但高价值客户任务失败。
平均延迟可接受，但支付/邮件类任务风险高。

误区四：公开 benchmark 分数等于项目效果

SWE-bench 很适合评估真实 GitHub issue 修复能力，但它主要衡量 coding patch 场景。企业内部 Agent 还要补自己的私有 benchmark、权限 benchmark、业务闭环 benchmark。SWE-bench 官方也提供 resolved、cost、step 等多视角对比，这提示我们不要只看单一分数。(SWE-bench)

误区五：没有把失败样本变成资产

失败 trace 是最有价值的数据。

每次失败都应该进入：

error cluster
regression dataset
prompt/tool/schema 改进 backlog
安全规则库
人审样本池

13. 最后给一个可直接落地的指标清单

Agent 执行效果

类别	指标
目标完成	Task Success、Goal Accuracy、Pass@1
工具调用	Tool Call Accuracy、Tool Call F1、参数正确率、工具错误率
轨迹质量	Step Count、Loop Count、Recovery Rate、Handoff Accuracy
RAG 质量	Recall@k、Context Precision、Faithfulness、Citation Accuracy
成本性能	Cost / Run、Cost / Success、P50/P95/P99 Latency、Token / Run
安全	Policy Violation、Permission Deny Rate、Secret Exposure、High Risk Tool Rate
稳定性	Timeout Rate、Retry Rate、Crash Rate、Fallback Rate

Agent 项目效果

类别	指标
业务价值	自动完成率、节省工时、转化率、满意度、投诉率
工程效率	PR lead time、review 轮次、CI 通过率、缺陷率、DORA 指标
用户体验	采纳率、复用率、追问率、人工接管率、NPS/CSAT
成本收益	Cost per Success、ROI、Review Cost、Incident Cost
风险治理	安全审计通过率、越权尝试率、敏感数据暴露次数

总结

评估 Agent 的核心不是给最终回答打一个分，而是建立一套“可观测、可回放、可标注、可回归、可上线监控”的工程系统。

最推荐的落地路径是：

Trace First：先采集完整执行轨迹。
Trajectory Eval：评估工具调用、权限、上下文、恢复能力。
Outcome Eval：用测试、业务状态、人审判断任务是否完成。
Online Monitor：监控成本、延迟、安全、漂移。
Project ROI：用业务指标和工程指标证明项目价值。

成熟 Agent 项目的共同方向已经很明显：Claude Code 强调 session、hooks、OTel；OpenCode 强调 agent 模式、权限和 GitHub 工作流；OpenClaw 强调真实工具、Gateway、插件和安全边界；OpenAI、Ragas、LangSmith 则把 trace、grader、dataset、online/offline eval 变成系统化能力。把这些思想组合起来，才是生产级 Agent 评估体系。