agent-platform-eval-flywheel

Agent Platform Eval Flywheel 技能

帮助用户使用 Agent Platform GenAI Evaluation SDK（google.genai / agentplatform）评估并迭代改进生成式 AI 模型和 Agent。

何时使用此技能

• 使用 Agent Platform GenAI Evaluation SDK（client.evals.evaluate()）评估生成式 AI Agent 或模型。
• 从会话轨迹、pandas DataFrame 或合成生成中创建评估数据集。
• 选择、配置或编写自定义评估指标。
• 分析评分标准判定结果、损失模式并对失败案例进行聚类。
• 根据评估结果提出具体的代码／提示词改进建议。
• 评估部署在 Agent Platform 端点上的模型（BYOM），或通过 ID 指定的 Model-as-a-Service (MaaS) 模型，包括在需要时先部署模型。此时请遵循 references/deployment.md，并使用 endpoint_evaluation.py / maas_evaluation.py 脚本。

安全与确认级别（重要）

在代表用户执行任何命令或脚本之前，必须遵守以下针对所请求操作的安全级别：

1. R 级：只读（inspect_results.py、compare_results.py、validate_dataset.py、parse_adk_traces.py、render_html_report.py）
   • 规则：无需确认。你可以立即执行这些辅助脚本，以检查数据、验证架构、解析轨迹或比较评估结果。
2. M 级：会产生计算成本的只读操作（client.evals.run_inference、client.evals.evaluate、client.evals.generate_conversation_scenarios、client.evals.generate_loss_clusters）
   • 规则：这些操作会调用大模型或远程评估服务，消耗计算资源并产生费用，因此必须通过“是”／“否”选项进行交互式确认。
   • 每次评估都必须确认：每次评估、重新评估、指标更新、参数变更或合成场景生成，都必须单独提供试运行预览并进行交互式确认。未经提供新的确认预览并获得用户批准，绝不能执行第二次评估、比较操作或修改后的评估。
   • 同轮限制：提出确认请求的同一轮中，不要运行评估。提出请求后应结束本轮并等待用户回复；只有获得明确的“是”／批准后，才能执行。在用户有机会回复之前先打印预览，再调用工具，不算获得了确认。
   • 禁止预先执行远程评估：在获得用户确认之前，绝不能执行 client.evals.evaluate()、client.evals.run_inference()、client.evals.generate_conversation_scenarios()，也不能运行调用这些远程操作的任何脚本。在初始轮次中，你可以准备本地数据结构并编写脚本，但必须先提供试运行预览卡片并获得用户明确确认，然后才能调用任何远程评估或场景生成操作。
   • 获批后立即执行：用户明确批准（例如“是”“已批准”“继续”“开始”）后，应立即通过 run_command 执行预览过的评估脚本并报告结果。不要在未执行获批操作的情况下结束本轮。

设置

这些脚本需要 vertexai（来自 google-cloud-aiplatform[evaluation]）、 google-genai、pandas 和 requests。不要创建虚拟环境——它初始为空，会隐藏环境已提供的软件包，导致重复安装。先检查，只安装缺少的软件包：

python3 -c "import vertexai, google.genai, pandas, requests" \
  || pip install 'google-cloud-aiplatform[evaluation]>=1.163.0' 'google-genai>=1.0.0'

版本说明符必须加引号：如果不加引号，bash 会将 >=1.154.0 解析为重定向，并悄悄写入一个空文件，而不是限制安装版本。

需要 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。

• 保留用户的项目和位置：始终优先使用用户明确提供的项目和位置（例如 project='<PROJECT_NUMBER>'、 location='us-central1'）。除非用户明确要求使用 'global'，否则绝不要将用户要求的位置更改或覆盖为 'global'。
• 缺少参数：如果用户的请求未提供项目或位置，你必须暂停响应，并在准备或运行评估前询问用户缺少的位置或项目。

正确的 SDK 入口点

import agentplatform
client = agentplatform.Client(project=PROJECT, location=LOCATION)

