支持内置赋值器和地面真值字段先决条件正确性与预期的响应 GoalSuccessRate 带断言轨迹与预期轨迹匹配将所有基本真相字段合并到一个请求中了解被忽略的参考输入字段自定义评估器中的基本真相

实地真相评估

事实真相是给定输入的已知正确答案或预期行为，即你将实际结果与之比较的 “黄金标准”。对于代理评估，ground truth 将主观质量评估转化为客观测量，从而实现了通用评估人员无法自行提供的回归检测、基准数据集和特定领域的正确性。

通过实况评估，您可以在调用 Evaluate API 时在会话跨度旁边提供参考输入。该服务使用这些参考输入根据预期行为对代理的实际行为进行评分。不使用特定基本真值字段的赋值者会忽略该字段，并报告响应中未使用哪些字段。

支持内置赋值器和地面真值字段

下表显示了哪些内置赋值器支持地面真值以及它们使用哪些字段。

评估者	级别	地面真相字段	说明
`Builtin.Correctness`	跟踪	`expectedResponse`	衡量代理的响应与预期答案相匹配的准确程度。使用 LLM-as-a-Judge 评分。
`Builtin.GoalSuccessRate`	会话	`assertions`	验证代理的行为是否满足整个会话中的自然语言断言。使用 LLM-as-a-Judge 评分。
`Builtin.TrajectoryExactOrderMatch`	会话	`expectedTrajectory`	检查实际的工具调用序列是否与预期顺序完全匹配——相同的工具、相同的顺序、没有额外内容。程序化评分（没有 LLM 调用）。
`Builtin.TrajectoryInOrderMatch`	会话	`expectedTrajectory`	检查所有预期的工具是否在实际序列中按顺序显示，但允许在它们之间使用额外的工具。程序化评分。
`Builtin.TrajectoryAnyOrderMatch`	会话	`expectedTrajectory`	检查所有预期的刀具是否存在于实际序列中，无论顺序如何。允许使用额外的工具。程序化评分。

注意

自定义赋值器还通过其评估指令中的占位符支持真实情况字段。有关详细信息，请参阅自定义赋值器中的基本真相。

下表描述了基本真值字段。

字段	Type	Scope	说明
`expectedResponse`	字符串	跟踪	特工在特定回合中的预期响应。作用域为在参考输入上下文`traceId`中使用的跟踪。
`assertions`	字符串列表	会话	关于代理在整个会话中的行为的自然语言陈述应该是真实的。
`expectedTrajectory`	工具名称列表	会话	会话的预期工具调用顺序。

真实情况字段是可选的。如果你省略它们，赋值器就会回退到他们的基本无真模式（例如，如果不使用它们，它Builtin.Correctness仍然可以工作expectedResponse，它只根据上下文进行评估）。
您可以在单个请求中提供所有基本真相字段。该服务为每个评估者挑选相关字段，并在响应ignoredReferenceInputFields中报告所有未使用的字段。
您无需为每条痕迹expectedResponse提供信息。使用评估器的地面无真值变体来评估没有基本真值的轨迹。

先决条件

Python 3.10+
在 AgentCore Runtime 上部署且启用了可观察性的代理，或者使用配置了可AgentCore 观察性的受支持框架构建的代理。支持的框架：
- Strands Agents
- LangGraph 用opentelemetry-instrumentation-langchain或 openinference-instrumentation-langchain
已在中启用交易搜索 CloudWatch — 请参阅启用交易搜索
AWS 配置有bedrock-agentcorebedrock-agentcore-control、和 logs (CloudWatch) 权限的凭证

有关下载会话跨度的说明，请参阅按需评估入门。

关于示例

本页上的示例使用AgentCore 评估教程中的示例代理。该代理有两个工具 — calculator 和 weather —，部署在 AgentCore Runtime 上并启用了可观察性。

这些示例假设会话为两回合：

回合 1：“什么是 15 + 27？” — 代理使用该calculator工具并返回结果。
回合 2：“天气怎么样？” — 代理使用该weather工具并根据当前天气做出响应。

在运行评估之前，请调用您的代理并等待 2-5 分钟 CloudWatch 以获取遥测数据。

本页的示例中使用了以下常量。用你自己的价值观替换它们：


REGION       = "<region-code>"
AGENT_ID     = "my-agent-id"
SESSION_ID   = "my-session-id"
TRACE_ID_1   = "<trace-id-1>"   # Turn 1: "What is 15 + 27?"
TRACE_ID_2   = "<trace-id-2>"   # Turn 2: "What's the weather?"

