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.
Tópicos
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 |
|---|---|---|---|
|
|
Rastrear |
|
Mede a precisão com que a resposta do agente corresponde à resposta esperada. Usa a 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 a 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 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
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 |
|---|---|---|---|
|
|
String |
Rastrear |
A resposta esperada do agente para um turno específico. Escopo 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ásicos são opcionais. Se você os omitir, os avaliadores retornarão ao modo básico livre de verdade (por exemplo,
Builtin.Correctnessainda funciona semexpectedResponseeles, 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
ignoredReferenceInputFieldsna resposta todos os campos que não foram usados. -
Você não precisa fornecer todos
expectedResponseos 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 para
bedrock-agentcore,bedrock-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 calculator e weather — e é implantado no AgentCore Runtime com a observabilidade ativada.
Os exemplos pressupõem uma sessão de dois turnos:
-
Turno 1: “O que é 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 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
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
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 |
|---|---|---|
|
|
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, a ordem não importa, os extras são permitidos |
Esperado: |
exemplo
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
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.