Agent-EvalKit 是 AWS 在 2026-06-11 发布的开源 AI Agent 评估工具包，Apache 2.0 许可（来源：AWS Machine Learning Blog）。适合已经有工具调用、检索、外部 API 或多步规划的 agent——在 Claude Code、Kiro CLI 或 Kilo Code 里敲 /evalkit.* 命令，assistant 就会读你的代码、生成测试用例、插桩 trace、跑评估，然后告诉你具体该改哪段代码。
别把它当成"问几个问题看回答"的替代品。它解决的问题是：final answer 看起来没错，但工具调错了、空结果被编成了事实、引用对不上原文。
什么时候该用 Agent-EvalKit
当你的 agent 满足以下任意两项，就值得在开发阶段引入 Agent-EvalKit，而不是只做人工抽查：
| 条件 | 评估重点 |
|---|---|
| 会调用搜索、数据库、CRM、工单或内部 API | 工具是否选对、参数是否正确、失败时是否停止 |
| 会把工具结果写进最终回答 | 回答是否忠实于工具返回的数据 |
| 会处理多轮任务 | 中间状态、上下文继承和工具顺序是否稳定 |
| 准备换模型、改 system prompt 或改工具描述 | 同一批 trace 在变更前后是否可比较 |
| 团队已经发现“答得像真的，但来源为空”的问题 | 空工具结果是否被明确披露，而不是被模型补全 |
如果 agent 还只是纯聊天、没有外部工具、没有业务动作，先用人工 checklist 和固定 prompt 集就够了。Agent-EvalKit 的价值主要出现在你必须看见执行路径的时候。
和 AgentCore 评测集有什么区别
本站已有 AI Agent 评测集怎么建，讲的是把生产失败沉淀成版本化数据集和发布门禁。Agent-EvalKit 更靠前：在本地开发目录里分析代码、生成 eval/、跑 trace、出报告。
| 问题 | 更适合用 Agent-EvalKit | 更适合用 AgentCore 数据集/生产评估 |
|---|---|---|
| 我刚写完一个 agent，想知道哪里会幻觉 | 是 | 否 |
| 我要看每次工具调用和中间状态 | 是 | 可作为后续生产监控 |
| 我要把线上失败固化成发布门禁 | 可以辅助 | 是 |
| 我要长期监控真实流量质量 | 否 | 是 |
| 我要让 coding assistant 直接指出该改哪段代码 | 是 | 否 |
实际用的时候，可以先拿 Agent-EvalKit 找出高风险行为，再把稳定复现的失败写进版本化评测集。
准备条件
| 项目 | 要求 |
|---|---|
| AWS 账号 | 在 Amazon Bedrock 控制台启用评估要用的 foundation model |
| 本地环境 | Python 3.11+、Git、uv |
| Coding assistant | Claude Code、Kiro CLI 或 Kilo Code 已安装并可在项目里运行 |
| Agent 代码 | 包含源码、工具定义、prompt 和运行配置 |
| 支持框架 | AWS 文章提到 Strands、LangGraph、CrewAI 可自动插桩；最新支持矩阵以 Agent-EvalKit 仓库为准 |
macOS/Linux 下安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
安装 Agent-EvalKit：
uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git
最小上手流程
先新建一个评估项目，把你的 agent 代码复制进去。下面的路径是示意路径，不是本站运行结果：
evalkit init my-agent-evaluation
cd my-agent-evaluation
cp -r /path/to/your/agent .
如果你使用 Claude Code，就在评估目录启动：
claude
第一次跑可以用 quick 命令，让 assistant 按步骤引导：
/evalkit.quick Evaluate my agent at ./my_agent for faithfulness, tool parameter accuracy, and response quality
如果你想控制每个阶段，就按六个命令分开跑：
/evalkit.plan Evaluate my agent at ./my_agent for faithfulness, tool parameter accuracy, and response quality
/evalkit.data
/evalkit.trace
/evalkit.run_agent
/evalkit.eval
/evalkit.report
这六步会在 eval/ 目录里生成评估计划、测试数据、trace、评分结果和报告。后续你可以只重跑某一阶段，例如改了指标就重跑 /evalkit.eval，改了工具代码就重跑 /evalkit.run_agent 和 /evalkit.report。
六个阶段各检查什么
| 阶段 | 命令 | 产物 | 你要检查什么 |
|---|---|---|---|
| Plan | /evalkit.plan |
评估计划和指标 | 指标是否覆盖你的真实风险，而不是只看回答好不好看 |
| Data | /evalkit.data |
测试用例 | 是否包含空结果、错误参数、权限不足、实时数据过期等场景 |
| Trace | /evalkit.trace |
OpenTelemetry-compatible tracing 插桩 | 工具调用、模型回复和中间状态是否能被捕获 |
| Run agent | /evalkit.run_agent |
每个用例的结构化 trace | agent 是否按测试用例完整执行 |
| Eval | /evalkit.eval |
可执行评估代码和评分 | 规则评估和 LLM-as-judge 是否各司其职 |
| Report | /evalkit.report |
修复建议 | 建议是否能指向具体文件、具体行为和预期影响 |
不要跳过 Data 阶段的人工复核。测试用例可以由 assistant 生成，但真实用户行为、业务红线和历史事故需要你补进去。
三个核心指标怎么选
AWS 的示例旅行研究 agent 用了三个指标：Faithfulness（忠实性）、Tool Parameter Accuracy（工具参数精度）和 Response Quality（回答质量）。适合大多数带工具的 agent：
| 指标 | 主要发现什么 | 更适合怎么评 |
|---|---|---|
| Faithfulness | 最终回答是否忠实于工具返回数据，是否把空结果编成事实 | trace + LLM judge + 引用检查 |
| Tool Parameter Accuracy | 工具是否选对，参数是否精确 | 规则检查优先，必要时人工复核 |
| Response Quality | 回答是否清晰、完整、可执行 | LLM judge 或人工抽样 |
如果 agent 涉及权限、支付、删除、发送消息等动作，要再加硬规则：
- 未通过权限检查不得调用业务 API
- 工具返回空结果时必须说明"没有拿到数据"
- 高风险动作必须等待人工确认
读报告时先看什么
AWS 的示例里，旅行研究 agent 的 Response Quality 是 83.9%，Tool Parameter Accuracy 是 64.5%，Faithfulness 只有 32.3%。不是它不会写旅行建议，而是 web search 工具返回空或不完整结果时，它会自己编汇率、气温和景点细节，还写得跟真从工具拿来的数据一样。
这类报告要按下面顺序处理：
- 先修高风险幻觉：空工具结果、错误用户、权限失败、过期实时数据。
- 再修工具参数：日期、地区、用户 ID、货币、产品 SKU、过滤条件。
- 最后修表达质量：格式、摘要顺序、措辞。
不要因为 Response Quality 分数高就放行。对工具型 agent 来说，漂亮回答可能掩盖了错误路径。
CI/CD 里怎么接
第一版别想着全自动。先用本地评估跑出稳定基线，再把最关键的那些场景接进 CI：
| 步骤 | 通过标准 |
|---|---|
| 固定 20-50 个高风险用例 | 覆盖工具空结果、权限失败、参数错误、实时数据过期 |
| 保存 trace 和报告 | 每次模型或 prompt 改动后可对比 |
| 设置硬门禁 | high-risk faithfulness 或权限场景任一失败就阻断 |
| 设置软门禁 | response quality 下降超过阈值时要求人工批准 |
| 只比较同一批测试 | 不要一边换题一边比较分数 |
等测试集稳定了，再接上生产 trace 到 Amazon Bedrock AgentCore Observability 和 AgentCore Evaluation。AWS 官方文章也把生产监控放在后续，不是拿来替代开发期评估的。
常见错误
只测最终回答。 Agent 可能答对结论，但跳过了权限检查或用了错误工具。
把 LLM judge 当唯一裁判。 语义质量可以交给 judge；权限、工具顺序、参数、是否调用 forbidden action，优先用规则检查。
不审生成的测试用例。 /evalkit.data 能生成覆盖面，但你的真实业务失败要人工加入。
一次塞太多指标。 先跑 faithfulness、tool parameter accuracy、response quality 三类；稳定后再加成本、延迟、风格和安全指标。
只在发布前跑。 Agent 评估应该在每次重要 prompt、工具描述、模型版本或检索策略变更后跑。否则报告只是在解释已经发生的问题。
FAQ
Agent-EvalKit 一定要用 Amazon Bedrock 吗？
AWS 官方文章写明，运行评估需要 AWS 账号，并在 Amazon Bedrock 控制台启用用于 LLM-as-judge 的 foundation model。也就是说，如果你要按官方流程跑完整评估，需要 Bedrock 模型访问。
它支持哪些 coding assistant？
Agent-EvalKit 集成了 Claude Code、Kiro CLI 和 Kilo Code。官方文章示例用的是 Claude Code。
它会自动修代码吗？
最后一步 /evalkit.report 会给出带优先级的修复建议，标出代码位置和预期影响。改不改还是由你决定——报告不是自动修 Bug 的工具。
已经有评测集了，还需要 Agent-EvalKit 吗？
如果评测集只存了输入和期望输出，Agent-EvalKit 仍然有用——它补了 trace、工具参数、faithfulness 和代码级建议。如果你的评测平台已经能记完整工具轨迹并给出可执行的修复建议，那 Agent-EvalKit 的增量就小了。
第一轮该怎么写提示词？
拿具体风险写，别只写"评估质量"。比如：
/evalkit.plan Evaluate ./my_agent for hallucinations when tools return empty results, wrong tool parameters for date and region filters, and response quality for business users.
这样评估就会聚焦到空结果、日期/地区参数和业务可用性上，后面的 Data、Eval 和 Report 也跟着这个方向走。