正确性与预期的响应

Builtin.Correctness是一个跟踪级别的评估器，用于衡量代理的响应与预期答案相匹配的准确程度。当你提供时expectedResponse，评估人员会使用 LLM-as-a-Judge 评分将代理的实际反应与你的真实情况进行比较。

例

AgentCore SDK


from bedrock_agentcore.evaluation import EvaluationClient, ReferenceInputs

client = EvaluationClient(region_name=REGION)

# String form — matched against the last trace in the session
results = client.run(
    evaluator_ids=["Builtin.Correctness"],
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    reference_inputs=ReferenceInputs(
        expected_response="The weather is sunny",
    ),
)

for r in results:
    print(f"Trace: {r['context']['spanContext'].get('traceId', 'session')}")
    print(f"Score: {r['value']}, Label: {r['label']}")

要定位特定的轨迹，请以 dict 的expected_response形式传递，将跟踪 ID 映射到预期答案：


results = client.run(
    evaluator_ids=["Builtin.Correctness"],
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    reference_inputs=ReferenceInputs(
        expected_response={
            TRACE_ID_1: "15 + 27 = 42",
            TRACE_ID_2: "The weather is sunny",
        },
    ),
)

AgentCore CLI


# Expected response matched against the last trace
agentcore run eval \
  --agent AGENT_NAME \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.Correctness" \
  --expected-response "The weather is sunny"

# Target a specific trace
agentcore run eval \
  --agent AGENT_NAME \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.Correctness" \
  --trace-id TRACE_ID_1 \
  --expected-response "15 + 27 = 42"

# ARN mode — evaluate an agent outside the CLI project
agentcore run eval \
  --runtime-arn arn:aws:bedrock-agentcore:<region-code>:<account-id>:runtime/<agent-id> \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.Correctness" \
  --expected-response "The weather is sunny"

Starter Toolkit SDK


from bedrock_agentcore_starter_toolkit import Evaluation, ReferenceInputs

eval_client = Evaluation(region=REGION)

# String form — matched against the last trace
results = eval_client.run(
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    evaluators=["Builtin.Correctness"],
    reference_inputs=ReferenceInputs(
        expected_response="The weather is sunny",
    ),
)

for r in results.get_successful_results():
    print(f"Score: {r.value:.2f}, Label: {r.label}")

要定位特定的跟踪，请传递一个元组：(trace_id, expected_response)


results = eval_client.run(
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    evaluators=["Builtin.Correctness"],
    reference_inputs=ReferenceInputs(
        expected_response=(TRACE_ID_1, "15 + 27 = 42"),
    ),
)

Starter Toolkit CLI


# Expected response matched against the last trace
agentcore eval run \
  --agent-id AGENT_ID \
  --session-id SESSION_ID \
  --evaluator "Builtin.Correctness" \
  --expected-response "The weather is sunny"

# Target a specific trace
agentcore eval run \
  --agent-id AGENT_ID \
  --session-id SESSION_ID \
  --trace-id TRACE_ID_1 \
  --evaluator "Builtin.Correctness" \
  --expected-response "15 + 27 = 42"

# Save results to a file
agentcore eval run \
  --agent-id AGENT_ID \
  --session-id SESSION_ID \
  --evaluator "Builtin.Correctness" \
  --expected-response "The weather is sunny" \
  --output results.json

AWS SDK (boto3)


import boto3

client = boto3.client("bedrock-agentcore", region_name=REGION)

response = client.evaluate(
    evaluatorId="Builtin.Correctness",
    evaluationInput={"sessionSpans": session_spans_and_log_events},
    evaluationReferenceInputs=[
        {
            "context": {
                "spanContext": {
                    "sessionId": SESSION_ID,
                    "traceId": TRACE_ID_1
                }
            },
            "expectedResponse": {"text": "15 + 27 = 42"}
        },
        {
            "context": {
                "spanContext": {
                    "sessionId": SESSION_ID,
                    "traceId": TRACE_ID_2
                }
            },
            "expectedResponse": {"text": "The weather is sunny"}
        }
    ]
)

for result in response["evaluationResults"]:
    print(f"Score: {result['value']}, Label: {result['label']}")

GoalSuccessRate 带断言

Builtin.GoalSuccessRate是一个会话级别的评估器，用于验证代理的行为是否满足一组自然语言断言。断言可以检查整个对话中工具的使用情况、响应内容、操作顺序或任何其他可观察到的行为。

注意

以下示例使用验证工具使用情况的断言，但断言是自由形式的自然语言——您可以使用它们来断言代理行为的任何方面，例如响应语气、事实准确性、安全合规性或业务逻辑。

例

AgentCore SDK


from bedrock_agentcore.evaluation import EvaluationClient, ReferenceInputs

client = EvaluationClient(region_name=REGION)

results = client.run(
    evaluator_ids=["Builtin.GoalSuccessRate"],
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    reference_inputs=ReferenceInputs(
        assertions=[
            "Agent used the calculator tool to compute the result",
            "Agent returned the correct numerical answer of 42",
            "Agent used the weather tool when asked about weather",
        ],
    ),
)

for r in results:
    print(f"Score: {r['value']}, Label: {r['label']}")
    print(f"Explanation: {r['explanation'][:200]}")

AgentCore CLI


agentcore run eval \
  --agent AGENT_NAME \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate" \
  --assertion "Agent used the calculator tool to compute the result" \
  --assertion "Agent returned the correct numerical answer of 42" \
  --assertion "Agent used the weather tool when asked about weather"

# ARN mode — evaluate an agent outside the CLI project
agentcore run eval \
  --runtime-arn arn:aws:bedrock-agentcore:<region-code>:<account-id>:runtime/<agent-id> \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate" \
  --assertion "Agent used the calculator tool to compute the result" \
  --assertion "Agent returned the correct numerical answer of 42"

Starter Toolkit SDK


from bedrock_agentcore_starter_toolkit import Evaluation, ReferenceInputs

eval_client = Evaluation(region=REGION)

results = eval_client.run(
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    evaluators=["Builtin.GoalSuccessRate"],
    reference_inputs=ReferenceInputs(
        assertions=[
            "Agent used the calculator tool to compute the result",
            "Agent returned the correct numerical answer of 42",
            "Agent used the weather tool when asked about weather",
        ],
    ),
)

for r in results.get_successful_results():
    print(f"Score: {r.value:.2f}, Label: {r.label}")

Starter Toolkit CLI


agentcore eval run \
  --agent-id AGENT_ID \
  --session-id SESSION_ID \
  --evaluator "Builtin.GoalSuccessRate" \
  --assertion "Agent used the calculator tool to compute the result" \
  --assertion "Agent returned the correct numerical answer of 42" \
  --assertion "Agent used the weather tool when asked about weather"

AWS SDK (boto3)


import boto3

client = boto3.client("bedrock-agentcore", region_name=REGION)

response = client.evaluate(
    evaluatorId="Builtin.GoalSuccessRate",
    evaluationInput={"sessionSpans": session_spans_and_log_events},
    evaluationReferenceInputs=[
        {
            "context": {
                "spanContext": {
                    "sessionId": SESSION_ID
                }
            },
            "assertions": [
                {"text": "Agent used the calculator tool to compute the result"},
                {"text": "Agent returned the correct numerical answer of 42"},
                {"text": "Agent used the weather tool when asked about weather"}
            ]
        }
    ]
)

for result in response["evaluationResults"]:
    print(f"Score: {result['value']}, Label: {result['label']}")

轨迹与预期轨迹匹配

轨迹评估器将代理的实际工具调用顺序与预期的工具名称序列进行比较。有三种变体可供选择，每种变体都有不同的匹配严格度。这三个都是会话级别的评估者，使用编程评分（没有 LLM 调用，因此代币使用量为零）。

评估者	匹配规则	示例
`Builtin.TrajectoryExactOrderMatch`	实际必须完全符合预期 — 相同的工具、相同的订单、没有额外费用	预期：`[calculator, weather]`，实际：`[calculator, weather]`→ 通过。实际：`[calculator, weather, calculator]`→ 失败。
`Builtin.TrajectoryInOrderMatch`	预期的工具必须按顺序显示，但允许在它们之间使用额外的工具	预期：`[calculator, weather]`，实际：`[calculator, some_tool, weather]`→ 通过。
`Builtin.TrajectoryAnyOrderMatch`	所有预期的工具都必须存在，顺序无关紧要，允许额外使用	预期：`[calculator, weather]`，实际：`[weather, calculator]`→ 通过。

例

AgentCore SDK


