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.
Tópicos
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 |
|---|---|---|---|
|
|
Traço |
|
Mede a precisão com que a resposta do agente corresponde à resposta esperada. Usa LLM-as-a-Judge pontuação. |
|
|
Sessão |
|
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. |
|
|
Sessão |
|
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). |
|
|
Sessão |
|
Verifica se todas as ferramentas esperadas aparecem em ordem na sequência real, mas permite ferramentas extras entre elas. Pontuação programática. |
|
|
Sessão |
|
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 |
|---|---|---|---|
|
|
String |
Traço |
A resposta esperada do agente para um turno específico. Com escopo definido para um rastreamento usado |
|
|
Lista de strings |
Sessão |
Declarações em linguagem natural que devem ser verdadeiras sobre o comportamento do agente durante a sessão. |
|
|
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.Correctnessainda 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
ignoredReferenceInputFieldsna resposta todos os campos que não foram usados. -
Você não precisa fornecer todos
expectedResponseos vestígios. Traços sem verdade fundamental são avaliados usando a variante sem verdade fundamental do avaliador.
Pré-requisitos
-
Python 3.10+
-
Um agente implantado no AgentCore Runtime com a observabilidade ativada ou um agente criado com uma estrutura compatível configurada com o Observability. AgentCore Estruturas suportadas:
-
Strands Agents
-
LangGraph com
opentelemetry-instrumentation-langchainouopeninference-instrumentation-langchain
-
-
Pesquisa de transações ativada em CloudWatch — consulte Ativar pesquisa de transações
-
AWS credenciais configuradas com permissões para
bedrock-agentcorebedrock-agentcore-control, elogs() 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çõescalculator e weather — e é implantado no AgentCore Runtime com a observabilidade ativada.
Os exemplos pressupõem uma sessão de dois turnos:
-
Turno 1: “Quanto é 15 + 27?” — o agente usa a
calculatorferramenta e responde com o resultado. -
Turno 2: “Qual é o clima?” — o agente usa a
weatherferramenta 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
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
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 |
|---|---|---|
|
|
O real deve corresponder exatamente ao esperado — mesmas ferramentas, mesmo pedido, sem extras |
Esperado: |
|
|
As ferramentas esperadas devem aparecer em ordem, mas ferramentas extras são permitidas entre elas |
Esperado: |
|
|
Todas as ferramentas esperadas devem estar presentes, o pedido não importa, extras são permitidos |
Esperado: |
exemplo
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
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.