View a markdown version of this page

Evaluaciones de verdad sobre el terreno - Base amazónica AgentCore

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Evaluaciones de verdad sobre el terreno

La verdad básica es la respuesta correcta conocida o el comportamiento esperado para una entrada determinada: el «estándar de referencia» con el que se comparan los resultados reales. En el caso de la evaluación de los agentes, la verdad básica transforma la evaluación subjetiva de la calidad en una medición objetiva, lo que permite detectar la regresión, comparar conjuntos de datos y obtener una precisión específica del dominio que los evaluadores genéricos no pueden proporcionar por sí solos.

Con las evaluaciones de Ground Truth, al llamar a la API Evaluate, usted proporciona datos de referencia junto con la duración de las sesiones. El servicio utiliza estas entradas de referencia para comparar el comportamiento real de su agente con el comportamiento esperado. Los evaluadores que no usan un campo de verdad fundamental en particular lo ignoran e informan qué campos no se usaron en la respuesta.

Apoyó a los evaluadores integrados y a los campos básicos de la verdad.

La siguiente tabla muestra qué evaluadores integrados respaldan la verdad básica y qué campos utilizan.

Evaluador Nivel Campo de verdad fundamental Description (Descripción)

Builtin.Correctness

Rastreo

expectedResponse

Mide la precisión con la que la respuesta del agente coincide con la respuesta esperada. Usa la LLM-as-a-Judge puntuación.

Builtin.GoalSuccessRate

Session

assertions

Valida si el comportamiento del agente satisface las afirmaciones en lenguaje natural durante toda la sesión. Utiliza la puntuación. LLM-as-a-Judge

Builtin.TrajectoryExactOrderMatch

Session

expectedTrajectory

Comprueba que la secuencia real de llamadas a la herramienta coincide exactamente con la secuencia esperada: las mismas herramientas, el mismo orden, sin extras. Puntuación programática (sin llamadas de LLM).

Builtin.TrajectoryInOrderMatch

Session

expectedTrajectory

Comprueba que todas las herramientas esperadas aparezcan en orden dentro de la secuencia real, pero permite añadir más herramientas entre ellas. Puntuación programática.

Builtin.TrajectoryAnyOrderMatch

Session

expectedTrajectory

Comprueba que todas las herramientas esperadas estén presentes en la secuencia real, independientemente del orden. Se permiten herramientas adicionales. Puntuación programática.

nota

Los evaluadores personalizados también admiten campos de verdad básica mediante marcadores de posición en sus instrucciones de evaluación. Para obtener más información, consulta Ground Truth en los evaluadores personalizados.

En la siguiente tabla se describen los campos de Ground Truth.

Campo Tipo Alcance Description (Descripción)

expectedResponse

Cadena

Rastreo

La respuesta esperada del agente para un turno específico. Se refiere a un seguimiento que se utiliza traceId en el contexto de entrada de referencia.

assertions

Lista de cadenas

Session

Declaraciones en lenguaje natural que deberían ser ciertas sobre el comportamiento del agente durante la sesión.

expectedTrajectory

Lista de nombres de herramientas

Session

La secuencia esperada de llamadas a las herramientas para la sesión.

  • Los campos de información básica son opcionales. Si los omites, los evaluadores vuelven a su modo básico sin la verdad (por ejemplo, Builtin.Correctness todavía funciona sin expectedResponse ellos, solo evalúa basándose únicamente en el contexto).

  • Puede proporcionar todos los campos de veracidad básicos en una sola solicitud. El servicio selecciona los campos pertinentes para cada evaluador e informa ignoredReferenceInputFields en la respuesta de los campos que no se utilizaron.

  • No es necesario que proporciones todos expectedResponse los rastros. Las trazas sin veracidad fundamental se evalúan utilizando la variante del evaluador sin veracidad fundamental.

Requisitos previos

  • Python 3.10+

  • Un agente creado con un marco y una biblioteca de instrumentación compatibles. Para obtener más información sobre los marcos y bibliotecas de instrumentación compatibles, consulte los marcos de agentes compatibles.

  • Un agente implementado en AgentCore Runtime con la observabilidad habilitada o un agente creado con un marco compatible configurado con AgentCore Observability, incluida la búsqueda de transacciones. Para obtener más información sobre la configuración de la telemetría, consulte Configuración y entrega de la telemetría.

  • AWS credenciales configuradas con permisos parabedrock-agentcore, bedrock-agentcore-control y () logs CloudWatch

Para obtener instrucciones sobre cómo descargar los intervalos de sesión, consulte Introducción a la evaluación bajo demanda.

Acerca de los ejemplos

Los ejemplos de esta página utilizan el agente de ejemplo de los tutoriales de AgentCore Evaluaciones. El agente tiene dos herramientas (calculatory) y weather está implementado en AgentCore Runtime con la observabilidad habilitada.

En los ejemplos se presupone una sesión de dos turnos:

  1. Turno 1: «¿Qué es 15 + 27?» — el agente usa la calculator herramienta y responde con el resultado.

  2. Curva 2: «¿Qué tiempo hace?» — el agente usa la weather herramienta y responde con el clima actual.

Antes de realizar las evaluaciones, llame a su agente y espere de 2 a 5 minutos CloudWatch para introducir los datos de telemetría.

Las siguientes constantes se utilizan en todos los ejemplos de esta página. Sustitúyalas por tus propios 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?"

Corrección con la respuesta esperada

Builtin.Correctnesses un evaluador a nivel de trazas que mide la precisión con la que la respuesta del agente coincide con la respuesta esperada. Cuando ofreces informaciónexpectedResponse, el evaluador compara la respuesta real del agente con la verdad sobre el terreno mediante una puntuación. LLM-as-a-Judge

ejemplo
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 centrarse en un rastreo específico, pase expected_response como dictado asignando los ID de rastreo a las respuestas 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 apuntar a un rastreo específico, pasa una 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 con afirmaciones

Builtin.GoalSuccessRatees un evaluador a nivel de sesión que valida si el comportamiento del agente satisface un conjunto de afirmaciones en lenguaje natural. Las afirmaciones pueden comprobar el uso de la herramienta, el contenido de las respuestas, el orden de las acciones o cualquier otro comportamiento observable durante toda la conversación.

nota

En los ejemplos siguientes se utilizan afirmaciones que validan el uso de las herramientas, pero las afirmaciones son un lenguaje natural de formato libre; puedes usarlas para afirmar cualquier aspecto del comportamiento de los agentes, como el tono de respuesta, la precisión de los hechos, el cumplimiento de las normas de seguridad o la lógica empresarial.

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

Coincidencia de la trayectoria con la trayectoria esperada

Los evaluadores de trayectorias comparan la secuencia real de llamadas a las herramientas del agente con una secuencia esperada de nombres de herramientas. Hay tres variantes disponibles, cada una con un nivel de coincidencia diferente. Los tres son evaluadores a nivel de sesión y utilizan la puntuación programática (no hay convocatorias de LLM, por lo que el uso de fichas es nulo).

Evaluador Regla de coincidencia Ejemplo

Builtin.TrajectoryExactOrderMatch

La real debe coincidir exactamente con lo esperado: las mismas herramientas, el mismo pedido, sin extras

Esperado:[calculator, weather], Actual: [calculator, weather] → Aprobado. Actual: [calculator, weather, calculator] → Fallo.

Builtin.TrajectoryInOrderMatch

Las herramientas esperadas deben aparecer en orden, pero se permiten herramientas adicionales entre ellas

Esperado:[calculator, weather], Actual: [calculator, some_tool, weather] → Aprobado.

Builtin.TrajectoryAnyOrderMatch

Todas las herramientas esperadas deben estar presentes, el orden no importa, se permiten extras

Esperado:[calculator, weather], Actual: [weather, calculator] → Aprobado.

ejemplo
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. Los nombres de las herramientas se pasan como una lista separada por comas:

    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. Los nombres de las herramientas se pasan como una lista separada por comas:

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

Combinar todos los campos de información básica en una sola solicitud

Puede superar todos los campos de verdad básicos en una sola convocatoria de evaluación. El servicio redirige cada campo al evaluador correspondiente e ignora los campos que un evaluador determinado no utiliza. Esto significa que puedes crear tus entradas de referencia una vez y reutilizarlas en diferentes evaluadores sin modificar la carga útil.

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

Comprender los campos de entrada de referencia ignorados

Cuando proporciona campos reales que un evaluador no utiliza, la respuesta incluye una ignoredReferenceInputFields matriz que enumera los campos no utilizados. Esto es informativo, no un error: la evaluación aún se completa correctamente.

Por ejemplo, si llamas Builtin.Helpfulness con la expectedResponse información proporcionada, el evaluador ignora la verdad básica (Helpfulness no la utiliza) y responde:

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

Este comportamiento es por diseño: te permite crear un único conjunto de entradas de referencia y utilizarlas en varios evaluadores sin ajustar la carga útil de cada uno de ellos.

La verdad básica en los evaluadores personalizados

Los evaluadores personalizados pueden usar campos de veracidad básica mediante marcadores de posición en sus instrucciones de evaluación. Al crear un evaluador personalizado, puede hacer referencia a los siguientes marcadores de posición:

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

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

Por ejemplo, un evaluador personalizado a nivel de seguimiento que compruebe la similitud de las respuestas podría 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.

Cuando se llama a este evaluador con las entradas expectedResponse de referencia, el servicio sustituye el marcador de posición por el valor real real antes de puntuar.

Para obtener más información sobre la creación de evaluadores personalizados, consulte Evaluadores personalizados. Evaluadores personalizados

nota

Los evaluadores personalizados que utilizan marcadores de posición reales ({assertions},{expected_response},{expected_tool_trajectory}) no se pueden usar en las configuraciones de evaluación en línea, ya que las evaluaciones en línea supervisan el tráfico de producción en tiempo real cuando los valores reales no están disponibles.