client.evals.run_inference(model=..., src=...)
client.evals.evaluate(dataset=..., metrics=...)
client.evals.generate_conversation_scenarios(...)

有两个看似合理、实际却不正确的导入方式：

• from agentplatform.types import evals —— 会出现 ModuleNotFoundError。types 是模块，不是包；请使用 from agentplatform import types。
• from vertexai.evaluation import PointwiseMetric, EvalTask —— 这是已被取代的 SDK。它的类接受不同的参数（PointwiseMetric 没有 system_instruction），因此使用它编写的代码会因 TypeError 而失败，而非因导入错误失败。请始终使用 agentplatform。

质量飞轮

分为五个阶段，首次按顺序运行，然后循环执行 2 → 5，直到达到质量目标。

浪费时间的捷径

捷径	失败原因
"我会调低指标阈值，	这会掩盖真实故障。修复 Agent，
: 让它通过。" : 而不是降低标准。 :
"这个用例不稳定，我跳过它。"	不稳定性揭示了 Agent 的非确定性。
: : 使用 temperature=0 或更严格的指令修复。:
: : :
"我只需要修复评估数据集，	如果预期输出不断变化，说明 Agent 存在
: 不需要修复 Agent。" : 行为问题。 :
"从轨迹中我就能看出它能正常工作	自我评分无法泛化。始终运行
: ——跳过阶段 3。" : evaluate() 并查看分数。 :
: : :
"一次迭代就够了。"	预计需要 5–10 次以上迭代。过早停止会
: : 导致其他指标上的回归未被发现。 :

1. 准备数据

生成一个 EvaluationDataset。输入有三种格式，请选择与用户现有数据相匹配的一种：

• EvalCase 列表（单轮或多轮）：

  from agentplatform import types
  from google.genai import types as genai_types
  
  # prompt/reference/response 的值是 Content，而不是 str。UserContent 和
  # ModelContent 会包装普通字符串，并设置正确的角色。
  dataset = types.EvaluationDataset(eval_cases=[
      types.EvalCase(
          prompt=genai_types.UserContent("What is 2+2?"),
          responses=[types.ResponseCandidate(
              response=genai_types.ModelContent("4"))],
          reference=types.ResponseCandidate(
              response=genai_types.ModelContent("4")),
      ),
      # 对于多轮 Agent 轨迹，请设置 agent_data，而不是 prompt/responses。
  ])
  

  多轮 Agent 轨迹会将每次对话封装为 AgentData → ConversationTurn → AgentEvent。完整的类型层次结构请参见 references/dataset_schema.md。

• Pandas DataFrame（表格数据源 — CSV、BigQuery、Sheets）：

  import pandas as pd
  from agentplatform import types
  
  df = pd.DataFrame({
      "prompt":    ["What is 2+2?", "Capital of France?"],
      "response":  ["4",            "Paris"],
      "reference": ["4",            "Paris"],
  })
  dataset = types.EvaluationDataset(eval_dataset_df=df)
  

  列名必须与所选指标要求的字段一致（各指标的要求表请参见 references/dataset_schema.md）。

• 冷启动（完全没有数据）： 使用 client.evals.generate_conversation_scenarios(agent=..., config=...) 在服务端合成场景—— 参数应为 agent 或 agent_info，而不是 agents，且必须提供 config。 配置类是 types.evals.UserScenarioGenerationConfig，而不是 types.UserScenarioGenerationConfig。设置其 user_scenario_count （1-100）：该值默认为 None，客户端会接受此值，但服务端会以 400 INVALID_ARGUMENT 拒绝调用。count 是单独的字段，不能替代它。 第 2 阶段会执行这些场景。

  • 重要 — 多轮用户模拟场景必须使用此 API： 当用户要求合成多轮用户场景，以模拟客户与 Agent 互动时 （而不是在沙盒中编写本地单轮测试数据集），绝不能自行用文字编写 对话场景，也不能手动编写场景文件。调用 client.evals.generate_conversation_scenarios 属于服务端 Tier M API 调用（使用用户的项目、位置、模型和环境数据），并且需要确认卡片； 在沙盒中编写本地单轮数据集文件且不调用 Agent Platform API，则属于 Tier R。
  • 重要 — 请求信息不完整：当用户要求合成场景，但请求中缺少必需参数 （例如 location、environment_data、simulation_instruction 或 model_name）时，切勿假定默认值或猜测。你必须在第一轮暂停，并明确向 用户询问缺失信息（例如：“请提供缺失的模拟指令、环境数据、模型名称 和位置。”）。只有在用户提供这些信息后，才能继续进行试运行预览。 location 没有安全的默认值：无论是 us-central1，还是你为其他调用自行 假定的位置，都不能替代用户尚未提供的位置。
  • 参数调整与异议：当用户要求生成合成用户场景，但修改了所请求的参数 （例如场景数量、模型或指令）或提出异议时，你必须提供一张包含更新后参数的 试运行确认卡片，并等待用户明确批准，然后才能通过 run_command 执行生成代码。