from bedrock_agentcore.evaluation import EvaluationClient, ReferenceInputs

client = EvaluationClient(region_name=REGION)

results = client.run(
    evaluator_ids=[
        "Builtin.TrajectoryExactOrderMatch",
        "Builtin.TrajectoryInOrderMatch",
        "Builtin.TrajectoryAnyOrderMatch",
    ],
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    reference_inputs=ReferenceInputs(
        expected_trajectory=["calculator", "weather"],
    ),
)

for r in results:
    print(f"{r['evaluatorId']}: {r['value']} ({r['label']})")
    print(f"  {r['explanation'][:150]}")

AgentCore CLI

工具名称以逗号分隔的列表形式传递：


agentcore run eval \
  --agent AGENT_NAME \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryExactOrderMatch" \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryInOrderMatch" \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryAnyOrderMatch" \
  --expected-trajectory "calculator,weather"

# ARN mode — evaluate an agent outside the CLI project
agentcore run eval \
  --runtime-arn arn:aws:bedrock-agentcore:<region-code>:<account-id>:runtime/<agent-id> \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryExactOrderMatch" \
  --expected-trajectory "calculator,weather"

Starter Toolkit SDK


from bedrock_agentcore_starter_toolkit import Evaluation, ReferenceInputs

eval_client = Evaluation(region=REGION)

results = eval_client.run(
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    evaluators=[
        "Builtin.TrajectoryExactOrderMatch",
        "Builtin.TrajectoryInOrderMatch",
        "Builtin.TrajectoryAnyOrderMatch",
    ],
    reference_inputs=ReferenceInputs(
        expected_trajectory=["calculator", "weather"],
    ),
)

for r in results.get_successful_results():
    print(f"{r.evaluator_name}: {r.value:.2f} ({r.label})")

Starter Toolkit CLI

工具名称以逗号分隔的列表形式传递：


agentcore eval run \
  --agent-id AGENT_ID \
  --session-id SESSION_ID \
  --evaluator "Builtin.TrajectoryExactOrderMatch" \
  --evaluator "Builtin.TrajectoryInOrderMatch" \
  --evaluator "Builtin.TrajectoryAnyOrderMatch" \
  --expected-trajectory "calculator,weather"

AWS SDK (boto3)


import boto3

client = boto3.client("bedrock-agentcore", region_name=REGION)

for evaluator in [
    "Builtin.TrajectoryExactOrderMatch",
    "Builtin.TrajectoryInOrderMatch",
    "Builtin.TrajectoryAnyOrderMatch",
]:
    response = client.evaluate(
        evaluatorId=evaluator,
        evaluationInput={"sessionSpans": session_spans_and_log_events},
        evaluationReferenceInputs=[
            {
                "context": {
                    "spanContext": {
                        "sessionId": SESSION_ID
                    }
                },
                "expectedTrajectory": {
                    "toolNames": ["calculator", "weather"]
                }
            }
        ]
    )

    for result in response["evaluationResults"]:
        print(f"{result['evaluatorId']}: {result['value']} ({result['label']})")

将所有基本真相字段合并到一个请求中

你可以在一次评估调用中将所有地面真值字段一起传递。该服务会将每个字段路由到相应的赋值器，并忽略给定赋值器未使用的字段。这意味着您只需构造一次参考输入，即可在不同的赋值器中重复使用这些输入，而无需修改有效载荷。

例

AgentCore SDK


from bedrock_agentcore.evaluation import EvaluationClient, ReferenceInputs

client = EvaluationClient(region_name=REGION)

results = client.run(
    evaluator_ids=[
        "Builtin.Correctness",
        "Builtin.GoalSuccessRate",
        "Builtin.TrajectoryExactOrderMatch",
        "Builtin.TrajectoryInOrderMatch",
        "Builtin.TrajectoryAnyOrderMatch",
    ],
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    reference_inputs=ReferenceInputs(
        expected_response="The weather is sunny",
        assertions=[
            "Agent used the calculator tool for math",
            "Agent used the weather tool when asked about weather",
        ],
        expected_trajectory=["calculator", "weather"],
    ),
)

for r in results:
    ignored = r.get("ignoredReferenceInputFields", [])
    print(f"{r['evaluatorId']}: {r['value']} ({r['label']})")
    if ignored:
        print(f"  Ignored fields: {ignored}")

AgentCore CLI


