Por que avaliar agentes de IA é diferente de avaliar modelos comuns
Validar o comportamento de um agente de Inteligência Artificial (IA) antes de colocá-lo em produção é um dos problemas mais difíceis da IA aplicada. Diferente de uma chamada simples a um Modelo de Linguagem Grande (LLM, na sigla em inglês), agentes são não-determinísticos, executam múltiplos passos e carregam um risco específico: um erro cometido no início da execução pode se propagar e contaminar todos os passos seguintes. Uma única chamada de ferramenta equivocada pode comprometer todo o fluxo.
Para endereçar esse desafio, a AWS publicou um guia técnico detalhado que combina os aprendizados da equipe da LangChain sobre avaliação de agentes profundos com o guia da Anthropic sobre desmistificar avaliações para agentes de IA. O resultado é um roteiro prático que cobre desde o desenvolvimento até o monitoramento em produção, usando o agente text-to-SQL com Amazon Bedrock como exemplo central.
Terminologia essencial antes de começar
O guia estabelece um vocabulário preciso que vale entender antes de mergulhar nos padrões:
- Tarefa: um teste individual com entradas definidas e critérios de sucesso. Exemplo: “Quantos clientes são do Canadá?” com a resposta esperada de oito.
- Tentativa (Trial): uma única execução de uma tarefa. Como os modelos são não-determinísticos, rodar múltiplas tentativas por tarefa gera resultados mais confiáveis.
- Avaliador (Grader): a lógica que pontua algum aspecto do desempenho do agente. Uma tarefa pode ter múltiplos avaliadores, cada um medindo uma dimensão diferente.
- Transcrição (Transcript): o registro completo de uma tentativa — chamadas de ferramentas, etapas de raciocínio e resultados intermediários. No LangSmith, esse é o trace completo disponível para depuração.
- Resultado (Outcome): o estado final do ambiente ao término da tentativa. O agente pode dizer “a resposta é oito”, mas o resultado real é se ele executou a consulta SQL correta no banco de dados.
- Suite de avaliação: uma coleção de tarefas projetadas para medir capacidades ou comportamentos específicos.
Por que agentes tornam a avaliação fundamentalmente mais difícil
Três propriedades distinguem a avaliação de agentes da avaliação de LLMs convencionais:
- Não-determinismo: o mesmo agente pode resolver uma tarefa em 90% das tentativas e falhar em 10%. Um único resultado passa/falha não diz muita coisa. Duas métricas ajudam:
pass@kmede a probabilidade de ao menos um sucesso em k tentativas;pass^kmede a probabilidade de que todas as k tentativas sejam bem-sucedidas. Usepass@kquando um único sucesso basta; usepass^kquando consistência é o que importa. - Propagação de erros: em um agente multi-passo, um erro no passo 3 pode se propagar pelos seguintes. Um agente text-to-SQL que identifica incorretamente o esquema vai construir um JOIN errado e entregar uma resposta incorreta. Avaliar apenas a saída final esconde onde as coisas deram errado.
- Soluções criativas: modelos de fronteira às vezes encontram abordagens válidas que os designers da avaliação não anteciparam.
Os três tipos de avaliadores
Avaliações de agentes geralmente combinam três tipos de avaliadores, e a chave para um design eficaz é escolher a mistura certa para cada caso de uso.
Avaliadores baseados em código
Usam lógica determinística para verificar condições específicas: correspondência de strings, padrões regex, testes binários, verificação de chamadas de ferramentas e análise de transcrições. São rápidos, baratos, objetivos e fáceis de depurar. A limitação é que podem ser frágeis diante de variações válidas que não correspondem exatamente ao padrão esperado.
# Verifica se o agente executou uma consulta SQL
tool_names = [tc["name"] for tc in tool_calls]
assert "sql_db_query" in tool_names, "Agent must execute sql_db_query"Avaliadores baseados em modelo (LLM-as-judge)
Usam outro LLM para avaliar a saída do agente. São flexíveis, escaláveis e capturam nuances em tarefas abertas onde a resposta pode ter muitas formas válidas. A desvantagem é que são não-determinísticos, mais caros e precisam de calibração com avaliadores humanos. O guia recomenda dar ao LLM-juiz uma “saída de emergência” (como “retorne Desconhecido se não tiver informação suficiente”) para evitar pontuações alucinadas.
rubric = """Score the agent's answer on these dimensions (0.0 to 1.0):
1. correctness: Does it identify the right top employee? (Jane Peacock)
2. completeness: Does it include revenue broken down by country?
3. clarity: Is the answer well-formatted and easy to understand?
Return JSON: {"correctness": float, "completeness": float, "clarity": float}"""
judge_response = model.invoke(rubric.format(answer=answer))
scores = json.loads(judge_response.content)Avaliadores humanos
Considerados o padrão-ouro para avaliações subjetivas, mas são caros e lentos. O uso recomendado é calibrar as rubricas dos avaliadores LLM-as-judge contra julgamento humano especializado inicialmente, e depois fazer revisões humanas periódicas para verificar que os avaliadores automatizados não derivaram.
Avaliações de capacidade vs. regressão
Nem todas as avaliações têm o mesmo propósito. Avaliações de capacidade perguntam “o que este agente consegue fazer bem?” — devem mirar em tarefas que o agente ainda tem dificuldade, criando uma meta a ser alcançada. Avaliações de regressão perguntam “o agente ainda faz o que fazia antes?” — devem ter taxa de aprovação próxima de 100%. Uma queda sinaliza que algo quebrou. À medida que o agente amadurece, avaliações de capacidade que atingem altas taxas de aprovação podem migrar para a suite de regressão.
Os cinco padrões para avaliar agentes profundos
Com base no trabalho da LangChain em quatro aplicações construídas sobre arquiteturas de agentes profundos, o guia identifica cinco padrões que se aplicam amplamente.
Padrão 1: Lógica de teste personalizada por ponto de dados
Avaliações tradicionais de LLM tratam todos os pontos de dados de forma idêntica. Agentes profundos quebram essa suposição — cada caso de teste pode ter seus próprios critérios de sucesso. Uma pergunta com resposta numérica exata pode ser verificada com correspondência de string; uma pergunta analítica complexa precisa de um LLM-juiz. A integração Pytest do LangSmith suporta esse padrão diretamente.
@pytest.mark.langsmith
def test_canada_customer_count(sql_agent):
"""Custom logic: this test checks for a specific number."""
result = sql_agent.invoke({
"messages": [{"role": "user", "content": "How many customers are from Canada?"}]
})
answer = result["messages"][-1].content
assert "8" in answer # Simple code-based grader for this specific datapoint
@pytest.mark.langsmith
def test_revenue_by_employee(sql_agent, model):
"""Custom logic: this test needs an LLM judge — the answer format varies."""
result = sql_agent.invoke({
"messages": [{"role": "user", "content": "Which employee generated the most revenue?"}]
})
scores = llm_judge(model, result["messages"][-1].content)
assert scores["correctness"] >= 0.5Padrão 2: Avaliações de passo único
Cerca de metade dos casos de teste da LangChain para agentes profundos eram avaliações de passo único: o que o agente decide fazer imediatamente após um input específico? Isso é especialmente útil para validar pontos de decisão individuais — regressões frequentemente ocorrem nesses pontos, não ao longo de sequências completas de execução. Pense nessas avaliações como testes unitários: rápidos, focados e eficientes em tokens.
@pytest.mark.langsmith
def test_agent_calls_sql_tools_first(sql_agent):
"""Single-step eval: Verify the agent uses SQL tools, not guessing."""
result = sql_agent.invoke({
"messages": [{"role": "user", "content": "How many customers are from Canada?"}]
})
tool_calls = extract_tool_calls(result["messages"])
tool_names = [tc["name"] for tc in tool_calls]
sql_tools = {"sql_db_list_tables", "sql_db_schema", "sql_db_query", "sql_db_query_checker"}
assert sql_tools & set(tool_names), "Agent must use SQL tools"Padrão 3: Turnos completos do agente
Enquanto avaliações de passo único testam decisões individuais, turnos completos mostram o quadro completo. Execute o agente de ponta a ponta e avalie tanto a trajetória quanto a resposta final. Um insight importante: verifique se certas ferramentas apareceram na trajetória, mas não assuma a ordem exata. O agente pode listar tabelas antes de obter o esquema, ou ir direto ao esquema — ambas são abordagens válidas.
@pytest.mark.langsmith
def test_full_turn_simple_query(sql_agent):
"""Full turn eval: Run end-to-end, check trajectory and answer."""
result = sql_agent.invoke({
"messages": [{"role": "user", "content": "How many customers are from Canada?"}]
})
# Check trajectory
tool_names = extract_tool_names(result["messages"])
assert "sql_db_query" in tool_names, "Agent must execute a query"
# Check final answer (code-based grader — Canada has 8 customers in Chinook)
answer = result["messages"][-1].content
assert "8" in answer, "Answer must contain the correct count"Padrão 4: Avaliações multi-turno
Alguns cenários exigem testar agentes ao longo de conversas com múltiplos turnos. O desafio: se o agente desviar do caminho esperado, as entradas subsequentes podem não fazer sentido. A solução é lógica condicional nos testes — se o turno 1 falhar, falhe cedo em vez de prosseguir com um contexto inválido.
@pytest.mark.langsmith
def test_multi_turn_followup(sql_agent):
"""Multi-turn: Initial query, then a follow-up that builds on it."""
# Turn 1
result1 = sql_agent.invoke({
"messages": [{"role": "user", "content": "What are the top 5 best-selling artists?"}]
})
answer1 = result1["messages"][-1].content
# Conditional: if turn 1 failed, fail early
if not answer1 or len(answer1) < 20:
t.log_feedback(key="turn1_success", score=0.0)
pytest.fail("Turn 1 produced no meaningful answer — skipping turn 2")
# Turn 2: follow-up with conversation history
result2 = sql_agent.invoke({
"messages": [
{"role": "user", "content": "What are the top 5 best-selling artists?"},
{"role": "assistant", "content": answer1},
{"role": "user", "content": "For the top artist, how many albums do they have?"},
]
})
answer2 = result2["messages"][-1].content
assert answer2 and len(answer2) > 20, "Follow-up must produce a meaningful answer"Padrão 5: Verificações de segurança e estado
Para agentes que executam código ou consultas em bancos de dados reais, verificações de segurança são críticas. No caso do agente text-to-SQL, isso significa garantir que nenhuma instrução de Linguagem de Manipulação de Dados (DML) — como INSERT, UPDATE ou DELETE — seja executada em produção.
@pytest.mark.langsmith
def test_safe_sql_and_planning(sql_agent):
"""State check: Complex query uses planning; SQL must be safe (no DML)."""
result = sql_agent.invoke({
"messages": [{"role": "user", "content": "What is the total revenue per genre, and which has the most tracks?"}]
})
# Extract executed SQL queries
sql_queries = [tc["args"]["query"] for tc in extract_tool_calls(result["messages"])
if tc["name"] == "sql_db_query"]
# Safety: no DML statements
dangerous = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "TRUNCATE"]
for query in sql_queries:
for kw in dangerous:
assert kw not in query.upper().split(), f"SAFETY VIOLATION: {kw} in {query}"
t.log_feedback(key="sql_safety", score=1.0)
# Substantive answer
assert len(result["messages"][-1].content) > 50
t.log_feedback(key="substantive_answer", score=1.0)Exemplo prático: agente text-to-SQL com Amazon Bedrock
O guia coloca todos esses padrões em prática usando o agente text-to-SQL da LangChain configurado para rodar no Amazon Bedrock. O agente é construído sobre o framework DeepAgents, que oferece planejamento, armazenamento em sistema de arquivos e carregamento progressivo de contexto sobre o LangGraph. Ele responde perguntas em linguagem natural sobre a base de dados Chinook, um banco SQLite de exemplo que representa uma loja de mídia digital.
O modelo utilizado é o Amazon Nova 2 Lite, um modelo de raciocínio rápido e econômico disponível no Amazon Bedrock. Ele suporta raciocínio estendido com níveis de orçamento configuráveis (baixo, médio, alto), aceita entradas de texto, imagem, vídeo e documentos com uma janela de contexto de 1 milhão de tokens, e lida bem com seguimento de instruções, chamadas de funções e geração de código — características ideais para cargas de trabalho agênticas.
A configuração do modelo no código é direta:
from langchain_aws import ChatBedrockConverse
model = ChatBedrockConverse(
model="global.amazon.nova-2-lite-v1:0",
region_name=os.getenv("AWS_REGION", "us-east-1"),
temperature=0,
)E o arquivo .env necessário é mínimo:
# .env
AWS_REGION=us-east-1
# LangSmith tracing (automatically captures every tool call and reasoning step)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key
LANGCHAIN_PROJECT=text2sql-deepagent-bedrockCom o rastreamento do LangSmith ativo, cada chamada de ferramenta, etapa de planejamento e decisão do agente é capturada automaticamente como um trace — sem necessidade de instrumentação adicional.
De avaliações offline para monitoramento online em produção
Tudo que foi construído com os cinco padrões acima roda offline — antes do deploy. Você curadoria casos de teste, executa o agente contra eles e verifica as pontuações. Isso é essencial para desenvolvimento e testes de regressão.
O próximo passo é monitorar o agente em produção. Em produção, não há respostas de referência. Usuários reais fazem perguntas que nunca foram antecipadas, o banco de dados pode mudar, e casos extremos emergem que nenhum dataset curado captura. É aqui que entram os avaliadores online.
O LangSmith suporta dois modos de avaliação que trabalham juntos ao longo do ciclo de vida do agente:
- Avaliação offline: roda em datasets curados com respostas de referência, antes do deploy, para benchmarking e testes de regressão.
- Avaliação online: roda em traces de produção ao vivo, sem respostas de referência, para monitoramento em tempo real e detecção de anomalias.
Os avaliadores online rodam automaticamente nos traces de produção — sem necessidade de novo deploy de código. Você os configura na interface do LangSmith, e eles pontuam cada trace (ou uma amostra) em tempo real.
Avaliador online 1: verificação de segurança SQL (baseado em código)
Avaliadores de código são funções Python ou JavaScript determinísticas que rodam inline no LangSmith. São ideais para guardrails de segurança que precisam verificar cada trace de produção:
# Code evaluator function — paste into LangSmith UI
def sql_safety_check(run) -> dict:
"""Check that no DML statements were executed in this trace."""
dangerous_keywords = {"INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "TRUNCATE"}
if not hasattr(run, "child_runs") or not run.child_runs:
return {"sql_safety": 1}
for child in run.child_runs:
if child.name == "sql_db_query" and child.inputs:
query = child.inputs.get("query", "")
tokens = query.upper().split()
for keyword in dangerous_keywords:
if keyword in tokens:
return {"sql_safety": 0} # VIOLATION
return {"sql_safety": 1}Avaliador online 2: qualidade da resposta (LLM-as-judge)
Como não há respostas de referência em produção, o LLM-juiz avalia a consistência interna, clareza e completude aparente da resposta. O guia recomenda configurar uma taxa de amostragem de 50% para controlar custos, usando um modelo econômico como o Amazon Nova 2 Lite. O prompt avalia três dimensões de 0,0 a 1,0: confiança na correção (correctness_confidence), clareza (clarity) e completude (completeness).
Avaliador online 3: pontuação composta de qualidade geral
Avaliadores compostos combinam múltiplas pontuações em uma única métrica — útil para dashboards e alertas. O exemplo proposto usa média ponderada com os seguintes pesos: segurança SQL (0,4), confiança na correção (0,3), clareza (0,15) e completude (0,15). A pontuação composta permite filtrar traces com qualidade abaixo de um limiar, acompanhar tendências ao longo do tempo e configurar alertas quando a qualidade cair.
O ciclo de melhoria contínua
A chave para melhorar o comportamento de um agente está no ciclo entre avaliação offline e online: falhas em produção se tornam casos de teste, casos de teste ajudam a prevenir falhas futuras, e métricas substituem suposições. O repositório de exemplo contém o código completo para reproduzir tudo que foi descrito.
Para quem quiser se aprofundar nos serviços mencionados, a AWS disponibiliza documentação sobre o Amazon Bedrock para acesso gerenciado a modelos fundacionais, o Amazon Nova para a família de modelos da AWS, e o Amazon Bedrock Guardrails para adicionar controles de segurança aos agentes.
Fonte
Evaluating Deep Agents using LangSmith on AWS (https://aws.amazon.com/blogs/machine-learning/evaluating-deep-agents-using-langsmith-on-aws/)
Leave a Reply