• 托管 Agent（Gemini Agents API）： 评估通过 Managed Agents API 创建的 Agent。使用 generate_conversation_scenarios 根据 Agent 的配置 创建测试场景，使用 run_inference 执行 Agent，并使用 evaluate 对轨迹评分。这些函数现在接受托管 Agent 和交互 ID 作为输入。你也可以使用 InteractionsDataSource 评估通过 Interactions API 记录的现有交互。完整代码 模式请参见 references/sdk_patterns.md 中的模式 8。 对于 ADK 会话转储，请使用 scripts/parse_adk_traces.py，不要手动编写转换代码。

2. 运行推理

在数据集中填充响应和轨迹。如果轨迹已完整（例如，生产日志或回放），跳过此阶段。

# Agent eval — pass a callable wrapping the user's ADK Agent/App.
client.evals.run_inference(model=agent_callable, src=dataset)

# Model eval — pass a model ID directly.
client.evals.run_inference(model="gemini-2.5-flash", src=dataset)

# Synthesized scenarios — let the simulator drive.
client.evals.run_inference(
    model=agent_callable,
    src=dataset,
    user_simulator_config=UserSimulatorConfig(max_turn=10),
)

# DataFrame also works as src= — no EvalCase wrapping needed.
client.evals.run_inference(model="gemini-2.5-flash", src=df)

# Managed Agent — pass an agent resource name.
AGENT_RESOURCE = f"projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}"
client.evals.run_inference(
    agent=AGENT_RESOURCE,
    src=scenarios,
    config={"user_simulator_config": {"max_turn": 3}},
)

3. 评分（始终运行）

result = client.evals.evaluate(dataset=dataset, metrics=[...])
result.show()  # Interactive HTML report with scores, rubrics, and traces.

根据要衡量的内容选择指标。 完整目录见 references/metric_registry.md。

如果用户指定了指标，请直接使用。 以下表格中的每个标识符（general_quality、text_quality、instruction_following、hallucination、grounding、safety、multi_turn_*、final_response_*、tool_use_quality）都是 types.RubricMetric.<UPPERCASE_NAME> 访问器——直接将其传入 metrics=[types.RubricMetric.GENERAL_QUALITY, ...]。对于这里列出的名称，不要搭建自定义 LLMMetric，也不要使用 vertexai.evaluation.EvalTask / PointwiseMetric / MetricPromptTemplateExamples——该 SDK 已被取代（见 Setup）。

judge_model 格式及处理用户指定的模型：

