Olá pessoal, Leo aqui do agntdev.com. Espero que todos estejam tendo uma semana produtiva!
Hoje, quero falar sobre algo que tem estado muito na minha cabeça ultimamente, especialmente enquanto estou mexendo em alguns projetos pessoais que envolvem fluxos de trabalho agentes mais complexos e com várias etapas. Conversamos bastante sobre a construção de agentes, sobre os próprios LLMs e sobre as coisas legais que eles podem fazer. Mas e o lado menos glamoroso, porém absolutamente essencial, de garantir que nossos agentes realmente funcionem de forma confiável e eficiente ao longo do tempo?
Especificamente, estou falando sobre observabilidade de agentes. Não se trata apenas de fazer logs; é sobre entender verdadeiramente o que seu agente está fazendo, por que está fazendo, e detectar problemas antes que eles se agravem. Em um mundo onde agentes interagem com APIs externas, tomam decisões baseadas em entradas dinâmicas e potencialmente ficam rodando por períodos longos, operar no escuro é uma receita para desastre. Eu aprendi isso na marra, como vou explicar a seguir.
O “Bug Misterioso” Que Me Ensinou Tudo
Alguns meses atrás, eu estava desenvolvendo um agente assistente pessoal. Vamos chamá-lo de “Projeto Chronos”. Sua função era monitorar meu calendário, feeds de notícias e canais específicos do Slack, para então sugerir proativamente horários para reuniões, resumir atualizações importantes ou até mesmo rascunhar respostas iniciais para perguntas comuns. Coisa bem padrão à primeira vista.
Eu o construí, testei com alguns cenários, e parecia funcionar bem. Configurei para rodar durante a noite, pensando que ao acordar teria um resumo perfeitamente organizado. Em vez disso, acordei com… nada. Ou melhor, um resumo parcial que terminou abruptamente, seguido por uma mensagem de erro enigmática nos logs do sistema que basicamente dizia “algo quebrou”.
Depurar isso foi um pesadelo. O Chronos tinha que fazer várias coisas: buscar eventos no calendário, consultar uma API de notícias, acessar a API do Slack, processar os dados e então gerar um resumo. Qual etapa falhou? Por quê? Ele ao menos tentou todas as etapas? Foi limite de chamadas na API? Um prompt mal formatado? Um timeout? Eu não fazia ideia.
Meus logs iniciais eram básicos: “Iniciou a etapa X”, “Concluiu a etapa Y” e depois o resultado final ou um erro. Isso não bastava. Era como tentar diagnosticar um problema no carro sabendo apenas que ele ligou e depois parou, sem nenhuma informação sobre a temperatura do motor, pressão do combustível ou falhas elétricas.
Essa experiência reforçou uma coisa: se você leva a sério o desenvolvimento de agentes, precisa de uma observabilidade sólida desde o primeiro dia. Não é um detalhe a mais; é um componente fundamental.
Além do Log Básico: O Que “Observabilidade” Significa para Agentes?
Para mim, a observabilidade de agentes se divide em alguns pontos-chave, cada um oferecendo uma visão diferente do funcionamento do seu agente:
1. Rastreamento da Execução Passo a Passo
Essa é a mais importante. Você precisa saber exatamente o que seu agente está fazendo em cada etapa da execução. Pense nisso como um rastro detalhado de migalhas de pão. No Projeto Chronos, eu precisava ver:
- Quando ele começou a buscar eventos no calendário.
- Quais parâmetros usou na chamada da API do calendário (ex: intervalo de datas).
- A resposta bruta da API do calendário.
- Como ele processou essa resposta.
- O prompt exato que enviou ao LLM para resumir as infos do calendário.
- A resposta do LLM.
- Quaisquer ferramentas que foram chamadas, com suas entradas e saídas.
- Mensagens de erro, não apenas “algo falhou”, mas um erro específico com contexto (ex: “API do calendário retornou 401 Unauthorized para o usuário X”).
Esse nível de detalhe é valiosíssimo para reproduzir problemas e entender pontos de decisão. Meus logs iniciais só diziam “Buscando dados do calendário…” e depois “Resumindo dados do calendário…” sem nada entre eles. Não ajudava quando a busca pelos dados falhava silenciosamente.
2. Rastreamento de Prompt e Resposta
O LLM é o cérebro do seu agente. Se você não sabe quais prompts ele está recebendo e quais respostas está gerando, está no escuro. Isso inclui:
- O prompt completo enviado ao LLM (sistema, usuário e descrição de chamadas de função).
- Os parâmetros de geração, como temperature, top_p e outros.
- A resposta bruta do LLM, incluindo quaisquer chamadas de ferramentas que ele resolveu fazer.
- Uso de tokens (entrada, saída, total) para controle de custo e análise de performance.
Isso é essencial para engenharia de prompt. Se o agente está respondendo com coisas sem sentido, ver o prompt exato que ele recebeu ajuda a descobrir se o contexto de entrada estava errado ou se o próprio prompt estava mal estruturado.
3. Monitoramento das Chamadas de Ferramentas
Agentes frequentemente interagem com ferramentas externas ou APIs. Cada interação é um ponto potencial de falha ou comportamento inesperado. Você precisa registrar:
- Qual ferramenta foi chamada.
- Os argumentos exatos passados para a ferramenta.
- A saída bruta da ferramenta.
- Quaisquer erros retornados pela ferramenta ou durante sua execução.
No Chronos, se ele tentasse chamar a API do Slack para postar um resumo, eu precisava saber qual canal foi alvo, o conteúdo da mensagem e se a API retornou um erro 403 Forbidden, por exemplo. Minha configuração anterior só dizia “Tentou postar no Slack.”
4. Capturas do Estado Interno
Muitos agentes mantêm algum estado interno – um bloco de notas, uma memória, uma lista de fatos que coletaram. Capturar periodicamente esse estado pode ser extremamente útil para depuração. Se um agente travar em um loop ou tomar uma decisão errada, ver seus “pensamentos” internos em vários momentos pode revelar onde o entendimento falhou.
Isso é menos sobre registrar cada mudança de variável e mais sobre capturar estados-chave de tomada de decisão. No Chronos, isso poderia ser “Entendimento atual da agenda do usuário” ou “Principais pontos extraídos dos feeds de notícias até agora.”
Abordagens Práticas: Construindo Observabilidade
Certo, mas como implementar isso sem se afogar em logs? Aqui vão algumas estratégias práticas e trechos de código.
Estratégia 1: Logging Estruturado com Contexto
Esqueça `print()`. Use uma biblioteca de logging adequada (como o módulo `logging` do Python). O crucial é enriquecer suas mensagens de log com dados estruturados (JSON, dicionários) em vez de strings simples. Isso torna os logs analisáveis, pesquisáveis e muito mais úteis.
Aqui está um exemplo simplificado em Python:
import logging
import json
import uuid
from datetime import datetime
# Configuração básica do logger (em um aplicativo real, você configuraria isso de maneira mais sólida)
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
def log_agent_step(agent_id: str, step_name: str, status: str, details: dict = None):
log_data = {
"timestamp": datetime.now().isoformat(),
"agent_id": agent_id,
"step_name": step_name,
"status": status, # por exemplo, "started", "completed", "failed"
"details": details if details is not None else {}
}
logger.info(json.dumps(log_data))
class MyAgent:
def __init__(self, agent_id: str = None):
self.agent_id = agent_id if agent_id else str(uuid.uuid4())
self.memory = [] # Memória interna simples
def _fetch_calendar_events(self, user_id: str, date_range: str):
log_agent_step(self.agent_id, "fetch_calendar_events", "started",
{"user_id": user_id, "date_range": date_range})
try:
# Simular chamada à API
if "error" in date_range:
raise ValueError("Erro simulado na API do calendário")
events = [
{"title": "Equipe Sync", "time": "10:00 AM"},
{"title": "Reunião com Cliente", "time": "02:00 PM"}
]
log_agent_step(self.agent_id, "fetch_calendar_events", "completed",
{"num_events": len(events), "data_preview": events[0]})
self.memory.append(f"Eventos do calendário: {events}")
return events
except Exception as e:
log_agent_step(self.agent_id, "fetch_calendar_events", "failed",
{"error": str(e), "traceback": "..."}) # Na vida real, capturar traceback
raise
def _summarize_with_llm(self, prompt_text: str):
log_agent_step(self.agent_id, "summarize_with_llm", "started",
{"prompt_length": len(prompt_text), "prompt_preview": prompt_text[:100]})
try:
# Simular chamada ao LLM
if "fail_llm" in prompt_text:
raise RuntimeError("Erro simulado na API do LLM")
response = f"Resumo do LLM de: {prompt_text[:50]}..."
token_usage = {"input": len(prompt_text) // 4, "output": len(response) // 4}
log_agent_step(self.agent_id, "summarize_with_llm", "completed",
{"response_length": len(response), "token_usage": token_usage,
"llm_response_preview": response[:100]})
self.memory.append(f"Resumo produzido pelo LLM: {response}")
return response
except Exception as e:
log_agent_step(self.agent_id, "summarize_with_llm", "failed",
{"error": str(e), "traceback": "..."})
raise
def run_daily_briefing(self, user_id: str):
log_agent_step(self.agent_id, "run_daily_briefing", "started", {"user_id": user_id})
try:
calendar_data = self._fetch_calendar_events(user_id, "today")
news_summary = self._summarize_with_llm("Resuma as principais notícias de hoje...")
final_briefing_prompt = (
f"Crie um briefing diário com base em:\n"
f"Calendário: {json.dumps(calendar_data)}\n"
f"Notícias: {news_summary}"
)
final_briefing = self._summarize_with_llm(final_briefing_prompt)
log_agent_step(self.agent_id, "run_daily_briefing", "completed",
{"final_briefing_length": len(final_briefing)})
return final_briefing
except Exception as e:
log_agent_step(self.agent_id, "run_daily_briefing", "failed",
{"error": str(e), "current_memory": self.memory}) # Captura a memória em caso de falha
raise
# Exemplo de Uso
if __name__ == "__main__":
agent = MyAgent()
print(f"\n--- Executando o Agente {agent.agent_id} (Caso de Sucesso) ---")
try:
briefing = agent.run_daily_briefing("leo_g")
print(f"Briefing: {briefing[:100]}...")
except Exception as e:
print(f"A execução do agente falhou: {e}")
agent_fail = MyAgent()
print(f"\n--- Executando o Agente {agent_fail.agent_id} (Caso de Falha do Calendário) ---")
try:
# Simular falha do calendário passando "error" em date_range
agent_fail._fetch_calendar_events("leo_g", "error_today")
except Exception as e:
print(f"A execução do agente falhou conforme esperado: {e}")
agent_llm_fail = MyAgent()
print(f"\n--- Executando o Agente {agent_llm_fail.agent_id} (Caso de Falha do LLM) ---")
try:
# Simular falha do LLM
agent_llm_fail._summarize_with_llm("fail_llm_please")
except Exception as e:
print(f"A execução do agente falhou conforme esperado: {e}")
Observe como `log_agent_step` captura o ID do agente, o nome da etapa, o status e um dicionário de detalhes relevantes. Isso facilita a filtragem de logs por ID de agente, o rastreamento de uma única execução ou a busca por todas as etapas “falhadas”.
Estratégia 2: Observabilidade Centralizada com uma Biblioteca/Serviço Dedicado
Para agentes mais complexos ou ambientes de produção, você rapidamente superará o registro simples em arquivo. É aqui que ferramentas especializadas se destacam. Bibliotecas como o `LangSmith` do LangChain (ou similares para outros frameworks) fornecem rastreamento integrado, visualização e depuração para aplicações LLM.
Mesmo que você não esteja usando LangChain, o conceito é transferível. Você pode construir seu próprio wrapper em torno da execução do seu agente que envia eventos estruturados para um serviço de registro (Datadog, Splunk, ELK stack ou até mesmo um simples bucket S3 com processamento Lambda). A chave é padronizar o esquema de evento.
Meu Projeto Chronos melhorado agora usa uma classe `TraceManager` personalizada que encapsula operações críticas. Este gerenciador envia eventos estruturados para um banco de dados local durante o desenvolvimento e para um serviço de registro em nuvem em produção. Isso me permite ver um “rascunho” completo de cada execução do agente, com etapas aninhadas e todos os dados associados (prompt, respostas, entradas/saídas de ferramentas, erros).
Estratégia 3: Interceptando Chamadas de LLM e Ferramentas
Muitos SDKs de LLM permitem que você configure callbacks ou interceptors para chamadas de API. Use isso! Em vez de registrar manualmente antes e depois de cada prompt do LLM, você pode ter um único interceptor que registra automaticamente:
- O exato endpoint da API acessado.
- Cabeçalhos e corpo da requisição (especialmente o prompt).
- Cabeçalhos e corpo da resposta (a conclusão).
- Latência.
- Quaisquer exceções.
Da mesma forma, encapsule suas chamadas de ferramenta. Se você tiver uma ferramenta `search_web`, o wrapper deve registrar a consulta de busca, o mecanismo de busca utilizado e os principais N resultados retornados, juntamente com quaisquer erros.
Ações Práticas para seu Próximo Projeto de Agente
- Desenhe para Observabilidade Primeiro: Não trate isso como um pensamento posterior. Pense no que você precisaria para depurar antes mesmo de escrever seu primeiro passo do agente.
- Abrace o Registro Estruturado: Deixe de lado `print()` e `console.log()` para código de produção. Use uma biblioteca de registro adequada e output de dados estruturados (JSON) para cada evento significativo.
- Rastreie Tudo que é Importante: Registre o início e o fim de cada etapa maior, todos os prompts e respostas do LLM (incluindo parâmetros e contagens de tokens), e cada chamada de ferramenta com suas entradas e saídas.
- Capture o Estado em Caso de Falha: Quando um agente falha, registre seu estado interno ou memória naquele momento. Isso fornece contexto crucial para entender por que ele falhou.
- Use IDs Específicos para Agentes: Atribua um ID único a cada execução do agente (por exemplo, um UUID). Isso permite que você filtre e rastreie facilmente um único caminho de execução através dos seus logs.
- Visualize Seus Rastros: Se possível, use ou construa uma ferramenta que possa visualizar esses logs estruturados como uma sequência de eventos. Ver o fluxo torna a depuração infinitamente mais fácil do que siftar por texto bruto. O LangSmith faz isso de maneira linda, mas até mesmo um script personalizado pode gerar uma linha do tempo simples em HTML.
- Monitore Custos: O uso de tokens do LLM é um custo direto. Registre isso. Isso ajuda você a entender onde seu dinheiro está indo e otimizar seus prompts.
Construir agentes é emocionante, mas construir agentes confiáveis é onde está o verdadeiro trabalho (e o verdadeiro valor). E a confiabilidade começa com saber o que está acontecendo “por trás das cortinas”. Minha dolorosa experiência com o Projeto Chronos me ensinou bem essa lição. Não espere pela sua própria “falha misteriosa” para convencê-lo. Comece a registrar de forma inteligente hoje.
Quais são suas estratégias de observabilidade favoritas para agentes? Fale comigo nos comentários ou nas redes sociais. Estou sempre interessado em ouvir como os outros estão enfrentando esses desafios!
🕒 Published: