Strands Evals v0.1.0 全解：LLM-as-a-Judge、轨迹评估与模拟器驱动的生产级 Agent 评测框架

人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载Strands EvaluationPython 包strands-agents-evals是 harness-sdk 仓库中用于度量 AI Agent 质量的评测框架从简单的输出校验到复杂的多智能体交互分析、轨迹评估与自动化实验生成它提供了一套覆盖输出、轨迹、工具使用与交互的完整评估工具链。本文以仓库中的发布记录 site/src/content/changelog/evals/v0.1.0.md 为核心骨架结合 evals-sdk 官方文档 与 示例代码 展开帮助你掌握如何用 LLM 作裁判进行结构化评分、如何基于 OpenTelemetry 轨迹分析 Agent 行为、如何自动生成测试套件、如何通过模拟器做多轮对话评估以及如何用 CLI 一键跑通整个评估流程。Strands Evals 是什么v0.1.0 的核心定位v0.1.0 是 Strands Evals 的初始发布版本其发布说明即关联文档给出了这个框架的能力全景多种评估类型输出评估Output evaluation、轨迹分析Trajectory analysis、工具使用评估Tool usage assessment、交互评估Interaction evaluationLLM-as-a-Judge内置基于语言模型的评估器支持结构化评分structured scoring基于轨迹的评估通过 OpenTelemetry 执行轨迹分析 Agent 行为自动化实验生成从上下文描述自动生成全面的测试套件自定义评估器可扩展的框架用于承载领域特定的评估逻辑实验管理通过 JSON 序列化保存、加载和版本化评估实验内置评分工具提供精确匹配、按顺序匹配、任意顺序匹配的轨迹匹配辅助函数模拟器通过生成随 Agent 响应自适应调整的真实交互模式实现对话 Agent 的多轮评估。从仓库文档可以看出该 SDK 在随后的版本中持续演进围绕这八个能力点沉淀出了完整的 Evals SDK 用户指南涵盖评估器Evaluators、检测器Detectors、红队Red teaming、模拟器Simulators与 CLI 五大部分。本文按 v0.1.0 的能力清单逐一展开所有代码均可基于仓库当前文档直接运行。评估的基本构成实验、用例、任务、评估器在动手写代码之前先理解一次评估的形状。根据 how-evaluation-works.mdx 的说明Strands Evals 由四个固定搭配的构件组成实验Experiment你要运行的最小单元持有用例列表和要应用到每个用例上的评估器集合用例Case一个输入与期望结果的配对携带发送给 Agent 的 prompt、可选的expected_output用于对照以及可供后续过滤与分组的metadata任务Task把用例变成结果。它运行你的 Agent或任意函数处理用例输入返回输出以及可选的轨迹trajectory——即 Agent 在运行过程中产生的模型响应与工具调用的有序记录。eval_task装饰器负责接线让任务函数只需返回一个Agent即可评估器Evaluator对单个结果评分输入是输出或整条轨迹返回分数、通过/失败判定以及评分理由。有的评估器用模型当裁判有的则是纯代码判断检测器Detector与评估方向相反。评估器告诉你这个用例得了 0.2 分检测器读取失败用例的轨迹定位出错的 span 并提出根因——评分回答是否失败诊断回答为什么失败。对单个用例而言流程从左到右任务产出输出与轨迹 → 评估器评分 → 检测器诊断失败实验对所有用例重复这一过程并聚合成报告供打印、保存与后续对比。评估的三个层级输出、轨迹、会话评估器之间的关键差异在于它们看多少运行过程。每个评估器都工作在三个层级之一选对层级与选对检查项同样重要下表出自 how-evaluation-works.mdx层级范围回答的问题OUTPUT_LEVEL单条响应这条回答本身好不好TRACE_LEVEL单个回合这一回合是否正确、切题、安全SESSION_LEVEL完整对话Agent 是否端到端达成了用户目标例如OutputEvaluator这类输出级检查只需要最终文本而GoalSuccessRateEvaluator这类会话级检查需要完整轨迹因此感知轨迹的任务task会收集 spans。当你把多个评估器组合进一个实验时通常是有意混用层级一个快速的输出检查加上一个读取整段运行的轨迹检查。v0.1.0 提到的四种评估类型在 评估器总览 中落实为四类内置评估器外加技能Skill、确定性Deterministic与自定义Custom三类质量QualityOutputEvaluatorOUTPUT_LEVEL按你写的 rubric 评估任意主观质量、HelpfulnessEvaluator、FaithfulnessEvaluator事实性与 groundedness、CorrectnessEvaluator、CoherenceEvaluator、ConcisenessEvaluator、ResponseRelevanceEvaluator以上均为 TRACE_LEVEL以及TrajectoryEvaluator、InteractionsEvaluatorSESSION_LEVEL分别评估动作序列/工具使用模式与对话模式/交互质量安全SafetyHarmfulnessEvaluator危险或冒犯内容、RefusalEvaluator对合理请求的不当拒绝、StereotypingEvaluator针对群体的偏见与刻板印象均返回二分类结果多模态MultimodalMultimodalOutputEvaluator、MultimodalOverallQualityEvaluatorLikert-5 总体质量、MultimodalCorrectnessEvaluator对图像内容的事实核查、MultimodalFaithfulnessEvaluator幻觉检查、MultimodalInstructionFollowingEvaluator约束合规检查AgenticToolSelectionAccuracyEvaluator与ToolParameterAccuracyEvaluatorTOOL_LEVEL、InstructionFollowingEvaluator、FailureCommunicationEvaluator、PartialCompletionEvaluator、RecoveryStrategyEvaluatorTRACE_LEVEL、GoalSuccessRateEvaluatorSESSION_LEVEL判断用户目标是否达成技能SkillSkillSelectionAccuracyEvaluator与SkillInstructionFollowingEvaluatorSESSION_LEVEL分别评估技能选择是否恰当、是否完整遵循技能步骤。LLM-as-a-Judge用自定义 rubric 做结构化评分v0.1.0 的核心能力之一是内置 LLM 裁判评估器。以OutputEvaluator为例它针对你编写的 rubric评分准则对响应进行结构化评分。下面是最小的端到端示例来自 quickstart.mdx并在 index.mdx 中复现from strands import Agent from strands_evals import eval_task, Case, Experiment from strands_evals.evaluators import OutputEvaluator # eval_task 装饰器处理样板代码只需返回一个 Agent eval_task() def get_response(): return Agent( system_promptYou are a helpful assistant that provides accurate information., callback_handlerNone ) # 创建测试用例 test_cases Case[str, str, Casestr, str, ] # 使用自定义 rubric 创建评估器 evaluator OutputEvaluator( rubric Evaluate the response based on: 1. Accuracy - Is the information factually correct? 2. Completeness - Does it fully answer the question? 3. Clarity - Is it easy to understand? Score 1.0 if all criteria are met excellently. Score 0.5 if some criteria are partially met. Score 0.0 if the response is inadequate or incorrect. , include_inputsTrue ) # 创建并运行实验 experiment Experimentstr, str report experiment.run_evaluations(get_response) report.run_display() # 保存实验供后续分析 experiment.to_file(basic_evaluation)运行python -u basic_eval.py后run_display()会打印每个用例的分数、是否通过以及裁判judge的推理随后是整体统计实验同时被保存到basic_evaluation.json。用例很多时Experiment还提供run_evaluations_async方法并发运行并返回同样的报告。关于eval_task装饰器它消除了样板代码函数可以返回一个Agent自动以case.input调用、一个str或一个dict对于基于轨迹的评估器用eval_task(TracedHandler())即可自动收集 spans细节见 Task Decorator 指南。基于轨迹的评估OpenTelemetry 执行轨迹v0.1.0 明确提到通过 OpenTelemetry 执行轨迹分析 Agent 行为。这意味着评估不局限于最终输出文本还可以读取 Agent 运行全程的模型响应与工具调用记录trajectory。在仓库文档中这条能力线分两层实现**会话映射器Session Mappers**把原始遥测 span 转换为评估器消费的Session格式见 trace_providers.mdx映射器适用场景StrandsInMemorySessionMapperStrands Harness SDK 内存 span本地评估默认LangChainOtelSessionMapper使用 OpenTelemetry 插桩的 LangChain 应用OpenInferenceSessionMapper使用 OpenInference 插桩的应用如 Arize Phoenix不确定用哪个映射器时可用detect_otel_mapper(spans)依据 span 属性自动检测返回合适的映射器类。轨迹提供者Trace Providers从可观测性后端拉取 Agent 执行数据并转换为评估管线需要的格式从而让你无需重跑 Agent直接对生产或预发环境留下的轨迹执行评估提供者后端认证方式CloudWatchProviderAWS CloudWatch LogsBedrock AgentCore 运行时日志AWS 凭证boto3LangfuseProviderLangfuseAPI 密钥OpenSearchProviderOpenSearch自托管或 Amazon OpenSearch ServiceBasic auth 或 SigV4安装方面CloudWatchProvider开箱即用boto3 是核心依赖LangfuseProvider需pip install strands-agents-evals[langfuse]OpenSearchProvider需pip install strands-agents-evals[opensearch]。以CloudWatchProvider为例它通过 CloudWatch Logs Insights 查询 Bedrock AgentCore 运行时日志组中的 OpenTelemetry 日志记录log_group与agent_name二选一region依次回退到AWS_REGION、AWS_DEFAULT_REGION、us-east-1lookback_days默认 30控制向前搜索的天数query_timeout_seconds默认 60.0控制查询超时。所有提供者实现统一的TraceProvider接口只需一个方法data provider.get_evaluation_data(session_idmy-session-id) # data[output] - str (最终 Agent 响应) # data[trajectory] - Session (traces 与 spans)把提供者数据包装进任务函数即可接入标准Experiment管线若轨迹检索失败提供者会抛出SessionNotFoundError会话无轨迹或ProviderError提供者不可达/查询失败两者都继承自TraceProviderError。还可以子类化TraceProvider实现自定义提供者返回的TaskOutput必须包含output最终响应文本与trajectory含AgentInvocationSpan、InferenceSpan、ToolExecutionSpan等类型化 span 的Session对象。内置评分工具确定性评估器与轨迹匹配v0.1.0 提及的精确、按顺序、任意顺序的轨迹匹配辅助函数在仓库中演化为 确定性评估器Deterministic Evaluators纯代码检查、无需 LLM、结果完全可复现天然适合回归测试与 CI/CD 管线。v0.1.0 之后还新增了面向轨迹的ToolCalled与SkillInvoked输出类Equals(valueParis)输出等于期望值value为None时改用用例的expected_outputContains(valueParis, case_sensitiveFalse)输出包含子串case_sensitive默认TrueStartsWith(valueThe capital, case_sensitiveFalse)输出以指定前缀开头。轨迹类ToolCalled(tool_namecalculator)轨迹中是否调用过指定工具兼容列表型轨迹与Session对象SkillInvoked(skill_namepdf-processing)轨迹中是否成功加载并调用指定技能被拒绝的加载不计入因为 Agent 从未获得该技能命中得 1.0reason字段区分从未请求该技能与请求了但加载失败。环境状态类StateEquals(nametemperature, value72.0)具名环境状态是否等于期望值用于校验使用工具的 Agent 是否正确产生了副作用value为None时改用用例的expected_environment_state。确定性评估器与 LLM 评估器组合使用效果最佳——先做快速精确检查再做需要语义判断的质量评估from strands_evals.evaluators import Contains, HelpfulnessEvaluator, CorrectnessEvaluator evaluators [ Contains(valueParis), # 快速确定性检查 CorrectnessEvaluator(), # LLM 事实正确性 HelpfulnessEvaluator(), # LLM 有帮助程度 ]自定义评估器当内置评估器都不合适时v0.1.0 承诺的可扩展框架体现在继承基类Evaluator实现自己的评估逻辑即可详见 Custom Evaluators。仓库的 custom_evaluator.py 示例 展示了完整写法评估器需要返回分数score、通过/失败pass/fail与推理reason三要素从而无缝接入Experiment的聚合报告。自动化实验生成从上下文描述到完整测试套件v0.1.0 的自动化实验生成能力由ExperimentGenerator实现文档见 experiment_generator.mdx。给它一段 Agent 工具与任务的描述它会用 LLM 生成测试用例、把用例分散到多个主题与难度级别并可为默认评估器自动生成评分 rubric。基本用法从上下文生成import asyncio from strands_evals.generators import ExperimentGenerator from strands_evals.evaluators import OutputEvaluator generator ExperimentGeneratorstr, str async def generate_experiment(): experiment await generator.from_context_async( context Available tools: - calculator(expression: str) - float: Evaluate mathematical expressions - current_time() - str: Get current date and time , task_descriptionMath and time assistant, num_cases5, evaluatorOutputEvaluator ) return experiment experiment asyncio.run(generate_experiment()) print(fGenerated {len(experiment.cases)} test cases)生成器提供四种方法from_context_async(context, task_description, num_cases, num_topics, evaluator)基于特定上下文生成num_topics可选用于跨主题分散用例from_scratch_async(topics, task_description, num_cases, evaluator)从主题列表与任务描述从零生成from_experiment_async(source_experiment, task_description, num_cases, extra_information)以现有实验为灵感为新任务生成相似实验update_current_experiment_async(source_experiment, task_description, num_cases, context, add_new_cases, add_new_rubric)为现有实验增量补充用例与 rubric。配置选项支持复杂输入/输出类型如ExperimentGenerator[Dict[str, str], List[str]]配合include_expected_trajectoryTrue、include_metadataTrue、并行生成max_parallel_num_cases20最多并发生成 20 个用例以及自定义 promptcase_system_prompt与rubric_system_prompt默认模板位于strands_evals.generators.prompt_template.prompt_templates。难度分布是自动的Easy 约 30%基础直接场景、Medium 约 50%标准复杂度、Hard 约 20%复杂与边界用例。生成器可为三个默认评估器自动创建 rubricOutputEvaluator、TrajectoryEvaluator、InteractionsEvaluator其他评估器需传evaluatorNone或用Evaluator()占位或像construct_evaluator_async的注释说明那样对非默认评估器如HelpfulnessEvaluator直接实例化后追加到experiment.evaluators。最佳实践文档明确给出提供详尽的上下文含工具签名、返回值说明、行为模式比笼统描述生成质量高得多15 用例建议启用主题规划num_topics4保证覆盖度从小规模起步、跑完评估后针对暴露的弱点增量扩展每一步生成后及时experiment.to_file(fexperiment_v{version})保存中间结果。实验管理JSON 序列化保存、加载与版本化v0.1.0 的实验管理能力落实为 JSON 序列化机制experiment.to_file(basic_evaluation)保存产出basic_evaluation.jsonExperiment.from_file(original_experiment.json)加载。这让实验可以保存、重载、对比也支持把实验文件作为版本化资产纳入代码库。更完整的说明见 Experiment Management 与 Serialization。模拟器多轮对话与工具行为的真实化v0.1.0 对模拟器的描述是通过生成随 Agent 响应自适应调整的真实交互模式实现对话 Agent 的多轮评估。仓库中的 Simulators 总览 给出了两个内置模拟器ActorSimulator扮演对话中的任意参与者——最常用的是用户模拟user simulation也可通过自定义 profile 扮演客服代表、领域专家、对抗性测试者、内部员工等。它持有 actor profile、根据对话历史生成响应、并跟踪目标完成状态把max_turns设为 5简单任务或 12复杂任务可平衡完整度与效率。ToolSimulator代替 Agent 真实调用的工具。不用执行真实函数而是让 LLM 依据 schema 生成合法响应并通过share_state_id在相关工具间共享状态例如传感器与控制器作用于同一环境保证连续调用的一致性。适合真实工具依赖线上基础设施、需要可控行为或工具仍在开发中的场景from typing import Any from pydantic import BaseModel, Field from strands import Agent from strands_evals.simulation.tool_simulator import ToolSimulator tool_simulator ToolSimulator() class WeatherResponse(BaseModel): temperature: float Field(..., descriptionTemperature in Fahrenheit) conditions: str Field(..., descriptionWeather conditions) tool_simulator.tool(output_schemaWeatherResponse) def get_weather(city: str) - dict[str, Any]: Get current weather for a city. pass weather_tool tool_simulator.get_tool(get_weather) agent Agent(tools[weather_tool], callback_handlerNone) response agent(Whats the weather in Seattle?)模拟器与评估器是互补关系模拟器生成多轮对话评估器如HelpfulnessEvaluatorGoalSuccessRateEvaluator再评估这些交互的质量。一个实用的细节是当 actor 发出完成信号时模拟器会设置result.structured_output.stop True以及自身的simulator.stop标志判断目标是否达成应检查该标志而不是扫描消息文本has_next()返回 False 既可能是目标达成也可能是撞上max_turns需要时用stop_reason goal_completed区分。仓库还提供了 actor_simulator.py 与 tool_simulator.py 可直接运行的示例。CLI一行命令跑完评估最快的上手方式是安装包自带的strands-evals命令无需编写 runner 脚本pip install strands-agents-evals # 一次性检查Agent 的回答是否包含 Paris strands-evals run \ --input What is the capital of France? \ --expected-output Paris \ --agent my_agent:build_agent # 从上下文描述生成一个入门实验然后运行它 strands-evals generate \ --context $(cat tools.txt) \ --num-cases 10 \ -o experiment.json strands-evals run experiment.json --agent my_agent:build_agent --display其中strands-evals run的--rubric会自动接线一个OutputEvaluator--evaluator接受helpfulness、correctness等内置短名完整列表见 run 命令文档strands-evals generate则包装了上面的ExperimentGenerator支持--task-description、--num-topics、--evaluator TrajectoryEvaluator等参数还能通过--experiment扩展现有实验文件详见 generate 命令文档。CLI 一节还包含报告渲染report与失败会话诊断diagnose等子命令便于把评估接入 CI 流水线。快速开始安装、凭证与第一个评估安装要求 Python 3.10建议使用虚拟环境python -m venv .venv # macOS / Linux: source .venv/bin/activate # Windows (CMD): .venv\Scripts\activate.bat # Windows (PowerShell): .venv\Scripts\Activate.ps1 pip install strands-agents-evals strands-agents配置凭证Strands Evals 复用 Strands Agents 的模型提供方默认由 Amazon Bedrock 上的 Claude 担任裁判模型因此需要配置可调用 Claude 的 AWS 凭证环境变量AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/可选AWS_SESSION_TOKEN或aws configure或在 EC2/ECS/Lambda 上使用 IAM 角色并在 Bedrock 控制台开通模型访问。第一个评估按上文 LLM-as-a-Judge 一节的代码创建basic_eval.py并运行python -u basic_eval.py即可看到每个用例的分数、通过状态与裁判推理以及整体统计。完整的端到端演练见 quickstart.mdx。从入门到落地推荐的进阶路径围绕 v0.1.0 的能力清单仓库文档给出了一条清晰的实践路径按 SOP 迭代Eval SOP 提供了一套可重复的评估—改进流程选对评估器从 评估器总览 的表格按要检查什么 × 什么粒度挑选内置评分器质量类从OutputEvaluator起步诊断失败评估器只说失败检测器 负责自动失败检测与根因分析驱动多轮对话需要轨迹类评分时用 模拟器 生成对话用 trace-based 任务收集 spans接入 CLI/CI用 CLI 在 shell 中运行实验配合确定性评估器做零成本回归测试参考可运行示例仓库 site/docs/examples/evals-sdk 目录收录了 30 个可直接运行的示例覆盖输出/正确性/忠实度/连贯性/有帮助程度等单评估器脚本、evaluate_async.py/evaluate_graph.py/evaluate_swarm.py等不同运行形态以及chaos_*系列混沌测试脚本与experiment_generator数据集生成脚本。简而言之Strands Evals v0.1.0 确立的架构——实验/用例/任务/评估器四构件、三个评估层级、LLM 裁判 轨迹评估 确定性检查 模拟器的组合——构成了一个既能打分、又能解释为什么失败、还能自动造数据与模拟真实用户的完整评测体系足以支撑从单条输出校验到生产环境持续监控的 Agent 质量保障闭环。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐LLM Zoomcamp Agent 评估实战用 A→Q→A′ 框架与 LLM Judge 同时评判答案质量和工具调用轨迹LLM Zoomcamp Agent 评估实战用 A→Q→A′ 框架与 LLM Judge 同时评判答案质量和工具调用轨迹 在 LLM Zoomcamp 的示例工程教程人工智能大模型基于 Agent-Skills-for-Context-Engineering 的高级评估实践构建生产级 LLM-as-a-Judge 评估系统基于 Agent Skills for Context Engineering 的高级评估实践构建生产级 LLM as a Judge 评估系统 LLM as人工智能AI 技能提示工程AI 评测用 LLM 当裁判基于 Agent Skills for Context Engineering 构建生产级 LLM-as-a-Judge 评估技能用 LLM 当裁判基于 Agent Skills for Context Engineering 构建生产级 LLM as a Judge 评估技能 导读 本人工智能AI 技能提示工程AI 评测上一篇最完整Obsidian Text Generator使用指南从安装到高级配置下一篇终极指南如何在iOS应用中快速实现专业计时器功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考