View a markdown version of this page

Avaliações da verdade básica - Amazon Bedrock AgentCore

Avaliações da verdade básica

A verdade fundamental é a resposta correta conhecida ou o comportamento esperado de uma determinada entrada — o “padrão-ouro” com o qual você compara os resultados reais. Para avaliação de agentes, a verdade fundamental transforma a avaliação subjetiva da qualidade em medição objetiva, permitindo a detecção de regressão, conjuntos de dados de referência e exatidão específica do domínio que os avaliadores genéricos não podem fornecer sozinhos.

Com as avaliações verdadeiras básicas, você fornece entradas de referência junto com os períodos de sua sessão ao chamar a API Evaluate. O serviço usa essas entradas de referência para avaliar o comportamento real do seu agente em relação ao comportamento esperado. Os avaliadores que não usam um determinado campo de verdade fundamental o ignoram e relatam quais campos não foram usados na resposta.

Avaliadores integrados apoiados e campos de verdade fundamentais

A tabela a seguir mostra quais avaliadores integrados apoiam a verdade fundamental e quais campos eles usam.

Avaliador Nível Campo da verdade fundamental Description

Builtin.Correctness

Traço

expectedResponse

Mede a precisão com que a resposta do agente corresponde à resposta esperada. Usa LLM-as-a-Judge pontuação.

Builtin.GoalSuccessRate

Sessão

assertions

Valida se o comportamento do agente satisfaz as afirmações de linguagem natural durante toda a sessão. Usa LLM-as-a-Judge pontuação.

Builtin.TrajectoryExactOrderMatch

Sessão

expectedTrajectory

Verifica se a sequência real de chamadas da ferramenta corresponde exatamente à sequência esperada — mesmas ferramentas, mesma ordem, sem extras. Pontuação programática (sem chamadas de LLM).

Builtin.TrajectoryInOrderMatch

Sessão

expectedTrajectory

Verifica se todas as ferramentas esperadas aparecem em ordem na sequência real, mas permite ferramentas extras entre elas. Pontuação programática.

Builtin.TrajectoryAnyOrderMatch

Sessão

expectedTrajectory

Verifica se todas as ferramentas esperadas estão presentes na sequência real, independentemente da ordem. Ferramentas extras são permitidas. Pontuação programática.

nota

Avaliadores personalizados também oferecem suporte a campos de verdade básica por meio de espaços reservados em suas instruções de avaliação. Consulte Ground truth em avaliadores personalizados para obter detalhes.

A tabela a seguir descreve os campos de verdade básica.

Campo Tipo Escopo Description

expectedResponse

String

Traço

A resposta esperada do agente para um turno específico. Com escopo definido para um rastreamento usado traceId no contexto de entrada de referência.

assertions

Lista de strings

Sessão

Declarações em linguagem natural que devem ser verdadeiras sobre o comportamento do agente durante a sessão.

expectedTrajectory

Lista de nomes de ferramentas

Sessão

A sequência esperada de chamadas de ferramentas para a sessão.

  • Os campos de verdade básica são opcionais. Se você os omitir, os avaliadores retornarão ao modo livre de verdades (por exemplo, Builtin.Correctness ainda funciona sem elesexpectedResponse, ele apenas avalia com base apenas no contexto).

  • Você pode fornecer todos os campos de verdade básica em uma única solicitação. O serviço seleciona os campos relevantes para cada avaliador e relata ignoredReferenceInputFields na resposta todos os campos que não foram usados.

  • Você não precisa fornecer todos expectedResponse os vestígios. Traços sem verdade fundamental são avaliados usando a variante sem verdade fundamental do avaliador.

Pré-requisitos

Para obter instruções sobre como baixar períodos de sessão, consulte Introdução à avaliação sob demanda.

Sobre os exemplos

Os exemplos nesta página usam o agente de amostra dos tutoriais de AgentCore avaliações. O agente tem duas ferramentas — calculator e weather — e é implantado no AgentCore Runtime com a observabilidade ativada.

Os exemplos pressupõem uma sessão de dois turnos:

  1. Turno 1: “Quanto é 15 + 27?” — o agente usa a calculator ferramenta e responde com o resultado.

  2. Turno 2: “Qual é o clima?” — o agente usa a weather ferramenta e responde com o clima atual.

Antes de realizar as avaliações, chame seu agente e aguarde de 2 a 5 minutos para CloudWatch ingerir os dados de telemetria.

As constantes a seguir são usadas nos exemplos desta página. Substitua-os por seus próprios valores:

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?"

Exatidão com a resposta esperada

