支援的內建評估器和 Ground Truth 欄位先決條件預期回應的正確性 GoalSuccessRate 與聲明與預期軌跡相符的軌跡在一個請求中結合所有基本事實欄位了解忽略的參考輸入欄位自訂評估器中的 Ground Truth

Ground Truth 評估

Ground Truth 是指定輸入已知的正確答案或預期行為 — 您比較實際結果的「黃金標準」。對於代理程式評估， Ground Truth 會將主觀品質評估轉換為目標測量，啟用一般評估者無法自行提供的迴歸偵測、基準資料集和網域特定正確性。

透過 Ground Truth 評估，您可以在呼叫評估 API 時，在工作階段範圍之外提供參考輸入。該服務使用這些參考輸入，根據預期的行為對代理程式的實際行為進行評分。不使用特定 Ground Truth 欄位的評估者會忽略該欄位，並報告回應中未使用哪些欄位。

支援的內建評估器和 Ground Truth 欄位

下表顯示哪些內建評估器支援 Ground Truth 及其使用的欄位。

評估者	Level	Ground Truth 欄位	說明
`Builtin.Correctness`	追蹤	`expectedResponse`	測量客服人員的回應符合預期答案的準確度。使用 LLM-as-a-Judge 評分。
`Builtin.GoalSuccessRate`	Session (工作階段)	`assertions`	驗證客服人員的行為在整個工作階段中是否符合自然語言聲明。使用 LLM-as-a-Judge 評分。
`Builtin.TrajectoryExactOrderMatch`	Session (工作階段)	`expectedTrajectory`	檢查實際工具呼叫序列是否完全符合預期的序列 - 相同的工具、相同的順序、沒有額外的項目。程式設計評分（無 LLM 呼叫）。
`Builtin.TrajectoryInOrderMatch`	Session (工作階段)	`expectedTrajectory`	檢查所有預期工具是否在實際序列中按順序出現，但允許它們之間使用額外的工具。程式設計評分。
`Builtin.TrajectoryAnyOrderMatch`	Session (工作階段)	`expectedTrajectory`	檢查所有預期工具是否出現在實際序列中，無論順序為何。允許額外的工具。程式設計評分。

注意

自訂評估者也會在評估指示中透過預留位置支援 Ground Truth 欄位。如需詳細資訊，請參閱自訂評估器中的 Ground Truth。

下表說明 Ground Truth 欄位。

欄位	Type	Scope (範圍)	Description
`expectedResponse`	String	追蹤	特定回合的預期客服人員回應。在參考輸入內容`traceId`中使用範圍為追蹤。
`assertions`	字串清單	Session (工作階段)	關於客服人員在整個工作階段中的行為，應該是正確的自然語言陳述式。
`expectedTrajectory`	工具名稱清單	Session (工作階段)	工作階段所需的工具呼叫順序。

Ground Truth 欄位為選用。如果您省略它們，評估者會回到其基本的無事實模式（例如，在沒有 expectedResponse 的情況下Builtin.Correctness仍然有效，它只是僅根據內容進行評估）。
您可以在單一請求中提供所有 Ground Truth 欄位。服務會為每個評估者挑選相關欄位，並在回應ignoredReferenceInputFields中報告任何未使用的欄位。
您不需要expectedResponse為每個追蹤提供。沒有 Ground Truth 的追蹤會使用評估器的 Ground Truth-free 變體進行評估。

先決條件

Python 3.10+
在啟用可觀測性的 AgentCore 執行期上部署的代理程式，或使用 AgentCore 可觀測性設定的支援架構建置的代理程式。支援的架構：
- Strands 代理程式
- 使用 opentelemetry-instrumentation-langchain或的 LangGraph openinference-instrumentation-langchain
CloudWatch 中啟用的交易搜尋 — 請參閱啟用交易搜尋
AWS 使用、 bedrock-agentcore-control 和 bedrock-agentcore logs(CloudWatch) 許可設定的憑證

如需下載工作階段範圍的指示，請參閱隨需評估入門。

關於範例

本頁面上的範例使用 AgentCore Evaluations 教學課程中的範例代理程式。代理程式有兩個工具 — calculator和 weather — 並在啟用可觀測性的 AgentCore 執行時間上部署。

這些範例假設兩圈的工作階段：

轉 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']}")

若要以特定追蹤為目標，請將 expected_response做為方向映射追蹤 IDs傳遞至預期的答案：


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']})")

在一個請求中結合所有基本事實欄位

您可以在單一評估呼叫中將所有 Ground Truth 欄位一起傳遞。服務會將每個欄位路由至適當的評估者，並忽略指定評估者不使用的欄位。這表示您可以建構參考輸入一次，並在不同的評估器之間重複使用它們，而無需修改承載。

範例

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}")

了解忽略的參考輸入欄位

當您提供評估者不使用的 Ground Truth 欄位時，回應會包含列出未使用欄位的ignoredReferenceInputFields陣列。這是資訊性的，而不是錯誤 — 評估仍然成功完成。

例如，如果您Builtin.Helpfulness使用 expectedResponse 提供的呼叫，評估器會忽略基本事實 (Helpfulness 不使用它），並傳回：


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

此行為是設計：它可讓您建構一組參考輸入，並在多個評估器之間使用它們，而不需要調整每個參考輸入的承載。

自訂評估器中的 Ground Truth

自訂評估者可以透過評估指示中的預留位置使用 Ground Truth 欄位。建立自訂評估器時，您可以參考下列預留位置：

工作階段層級自訂評估器：{context}、{available_tools}、{actual_tool_trajectory}、{expected_tool_trajectory}、 {assertions}
追蹤層級自訂評估器：{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中使用呼叫此評估器時，服務會在評分之前以實際的 Ground Truth 值取代預留位置。

如需建立自訂評估器的詳細資訊，請參閱自訂評估器。

注意

使用 Ground Truth 預留位置 ({assertions}{expected_response}、、) {expected_tool_trajectory} 的自訂評估器無法用於線上評估組態，因為線上評估會監控無法使用 Ground Truth 值的即時生產流量。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

隨需評估入門

了解輸入範圍