• judge_model 必须使用完整资源名称：LLMMetric 和 RubricMetric 都会将 judge_model 作为 autorater_config.autorater_model 发送到后端（尽管 agentplatform 会针对 RubricMetric 在客户端日志中发出“已忽略”警告）。"gemini-2.5-flash" 或 "gemini-2.5-pro" 之类的短名称会报错 400 INVALID_ARGUMENT ("Invalid autorater model resource name")。请始终传入完整的发布方模型资源名称： f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_NAME}" （优先使用 gemini-2.5-flash 作为评分模型；gemini-2.5-pro 在服务器端可能会间歇性地报错 "Rubric results could not be reliably computed"）。
• 数据集不含响应与包含响应时的处理：
  • 如果数据集仅包含提示词（没有 response 列），先调用 run_inference(model="<the named model>", src=dataset) 生成候选模型的响应，然后使用 evaluate() 评分。
  • 如果用户在数据集中已提供 response，不要调用 run_inference——run_inference 会用模型生成的输出覆盖现有的 response 列，从而丢弃用户提供的响应！此时，请直接使用 evaluate(dataset=dataset, ...) 对用户提供的 response 评分，并在 judge_model 中将指定模型作为完整资源路径传入（或者，如果预定义的 RubricMetric 无法使用该评分模型可靠地计算评分结果，则改用默认评分模型并说明原因）。

Agent 指标（多轮、自适应评分标准）——Agent 评估请从这里开始。

目标	指标
Agent 是否实现了用户的目标？	multi_turn_task_success
推理路径是否合乎逻辑且高效？	multi_turn_trajectory_quality
跨轮次的工具／函数调用质量	multi_turn_tool_use_quality
整体对话质量	multi_turn_general_quality
最终响应质量（无需参考答案）	final_response_quality
最终响应与标准参考答案的匹配度	final_response_match
单轮工具使用	tool_use_quality

通用质量指标（单轮、自适应评分标准）——用于模型评估。

目标	指标
整体响应质量（推荐的起点）	general_quality
语言质量（流畅度、连贯性、语法）	text_quality
对特定约束／指令的遵循程度	instruction_following

静态评分标准指标（固定标准）——与上述指标配合使用。

目标	指标
捕获幻觉陈述（RAG、事实性回答）	hallucination
依据所提供上下文的事实性／一致性	grounding
安全策略合规性	safety

**没有内置指标覆盖的特定领域检查：**编写自定义指标。

• 预定义：types.RubricMetric.<NAME> — 服务端 AutoRater，无需评判模型。
• **自定义 LLM-as-a-judge：**使用 types.LLMMetric 和 prompt_template，或使用 types.MetricPromptBuilder 编写结构化评分标准。始终设置 judge_model；其默认值为 None，此时每个用例都会失败并返回 400 INVALID_ARGUMENT: Error parsing JSON。
  • 评判模型选择：如果用户指定了评判模型（例如 gemini-2.5-pro），请使用该模型。如果用户未指定评判模型，或表示没有相关信息／偏好，请在试运行预览卡片中默认使用 gemini-2.5-flash 作为评判模型，并询问用户是否确认运行评估。用户未指定评判模型时，切勿停止或拒绝评估。
• **自定义代码：**使用 types.CodeExecutionMetric，并通过包含 def evaluate(instance: dict) 的 custom_function 字符串进行远程沙盒执行；或者使用 types.Metric，通过 custom_function=<callable> 在本地执行。instance 字典中的 prompt / response / reference 是 Content 字典，而不是字符串；编写函数体前，请先阅读 references/metric_registry.md（“函数接收的内容”），不要通过运行评估来探查数据结构。

始终保存结果，以便第 4 和第 5 阶段读取。保存为 JSON （机器可读、可比较差异）和 HTML（人类可读、可链接）两种格式：

import datetime
from pathlib import Path

from agentplatform._genai import _evals_visualization

out_dir = Path("artifacts/grade_results")
out_dir.mkdir(parents=True, exist_ok=True)
ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")

# fallback=str, or a DataFrame-backed dataset raises PydanticSerializationError.
result_json = result.model_dump_json(fallback=str)
(out_dir / f"results_{ts}.json").write_text(result_json)

html = _evals_visualization.get_evaluation_html(result_json)
(out_dir / f"results_{ts}.html").write_text(str(html))

或者事后运行：scripts/render_html_report.py --type evaluation 或 scripts/inspect_results.py --save-html。

4. 分析失败

读取 summary_metrics 和 eval_case_results — 切勿编造分数。使用 scripts/inspect_results.py --failing-only 筛选失败项。