Builtin.Correctnessé um avaliador em nível de rastreamento que mede a precisão com que a resposta do agente corresponde à resposta esperada. Quando você forneceexpectedResponse, o avaliador compara a resposta real do agente com sua verdade básica usando LLM-as-a-Judge a pontuação.

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

    Para direcionar um rastreamento específico, passe expected_response como um dicionário mapeando IDs de rastreamento para as respostas esperadas:

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

    Para direcionar um rastreamento específico, passe uma tupla de(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 com afirmações

Builtin.GoalSuccessRateé um avaliador em nível de sessão que valida se o comportamento do agente satisfaz um conjunto de afirmações de linguagem natural. As afirmações podem verificar o uso da ferramenta, o conteúdo da resposta, a ordem das ações ou qualquer outro comportamento observável em toda a conversa.

nota

Os exemplos abaixo usam afirmações que validam o uso da ferramenta, mas as afirmações são uma linguagem natural de formato livre — você pode usá-las para afirmar qualquer aspecto do comportamento do agente, como tom de resposta, precisão factual, conformidade de segurança ou lógica comercial.

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

Correspondência de trajetória com a trajetória esperada

Os avaliadores de trajetória comparam a sequência real de chamadas da ferramenta do agente com uma sequência esperada de nomes de ferramentas. Três variantes estão disponíveis, cada uma com um rigor de combinação diferente. Todos os três são avaliadores em nível de sessão e usam pontuação programática (sem chamadas de LLM, então o uso do token é zero).

Avaliador Regra de correspondência Exemplo

Builtin.TrajectoryExactOrderMatch

O real deve corresponder exatamente ao esperado — mesmas ferramentas, mesmo pedido, sem extras

Esperado:[calculator, weather], Real: [calculator, weather] → Passe. Real: [calculator, weather, calculator] → Falha.

Builtin.TrajectoryInOrderMatch

As ferramentas esperadas devem aparecer em ordem, mas ferramentas extras são permitidas entre elas

Esperado:[calculator, weather], Real: [calculator, some_tool, weather] → Passe.

Builtin.TrajectoryAnyOrderMatch

Todas as ferramentas esperadas devem estar presentes, o pedido não importa, extras são permitidos

Esperado:[calculator, weather], Real: [weather, calculator] → Passe.

exemplo
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. Os nomes das ferramentas são passados como uma lista separada por vírgulas:

    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. Os nomes das ferramentas são passados como uma lista separada por vírgulas:

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

Combinando todos os campos de verdade básica em uma única solicitação

Você pode reunir todos os campos da verdade básica em uma única chamada de avaliação. O serviço encaminha cada campo para o avaliador apropriado e ignora os campos que um determinado avaliador não usa. Isso significa que você pode criar suas entradas de referência uma vez e reutilizá-las em diferentes avaliadores sem modificar a carga útil.

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

Compreendendo os campos de entrada de referência ignorados

Quando você fornece campos de verdade básica que um avaliador não usa, a resposta inclui uma ignoredReferenceInputFields matriz listando os campos não usados. Isso é informativo, não um erro — a avaliação ainda é concluída com êxito.

Por exemplo, se você ligar Builtin.Helpfulness com expectedResponse provided, o avaliador ignora a verdade básica (a Helpfulness não a usa) e retorna:

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

Esse comportamento é intencional: ele permite que você construa um único conjunto de entradas de referência e as use em vários avaliadores sem ajustar a carga útil de cada um.

Verdade fundamental em avaliadores personalizados

Avaliadores personalizados podem usar campos de verdade básica por meio de espaços reservados em suas instruções de avaliação. Ao criar um avaliador personalizado, você pode fazer referência aos seguintes espaços reservados:

  • Session-level avaliadores personalizados:{context},,{available_tools},{actual_tool_trajectory}, {expected_tool_trajectory} {assertions}

  • Trace-level avaliadores personalizados:{context},, {assistant_turn} {expected_response}

Por exemplo, um avaliador personalizado em nível de rastreamento que verifica a similaridade da resposta pode usar:

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.

Quando esse avaliador é chamado com as entradas expectedResponse de referência, o serviço substitui o espaço reservado pelo valor real da verdade fundamental antes da pontuação.

Para obter detalhes sobre a criação de avaliadores personalizados, consulte Avaliadores personalizados.

nota

Avaliadores personalizados que usam espaços reservados de verdade básica ({assertions},{expected_response},{expected_tool_trajectory}) não podem ser usados em configurações de avaliação on-line, porque as avaliações on-line monitoram o tráfego de produção ao vivo onde os valores de verdade básica não estão disponíveis.