agentcore run eval \
  --agent AGENT_NAME \
  --session-id SESSION_ID \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.Correctness" \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate" \
  --evaluator-arn "arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryExactOrderMatch" \
  --assertion "Agent used the calculator tool for math" \
  --assertion "Agent used the weather tool when asked about weather" \
  --expected-trajectory "calculator,weather" \
  --expected-response "The weather is sunny" \
  --output results.json

Starter Toolkit SDK


from bedrock_agentcore_starter_toolkit import Evaluation, ReferenceInputs

eval_client = Evaluation(region=REGION)

results = eval_client.run(
    agent_id=AGENT_ID,
    session_id=SESSION_ID,
    evaluators=[
        "Builtin.Correctness",
        "Builtin.GoalSuccessRate",
        "Builtin.TrajectoryExactOrderMatch",
        "Builtin.TrajectoryInOrderMatch",
        "Builtin.TrajectoryAnyOrderMatch",
    ],
    reference_inputs=ReferenceInputs(
        expected_response="The weather is sunny",
        assertions=[
            "Agent used the calculator tool for math",
            "Agent used the weather tool when asked about weather",
        ],
        expected_trajectory=["calculator", "weather"],
    ),
)

for r in results.get_successful_results():
    print(f"{r.evaluator_name}: {r.value:.2f} ({r.label})")

AWS SDK (boto3)


import boto3

client = boto3.client("bedrock-agentcore", region_name=REGION)

reference_inputs = [
    {
        "context": {
            "spanContext": {"sessionId": SESSION_ID}
        },
        "assertions": [
            {"text": "Agent used the calculator tool for math"},
            {"text": "Agent used the weather tool when asked about weather"}
        ],
        "expectedTrajectory": {
            "toolNames": ["calculator", "weather"]
        }
    },
    {
        "context": {
            "spanContext": {
                "sessionId": SESSION_ID,
                "traceId": TRACE_ID_2
            }
        },
        "expectedResponse": {"text": "The weather is sunny"}
    }
]

for evaluator in ["Builtin.Correctness", "Builtin.GoalSuccessRate",
                   "Builtin.TrajectoryExactOrderMatch"]:
    response = client.evaluate(
        evaluatorId=evaluator,
        evaluationInput={"sessionSpans": session_spans_and_log_events},
        evaluationReferenceInputs=reference_inputs
    )
    for result in response["evaluationResults"]:
        ignored = result.get("ignoredReferenceInputFields", [])
        print(f"{result['evaluatorId']}: {result['value']} ({result['label']})")
        if ignored:
            print(f"  Ignored fields: {ignored}")

了解被忽略的参考输入字段

当您提供评估者不使用的基本真相字段时，响应中会包含一个ignoredReferenceInputFields列出未使用字段的数组。这是信息性的，不是错误——评估仍然成功完成。

例如，如果您使用 provided 调用Builtin.Helpfulness，expectedResponse则评估器会忽略基本真相（Helpfulness 不使用它）并返回：


{
  "evaluatorId": "Builtin.Helpfulness",
  "value": 0.83,
  "label": "Very Helpful",
  "explanation": "...",
  "ignoredReferenceInputFields": ["expectedResponse"]
}

这种行为是设计使然，它允许您构造一组参考输入，并在多个赋值器中使用它们，而无需调整每个赋值器的有效负载。

自定义评估器中的基本真相

自定义赋值者可以在评估指令中通过占位符使用基本真值字段。创建自定义赋值器时，可以引用以下占位符：

Session-level 自定义赋值器：{context}、{available_tools}、{actual_tool_trajectory}、{expected_tool_trajectory} {assertions}
Trace-level 自定义赋值器：{context}、、{assistant_turn} {expected_response}

例如，用于检查响应相似性的自定义跟踪级别评估器可以使用：


Compare the agent's response with the expected response.
Agent response: {assistant_turn}
Expected response: {expected_response}
Rate how closely the agent's response matches the expected response on a scale of 0 to 1.

当在参考输入expectedResponse中使用此赋值器调用该赋值器时，服务会在得分之前用实际的真实值替换占位符。

有关创建自定义赋值器的详细信息，请参阅自定义赋值器。

注意

使用真实情况占位符（{assertions}、{expected_response}、{expected_tool_trajectory}）的自定义评估器不能用于在线评估配置，因为在线评估在没有地面实况值的情况下会监控实时制作流量。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

按需评估入门

了解输入跨度