对于每项未通过的指标，请参阅 references/failure_patterns.md 了解更深入的诊断。简要对应关系：

未通过的指标	需要更改的内容
multi_turn_task_success 低	Agent 未能完成目标 —
: : 修复编排、缺失的工具调用、过早终止、 :
: : 工具选择错误。 :
multi_turn_trajectory_quality 低	Agent 达成目标的方式
: : 效率低下 — 优化规划提示词， :
: : 移除多余的工具调用。 :
multi_turn_tool_use_quality 低	修复工具描述、参数
: : 文档字符串或用于选择工具的 Agent 指令。 :
final_response_quality 低	查看自动生成的评分标准判定；
: : 优化指令，解决得分最低的 :
: : 标准项。 :
final_response_match 低	Agent 的最终回答与黄金参考答案不匹配 —
: : 调整回答格式或更新参考答案。 :
hallucination 低	收紧指令，确保回答以工具输出为依据；
: : 验证工具是否确实返回了所声称的数据。 :
grounding 低	回答与所提供的上下文矛盾 —
: : 添加明确的“仅引用上下文”指令。 :
safety 低	添加安全防护措施；查看
: : 评分标准判定中违反要求的内容类别。 :
general_quality / text_quality	调整系统指令的措辞；模型的
: 低 : 默认表述对于该任务来说过于通用。 :
instruction_following 低	Agent 忽略了约束 —
: : 在系统指令中重申这些约束， :
: : 或使用更严格的措辞。 :
Agent 调用了错误的工具	修复工具描述、Agent 指令，
: : 或 tool_config。 :
Agent 调用了额外工具	添加明确的停止指令，或
: : 切换到 :
: : multi_turn_tool_use_quality， :
: : 以便在评分标准中显示额外调用。 :

同一指标有 10 次或更多失败时，请使用错误分析服务，将失败归类为主题（L1/L2 分类体系类别），而不是逐一阅读每条轨迹：

# Only supports multi_turn_task_success and multi_turn_tool_use_quality.
# Service runs in the global region.
analysis_client = agentplatform.Client(project="PROJECT_ID", location="global")
response = analysis_client.evals.generate_loss_clusters(
    eval_result=result,
    metric="multi_turn_task_success",
    config={"max_top_cluster_count": 5},
)
for r in response.results:
    for cluster in r.clusters:
        print(
            f"[{cluster.taxonomy_entry.l1_category}/"
            f"{cluster.taxonomy_entry.l2_category}] "
            f"{cluster.item_count} cases — {cluster.taxonomy_entry.description}"
        )

保存 response.model_dump_json()，并使用 scripts/render_html_report.py --type loss-analysis 进行渲染。

5. 优化与迭代

针对未达标的指标应用修复。重新运行 Stage 3。使用 scripts/compare_results.py --baseline <prev> --candidate <new> 进行比较，确认 目标指标有所提升，且其他指标均未退步。

跟踪每次迭代的进度：

迭代	指标 A	指标 B	所做更改
基线	0.62	0.55	—
v2	0.78	0.68	添加了 grounding 提示词
v3	0.81	0.72	修复了工具选择

预计每个未达标用例需要迭代 5–10 次甚至更多。只有用例通过后，才应通过增加更多评估用例来扩大覆盖范围。

证明你的工作

绝不要声称评估结果，除非你从实际的 result 对象中读取了这些结果。

• 运行评估后，打印 summary_metrics 表格 （scripts/inspect_results.py）。
• 修复后，通过 scripts/compare_results.py 展示前后对比。
• 宣布成功之前，确认所有用例都已通过，而不只是你正在处理的用例。

如果无法提供证据（SDK 调用失败、结果被截断、指标不受支持），请明确说明。不要掩盖问题。

协作规则

