View a markdown version of this page

Avaliações de verdades fundamentais - Base da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Avaliações de verdades fundamentais

A verdade fundamental é a resposta correta conhecida ou o comportamento esperado para uma determinada entrada — o “padrão-ouro” com o qual você compara os resultados reais. Para a 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 correção específica do domínio que os avaliadores genéricos não podem fornecer sozinhos.

Com 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 campo de verdade fundamental específico o ignoram e relatam quais campos não foram usados na resposta.

Avaliadores integrados suportados e campos de verdade fundamentais

A tabela a seguir mostra quais avaliadores integrados apoiam a verdade básica e quais campos eles usam.

Avaliador Nível Campo de verdade fundamental Description

Builtin.Correctness

Rastrear

expectedResponse

Mede a precisão com que a resposta do agente corresponde à resposta esperada. Usa a 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 a 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 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

Os 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 in custom valuators para obter detalhes.

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

Campo Tipo Escopo Description

expectedResponse

String

Rastrear

A resposta esperada do agente para um turno específico. Escopo 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ásicos são opcionais. Se você os omitir, os avaliadores retornarão ao modo básico livre de verdade (por exemplo, Builtin.Correctness ainda funciona sem expectedResponse eles, 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 escolhe 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 rastros. Traços sem verdade fundamental são avaliados usando a variante sem verdade básica do avaliador.

Pré-requisitos

  • Python 3.10 ou superior

  • Um agente criado com uma estrutura compatível e uma biblioteca de instrumentação. Para obter mais informações sobre estruturas compatíveis e bibliotecas de instrumentação, consulte Estruturas de agentes suportadas.

  • Um agente implantado no AgentCore Runtime com a observabilidade ativada ou um agente criado com uma estrutura compatível configurada com o AgentCore Observability, incluindo a Pesquisa de Transações. Para obter mais informações sobre a configuração de telemetria, consulte Configuração e entrega de telemetria.

  • AWS credenciais configuradas com permissões parabedrock-agentcore,bedrock-agentcore-control, e logs () CloudWatch

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: “O que é 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 executar 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 a uma 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 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 \ --runtime AGENT_NAME \ --session-id SESSION_ID \ --evaluator Builtin.Correctness \ --expected-response "The weather is sunny" # Target a specific trace agentcore run eval \ --runtime AGENT_NAME \ --session-id SESSION_ID \ --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> \ --region <region-code> \ --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"), ), )
AgentCore CLI
  1. # Expected response matched against the last trace agentcore run eval \ --runtime-arn AGENT_RUNTIME_ARN \ --region REGION \ --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 \ --runtime-arn AGENT_RUNTIME_ARN \ --region REGION \ --session-id SESSION_ID \ --trace-id TRACE_ID_1 \ --evaluator-arn arn:aws:bedrock-agentcore:::evaluator/Builtin.Correctness \ --expected-response "15 + 27 = 42" # Save results to a file agentcore run eval \ --runtime-arn AGENT_RUNTIME_ARN \ --region REGION \ --session-id SESSION_ID \ --evaluator-arn arn:aws:bedrock-agentcore:::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 sobre qualquer aspecto do comportamento do agente, como tom de resposta, precisão factual, conformidade de segurança ou lógica de negócios.

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 \ --runtime AGENT_NAME \ --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" # 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> \ --region <region-code> \ --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}")
AgentCore CLI
  1. agentcore run eval \ --runtime-arn AGENT_RUNTIME_ARN \ --region REGION \ --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"
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 de ferramentas do agente com uma sequência esperada de nomes de ferramentas. Três variantes estão disponíveis, cada uma com um rigor de correspondência diferente. Todos os três são avaliadores em nível de sessão e usam pontuação programática (sem chamadas LLM, portanto, 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], Atual: [calculator, weather] → Passe. Atual: [calculator, weather, calculator] → Falha.

Builtin.TrajectoryInOrderMatch

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

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

Builtin.TrajectoryAnyOrderMatch

Todas as ferramentas esperadas devem estar presentes, a ordem não importa, os extras são permitidos

Esperado:[calculator, weather], Atual: [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 \ --runtime AGENT_NAME \ --session-id SESSION_ID \ --evaluator Builtin.TrajectoryExactOrderMatch Builtin.TrajectoryInOrderMatch 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> \ --region <region-code> \ --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})")
AgentCore CLI
  1. Os nomes das ferramentas são passados como uma lista separada por vírgulas:

    agentcore run eval \ --runtime-arn AGENT_RUNTIME_ARN \ --region REGION \ --session-id SESSION_ID \ --evaluator-arn arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryExactOrderMatch arn:aws:bedrock-agentcore:::evaluator/Builtin.TrajectoryInOrderMatch arn:aws:bedrock-agentcore:::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 da verdade básica em uma 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 construir 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 \ --runtime AGENT_NAME \ --session-id SESSION_ID \ --evaluator Builtin.Correctness Builtin.GoalSuccessRate 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 reais que um avaliador não usa, a resposta inclui uma ignoredReferenceInputFields matriz listando os campos não utilizados. 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

Os 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 das respostas 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 expectedResponse nas entradas 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 para 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 da verdade básica não estão disponíveis.