AI Agent 越来越多，但"它到底好不好用"这件事，大多数团队还在靠手动试几个场景、凭感觉判断。Agent-EvalKit 这个 Apache 2.0 开源工具包，试图把 Agent 评估从"拍脑袋"变成"有流程、有数据、可复现"的工程实践。它已经对接了 Claude Code、Kiro CLI、Kilo Code 等主流 AI 编码助手，并提供了从定义场景到输出报告的六阶段评估管线。本文以一个基于 Strands Agents SDK 和 Amazon Bedrock 的旅行研究 Agent 为线索，拆解每个阶段在做什么，以及你如何把它接入自己的项目。
评估为什么需要"管线化"
传统 LLM 评估聚焦在问答准确性，但 Agent 的行为链条更长：它要理解任务、选择工具、调用 API、处理异常、组合多步结果。单看最终输出是否正确，会漏掉大量中间环节的问题——工具选错了但最终碰巧对了、规划合理但执行超时、边界条件下直接崩溃。Agent-EvalKit 把评估拆成六个阶段，正是为了让每个环节都有独立的观测点，而不是只看终点。
六阶段评估拆解
Agent-EvalKit 的评估管线大致分为以下六个阶段：
1. 场景定义（Scenario Definition）
明确你要测什么。不是泛泛地"测 Agent 能力"，而是写出具体的任务描述、预期行为、约束条件。比如旅行研究 Agent 的场景可以是："用户要求规划一个 5 天东京行程，预算 8000 元，必须包含至少两个博物馆。"
2. 测试用例生成（Test Case Generation）
从场景定义出发，自动或半自动地生成一批输入-期望对。Agent-EvalKit 可以借助 LLM 辅助生成多样化用例，覆盖正常路径和边界情况（极端预算、模糊需求、不存在的目的地等）。
3. Agent 执行（Agent Execution）
把测试用例逐条喂给目标 Agent，记录完整交互轨迹——不只是最终回答，还包括每一步的工具调用、中间推理、API 请求与响应。这一步的关键是"全量录制"，否则后续分析就缺素材。
4. 输出采集（Output Capture）
结构化地存储执行轨迹和最终输出。Agent-EvalKit 会把轨迹整理成可查询的格式，方便后续按步骤、按工具、按时间维度检索。
5. 指标计算（Metric Computation）
对采集的数据计算量化指标。常见的维度包括：
- 任务完成率：最终输出是否满足场景定义的约束
- 工具使用准确率：调用的工具和参数是否合理
- 步骤效率：完成同一任务用了多少步，有没有冗余调用
- 异常恢复率：遇到错误后 Agent 是否能自纠正
6. 结果聚合与报告（Aggregation & Reporting）
把各场景、各维度的指标汇总，生成可读的报告。报告不只是数字，还包含典型失败案例的轨迹回放，让开发者能直接定位问题根因。
实操：用 Strands Agents SDK 搭一个被测 Agent
下面用一个简化版旅行研究 Agent 来演示如何让 Agent-EvalKit 评估它。先写 Agent 本身：
# travel_agent.py — 基于 Strands Agents SDK 的旅行研究 Agent
from strands_agents import Agent, tool
import json
@tool(name="search_flights", description="搜索航班信息")
def search_flights(origin: str, destination: str, date: str, budget: float) -> str:
"""模拟航班搜索，实际项目中替换为真实 API"""
# 这里用模拟数据演示，生产环境接入 Skyscanner / Amadeus 等
mock_results = [
{"airline": "ANA", "price": 3200, "duration": "3h10m"},
{"airline": "JAL", "price": 4100, "duration": "3h05m"},
]
affordable = [r for r in mock_results if r["price"] <= budget]
return json.dumps(affordable, ensure_ascii=False)
@tool(name="search_attractions", description="搜索景点和博物馆信息")
def search_attractions(city: str, category: str = "all") -> str:
"""模拟景点搜索"""
mock_data = {
"tokyo": [
{"name": "东京国立博物馆", "category": "museum", "cost": 100},
{"name": "teamLab Borderless", "category": "museum", "cost": 320},
{"name": "浅草寺", "category": "temple", "cost": 0},
]
}
results = mock_data.get(city.lower(), [])
if category != "all":
results = [r for r in results if r["category"] == category]
return json.dumps(results, ensure_ascii=False)
# 创建 Agent，挂载工具，指定 Bedrock 上的模型
travel_agent = Agent(
name="travel-researcher",
model_id="us.anthropic.claude-3-5-sonnet-20241022-v2:0", # Amazon Bedrock 模型 ID
tools=[search_flights, search_attractions],
description="帮助用户规划旅行行程，搜索航班和景点信息",
)
# 简单调用测试
if __name__ == "__main__":
result = travel_agent.run(
"帮我规划一个5天东京行程，预算8000元，至少包含两个博物馆"
)
print(result)
运行前确保你的环境已配置好 AWS 凭证和 Bedrock 访问权限：
# 安装 Strands Agents SDK
pip install strands-agents
# 配置 AWS 凭证（Bedrock 调用需要）
aws configure set region us-east-1
# 或通过环境变量
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
实操：接入 Agent-EvalKit 评估管线
Agent 写好后，用 Agent-EvalKit 对它跑一轮系统化评估：
# evalkit_config.yaml — Agent-EvalKit 评估配置
evalkit:
agent:
type: strands
entrypoint: travel_agent.py:travel_agent
runtime: python
scenarios:
- id: tokyo-budget-trip
task: "规划5天东京行程，预算8000元，至少两个博物馆"
constraints:
- budget_max: 8000
- museum_min: 2
- days: 5
expected_tools: ["search_flights", "search_attractions"]
- id: vague-request
task: "我想去日本玩"
constraints:
- should_ask_clarification: true # 模糊需求应主动追问
expected_tools: [] # 不应直接调用工具
- id: impossible-budget
task: "规划东京7天行程，预算500元"
constraints:
- should_flag_impossibility: true # 不可能完成的预算应提示用户
metrics:
- task_completion
- tool_accuracy
- step_efficiency
- error_recovery
output:
format: markdown
path: ./eval_reports/
运行评估：
# 安装 Agent-EvalKit
pip install agent-evalkit
# 执行六阶段评估管线
agent-evalkit run --config evalkit_config.yaml
# 查看生成的报告
cat ./eval_reports/latest_summary.md
报告会包含每个场景的通过率、工具调用轨迹、步骤数量，以及失败案例的详细回放。比如 vague-request 场景如果 Agent 直接调了 search_flights 而没有先追问细节，工具使用准确率就会扣分；impossible-budget 场景如果 Agent 照常输出行程而不提示预算不足，任务完成率也会标记为不通过。
与 AI 编码助手的集成
Agent-EvalKit 不只是一个独立运行的工具——它还能嵌入到开发流程中。它已经对接了 Claude Code、Kiro CLI、Kilo Code，这意味着你可以在编码助手的工作流里直接触发评估：
# 在 Claude Code 中通过 Agent-EvalKit 插件触发评估
claude-code eval --kit agent-evalkit --config evalkit_config.yaml
# 或在 Kiro CLI 中
kiro eval run --evalkit-config evalkit_config.yaml
这种集成让评估不再是"写完代码再单独跑一轮测试"的事后动作，而是可以变成编码过程中的即时反馈——改了 Agent 的工具选择逻辑，立刻看评估指标有没有变化。
什么时候该用、什么时候不必用
Agent-EvalKit 适合以下场景：
- Agent 行为链条超过 3 步：单步问答用传统 benchmark 就够了，多步 Agent 才需要管线化评估
- 工具调用是核心能力：如果你的 Agent 依赖外部 API、数据库查询等工具，工具准确率指标比最终输出正确性更重要
- 需要回归测试：每次改 Agent 逻辑后都要确认没有退化，六阶段管线可以复用场景定义，自动跑回归
暂时不需要的情况：
- Agent 还在早期原型：场景定义本身还不稳定，先手动探索再引入系统化评估
- 单模型调用的简单 wrapper：没有工具选择、没有多步规划，评估复杂度不高
一个实用的落地节奏：先手动跑 3-5 个典型场景确认 Agent 基本可用，然后把这些场景转成 Agent-EvalKit 的 YAML 配置，作为回归基线。之后每次迭代都跑一遍，逐步补充边界场景。评估不是一次性动作，而是持续伴随 Agent 演进的工程实践。