1. 始终先制定计划： 编写脚本前，输出一个 <plan> 块，详细说明你将采取的步骤。
2. 逐步执行： 准备数据和评估脚本，展示包含完整参数的试运行确认卡片，等待用户批准，只有在得到明确确认后才能执行，然后检查并分析结果。未经用户确认，不得调用评估。
3. 使用标准 Python： 使用标准 Python 导入语句（import agentplatform、from google.genai import types）。不要使用内部导入路径。
4. 先验证，再猜测： 不确定 SDK 类型或指标时，先检查 SDK 源代码，不要猜测或臆造。
5. 每轮都要有明确结尾： 每轮都必须以非空且内容明确的文本回复用户，总结已采取的操作或说明后续步骤。什么都不返回会被视为失败，无论工具执行了什么。

SDK 快速参考

import agentplatform
from agentplatform import types
from google.genai import types as genai_types
import pandas as pd

# Initialize client
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

# --- SINGLE-TURN EVAL (pandas DataFrame) -- RECOMMENDED ---
# The converter wraps plain strings for you.
df = pd.DataFrame({
    "prompt":   ["Q1", "Q2"],
    "response": ["A1", "A2"],
})
dataset = types.EvaluationDataset(eval_dataset_df=df)

# --- SINGLE-TURN EVAL (direct EvalCase) ---
# Verbose and easy to get wrong; see references/dataset_schema.md for the
# exact types before using this form.
dataset = types.EvaluationDataset(eval_cases=[
    types.EvalCase(
        prompt=genai_types.UserContent("Query here"),
        responses=[types.ResponseCandidate(
            response=genai_types.ModelContent("Model response here"))],
        reference=types.ResponseCandidate(
            response=genai_types.ModelContent("Ground truth here")),
    ),
])

# --- MULTI-TURN AGENT EVAL ---
agent_data = types.evals.AgentData(
    agents={"my_agent": types.evals.AgentConfig(
        agent_id="my_agent", instruction="You are helpful.")},
    turns=[types.evals.ConversationTurn(turn_index=0, events=[
        types.evals.AgentEvent(author="user",
            content=genai_types.Content(role="user",
                parts=[genai_types.Part(text="Hello")])),
        types.evals.AgentEvent(author="my_agent",
            content=genai_types.Content(role="model",
                parts=[genai_types.Part(text="Hi! How can I help?")])),
    ])],
)
dataset = types.EvaluationDataset(
    eval_cases=[types.EvalCase(agent_data=agent_data)])

# --- METRICS ---
predefined = types.RubricMetric.MULTI_TURN_TRAJECTORY_QUALITY
custom_llm = types.LLMMetric(name="tone",
    prompt_template="Is this polite? Response: {response}")
custom_code = types.CodeExecutionMetric(name="check",
    custom_function='def evaluate(instance): return {"score": 1.0}')

# --- EVALUATE ---
result = client.evals.evaluate(dataset=dataset, metrics=[predefined])

# --- RESULTS ---
for s in result.summary_metrics:
    print(f"{s.metric_name}: mean={s.mean_score}, pass_rate={s.pass_rate}")
for case in result.eval_case_results:
    for cand in case.response_candidate_results:
        for name, r in cand.metric_results.items():
            print(f"  {name}: score={r.score}, explanation={r.explanation}")

有关高级模式的详情，请参阅 references/sdk_patterns.md：合成数据生成、成对比较、MetricPromptBuilder、多 Agent 评估。

捆绑脚本

脚本	使用时机
validate_dataset.py	Stage 3 之前——检查 EvaluationDataset JSON 格式是否正确。
parse_adk_traces.py	Stage 1——将 ADK 会话转储转换为规范数据集格式。
inspect_results.py	Stages 3/4——显示摘要和每个用例的得分。使用 --save-html 生成可浏览的报告。
compare_results.py	Stage 5——比较基线与候选版本，检测回归。
render_html_report.py	根据已保存的结果 JSON 或 loss-clusters JSON 渲染 HTML。
endpoint_evaluation.py	针对已部署的 Agent Platform 端点执行 Stages 2/3（BYOM）。请参阅 references/deployment.md。
maas_evaluation.py	针对按 ID 指定的 Model-as-a-Service 模型执行 Stages 2/3。请参阅 references/deployment.md。