View a markdown version of this page

Ground Truth の評価 - Amazon Bedrock AgentCore

Ground Truth の評価

グラウンドトゥルースは、特定の入力に対する既知の正しい回答または予想される動作です。実際の結果を比較する「ゴールドスタンダード」です。エージェント評価の場合、グラウンドトゥルースは主観的な品質評価を目的の測定に変換し、回帰検出、ベンチマークデータセット、および一般的な評価者が独自に提供できないドメイン固有の正確性を可能にします。

グラウンドトゥルース評価では、Evaluate API を呼び出すときに、セッションスパンとともにリファレンス入力を提供します。このサービスは、これらのリファレンス入力を使用して、予想される動作に対するエージェントの実際の動作をスコアリングします。特定のグラウンドトゥルースフィールドを使用しない評価者はそれを無視し、レスポンスで使用されなかったフィールドを報告します。

サポートされている組み込み評価者とグラウンドトゥルースフィールド

次の表は、グラウンドトゥルースをサポートする組み込み評価者と、それらが使用するフィールドを示しています。

評価者 レベル 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

順序に関係なく、予想されるすべてのツールが実際のシーケンスに存在することを確認します。追加のツールを使用できます。プログラムによるスコアリング。

注記

カスタム評価者は、評価手順のプレースホルダーを通じてグラウンドトゥルースフィールドもサポートしています。詳細については、「カスタム評価者のグラウンドトゥルース」を参照してください。

次の表に、グラウンドトゥルースフィールドを示します。

フィールド タイプ スコープ 説明

expectedResponse

文字列

トレース

特定のターンで予想されるエージェントのレスポンス。参照入力コンテキストtraceIdで を使用してトレースにスコープされます。

assertions

文字列のリスト

Session

セッション全体のエージェントの動作について当てはまる自然言語ステートメント。

expectedTrajectory

ツール名のリスト

Session

セッションのツール呼び出しの予想されるシーケンス。

  • Ground Truth フィールドはオプションです。これらを省略すると、評価者はグラウンドトゥルースフリーモードに戻ります (たとえば、 Builtin.Correctness がなくても機能しexpectedResponse、コンテキストのみに基づいて評価されます)。

  • すべてのグラウンドトゥルースフィールドを 1 回のリクエストで指定できます。サービスは各評価者の関連フィールドを選択し、使用されなかったフィールドのレスポンスignoredReferenceInputFieldsでレポートします。

  • トレースexpectedResponseごとに を指定する必要はありません。グラウンドトゥルースのないトレースは、評価者のグラウンドトゥルースフリーバリアントを使用して評価されます。

前提条件

  • Python 3.10 以降

  • オブザーバビリティが有効になっている AgentCore ランタイムにデプロイされたエージェント、または AgentCore オブザーバビリティ で設定されたサポートされているフレームワークで構築されたエージェント。サポートされているフレームワーク:

    • Strands Agents

    • opentelemetry-instrumentation-langchain または を使用した LangGraph openinference-instrumentation-langchain

  • CloudWatch でトランザクション検索を有効にする — 「トランザクション検索を有効にする」を参照してください。

  • AWS 、、および logs (CloudWatch) bedrock-agentcore-control のアクセス許可で設定された bedrock-agentcore 認証情報

セッションスパンのダウンロード手順については、「オンデマンド評価の開始方法」を参照してください。

の例について

このページの例では、AgentCore Evaluations チュートリアル のサンプルエージェントを使用しています。エージェントには calculatorweatherの 2 つのツールがあり、オブザーバビリティを有効にして AgentCore ランタイムにデプロイされます。

この例では、2 ターンセッションを想定しています。

  1. ターン 1: 「15 + 27 とは」 — エージェントはcalculatorツールを使用し、結果で応答します。

  2. ターン 2: 「天気は?」 — エージェントはweatherツールを使用し、現在の天気で応答します。

評価を実行する前に、エージェントを呼び出し、CloudWatch がテレメトリデータを取り込むまで 2~5 分待ちます。

このページの例全体で、次の定数が使用されます。それらを独自の値に置き換えます。

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

    特定のトレースをターゲットにするには、予想される回答にトレース IDs をディクトマッピングexpected_responseとして渡します。

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

予想される軌道との軌道マッチング

軌道評価者は、エージェントの実際のツール呼び出しシーケンスと予想されるツール名のシーケンスを比較します。3 つのバリアントが利用可能で、それぞれが厳密さが異なります。これら 3 つはすべてセッションレベルの評価者であり、プログラムによるスコアリングを使用します (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
  1. 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
  1. ツール名はカンマ区切りのリストとして渡されます。

    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
  1. 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
  1. ツール名はカンマ区切りのリストとして渡されます。

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

すべてのグラウンドトゥルースフィールドを 1 つのリクエストに結合する

すべてのグラウンドトゥルースフィールドを 1 回の評価呼び出しで渡すことができます。サービスは各フィールドを適切な評価者にルーティングし、特定の評価者が使用しないフィールドを無視します。つまり、リファレンス入力を一度構築し、ペイロードを変更せずに異なる評価者間で再利用できます。

AgentCore SDK
  1. 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
  1. 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
  1. 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)
  1. 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配列が含まれます。これはエラーではなく情報であり、評価は正常に完了します。

たとえば、 expectedResponse Builtin.Helpfulnessを指定して を呼び出すと、評価者はグラウンドトゥルースを無視し (ヘルプネスでは使用されません)、以下を返します。

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

この動作は設計上行われます。これにより、参照入力の 1 つのセットを構築し、それぞれのペイロードを調整することなく複数の評価者で使用できます。

カスタム評価者のグラウンドトゥルース

カスタム評価者は、評価手順でプレースホルダーを介してグラウンドトゥルースフィールドを使用できます。カスタムエバリュエーターを作成するときは、次のプレースホルダーを参照できます。

  • セッションレベルのカスタム評価者: {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で と呼び出されると、サービスはスコアリング前にプレースホルダーを実際のグラウンドトゥルース値に置き換えます。

カスタム評価者の作成の詳細については、「カスタム評価者」を参照してください。

注記

グラウンドトゥルースプレースホルダー ({assertions}、、) {expected_tool_trajectory} を使用するカスタム評価者は{expected_response}、オンライン評価設定では使用できません。オンライン評価では、グラウンドトゥルース値が利用できない本番環境のトラフィックがモニタリングされるためです。