Oi a todos, Leo aqui do agntdev.com. Espero que todos estejam tendo uma semana produtiva!
Hoje quero explorar algo que tem me preocupado muito ultimamente, especialmente desde que trabalhei em alguns projetos pessoais que envolvem fluxos de trabalho de agentes mais complexos e de múltiplas fases. Falamos muito sobre a construção de agentes, dos próprios LLM e das coisas interessantes que eles podem fazer. Mas e quanto ao aspecto menos glamouroso, mas absolutamente crucial, de garantir que nossos agentes funcionem realmente de maneira confiável e eficiente ao longo do tempo?
Mais precisamente, estou falando sobre observabilidade de agentes. Não se trata apenas de logging; trata-se de entender realmente o que seu agente está fazendo, por que ele está fazendo isso e detectar problemas antes que eles se tornem ingovernáveis. Em um mundo onde os agentes interagem com APIs externas, tomam decisões com base em entradas dinâmicas e podem potencialmente operar por longos períodos, navegar no escuro é uma receita para o desastre. Aprendi isso da maneira mais difícil, como explicarei.
O “Bug Misterioso” Que Me Ensinou Tudo
Há alguns meses, eu estava desenvolvendo um agente de assistente pessoal. Chamemos de “Projeto Chronos.” Seu papel era monitorar meu calendário, meus feeds de notícias e canais específicos do Slack, então propor proativamente horários para reuniões, resumir atualizações chave ou até redigir respostas iniciais a perguntas comuns. Um funcionamento bastante padrão na superfície.
Eu o construí, testei com alguns cenários e parecia funcionar corretamente. Eu o configurei para funcionar durante a noite, pensando em acordar com um resumo perfeitamente organizado. Em vez disso, acordei com… nada. Ou melhor, um resumo parcial que parou abruptamente, seguido por uma mensagem de erro críptico nos meus logs de sistema que dizia basicamente “algo deu errado.”
Debugá-lo foi um pesadelo. Chronos deveria fazer várias coisas: recuperar eventos do calendário, consultar uma API de notícias, tocar uma API do Slack, processar os dados e então gerar um resumo. Qual fase falhou? Por quê? Ele tentou todas as fases? Foi um limite de taxa da API? Um prompt malformado? Um timeout? Eu não tinha ideia.
Meu logging inicial era básico: “Fase X iniciada,” “Fase Y concluída,” e então a saída final ou um erro. Não era suficiente. Era como tentar diagnosticar um problema em um carro sabendo apenas que ele partiu e então apagou, sem qualquer informação sobre a temperatura do motor, pressão do combustível ou defeitos elétricos.
Essa experiência destacou um ponto: se você está sério sobre o desenvolvimento de agentes, precisa de uma boa observabilidade desde o primeiro dia. Não é uma reflexão pós-fato; é um componente fundamental.
Além do Logging Básico: O Que Significa “Observabilidade” para Agentes?
Para mim, a observabilidade de agentes se divide em alguns domínios chave, cada um oferecendo uma perspectiva diferente sobre o funcionamento do seu agente:
1. Monitoramento da Execução Fase por Fase
Esse é o mais crítico. Você precisa saber exatamente o que seu agente está fazendo em cada fase de sua execução. Pense nisso como um fio de Ariadne detalhado. Para o Projeto Chronos, eu precisava ver:
- Quando começou a recuperar os eventos do calendário.
- Os parâmetros que usou para a chamada da API do calendário (por exemplo, o intervalo de datas).
- A resposta bruta da API do calendário.
- Como processou essa resposta.
- O prompt exato que enviou ao LLM para resumir as informações do calendário.
- A resposta do LLM.
- Todos os serviços chamados, com suas entradas e saídas.
- As mensagens de erro, não apenas “algo deu errado”, mas um erro específico com contexto (por exemplo, “A API do calendário retornou 401 Unauthorized para o usuário X”).
Esse nível de detalhe é inestimável para recriar problemas e entender os pontos de decisão. Meus logs iniciais diziam apenas “Recuperando dados do calendário…” e então “Resumindo dados do calendário…” sem nada no meio. Não é útil quando a recuperação dos dados em si falhou silenciosamente.
2. Monitoramento de Prompts e Respostas
O LLM é o cérebro do seu agente. Se você não sabe quais prompts ele recebe e quais respostas ele retorna, está navegando no escuro. Isso inclui:
“`html
- O prompt completo enviado ao LLM (sistema, usuário e todas as descrições das chamadas de função).
- A temperatura, top_p e outros parâmetros de geração.
- A resposta bruta do LLM, incluindo todas as chamadas aos instrumentos que ele decidiu fazer.
- Uso dos tokens (entrada, saída, total) para monitoramento de custos e análise de desempenho.
Isso é crucial para a engenharia dos prompts. Se um agente retorna respostas sem sentido, ver o prompt exato que recebeu ajuda a fazer debugging se o contexto de entrada estava errado ou se o próprio prompt estava mal estruturado.
3. Monitoramento das Chamadas aos Instrumentos
Os agentes frequentemente interagem com ferramentas externas ou APIs. Cada interação representa um potencial ponto de falha ou um comportamento inesperado. Você deve registrar:
- Qual ferramenta foi chamada.
- Os argumentos exatos passados para a ferramenta.
- A resposta bruta da ferramenta.
- Todos os erros retornados pela ferramenta ou durante sua execução.
Para a Chronos, se ele estava tentando chamar a API Slack para postar um resumo, eu precisava saber o canal direcionado, o conteúdo da mensagem e se a API retornava, por exemplo, um erro 403 Forbidden. Minha configuração anterior apenas dizia “Tentativa de postar no Slack.”
4. Capturas de Estado
Muitos agentes mantêm um estado interno – um caderno, uma memória, uma lista de fatos que coletaram. Capturar regularmente esse estado pode ser incrivelmente útil para debugging. Se um agente se vê preso em um ciclo ou toma uma decisão errada, ver seus “pensamentos” internos em vários momentos pode revelar onde sua compreensão saiu do caminho.
Isso diz menos respeito ao registro de cada mudança de variável e mais à captura dos estados chave de decisão. Para a Chronos, isso poderia ser “Compreensão atual do horário do usuário,” ou “Pontos chave dos feeds de notícias até agora.”
Abordagens Práticas: Integrar a Observabilidade
Ok, como implementamos tudo isso sem nos afogar em logs? Aqui estão algumas estratégias práticas e fragmentos de código.
Estratégia 1: Logging Estruturado com Contexto
Esqueça as declarações `print()`. Use uma biblioteca de logging apropriada (como o módulo `logging` do Python). É fundamental enriquecer suas mensagens de logging com dados estruturados (JSON, dicionários) em vez de simples strings. Isso torna os logs analisáveis, pesquisáveis e muito mais úteis.
Aqui está um exemplo simplificado em Python:
“““html
import logging
import json
import uuid
from datetime import datetime
# Configuração básica do logger (em uma aplicação real, você configuraria de forma mais robusta)
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, "iniciado", "completo", "falhou"
"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 uma chamada API
if "error" in date_range:
raise ValueError("Erro simulado da API de calendário")
events = [
{"title": "Reunião de equipe", "time": "10:00 AM"},
{"title": "Reunião com o 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 a rastreabilidade
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 uma chamada LLM
if "fail_llm" in prompt_text:
raise RuntimeError("Erro simulado da API LLM")
response = f"Resumo 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 por 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("Resumir as principais notícias de hoje...")
final_briefing_prompt = (
f"Criar um briefing diário baseado 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}) # Capturar a memória em caso de erro
raise
# Exemplo de uso
if __name__ == "__main__":
agent = MyAgent()
print(f"\n--- Execução do 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--- Execução do agente {agent_fail.agent_id} (Caso de falha do calendário) ---")
try:
# Simular uma 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 como esperado: {e}")
agent_llm_fail = MyAgent()
print(f"\n--- Execução do agente {agent_llm_fail.agent_id} (Caso de falha LLM) ---")
try:
# Simular uma falha LLM
agent_llm_fail._summarize_with_llm("fail_llm_please")
except Exception as e:
print(f"A execução do agente falhou como esperado: {e}")
Nota como `log_agent_step` captura o ID do agente, o nome do passo, o estado e um dicionário de detalhes pertinentes. Isso facilita o filtragem dos logs por ID do agente, o rastreamento de uma execução única ou a busca de todos os passos “falhou”.
Estratégia 2: Observabilidade centralizada com uma biblioteca/serviço dedicado
“`
Para agentes mais complexos ou ambientes de produção, você rapidamente vai ultrapassar o simples logging em arquivos. É aqui que ferramentas especializadas se destacam. Bibliotecas como `LangSmith` do LangChain (ou similares para outros frameworks) fornecem rastreamento integrado, visualização e depuração para aplicações LLM.
Embora você não utilize LangChain, o conceito é transferível. Você pode criar seu wrapper em torno da execução do seu agente que envia eventos estruturados para um serviço de logging (Datadog, Splunk, stack ELK, ou até mesmo um simples bucket S3 com processamento Lambda). O essencial é padronizar o esquema dos eventos.
Meu projeto Chronos aprimorado agora utiliza uma classe `TraceManager` personalizada que envolve operações críticas. Este gerenciador envia eventos estruturados para um banco de dados local para desenvolvimento e para um serviço de logging na nuvem em produção. Isso me permite ver um “rastro” completo de cada execução do agente, com passos aninhados e todos os dados associados (solicitações, respostas, entradas/saídas das ferramentas, erros).
Estrategia 3: Interceptação das chamadas LLM e das ferramentas
Muitos SDK LLM permitem que você configure callbacks ou interceptores para as chamadas API. Use-os! Em vez de fazer manualmente o logging antes e depois de cada solicitação LLM, você pode ter um único interceptor que loga automaticamente:
- O endpoint API exato utilizado.
- Os cabeçalhos e o corpo da solicitação (particularmente a solicitação).
- Os cabeçalhos e o corpo da resposta (a conclusão).
- A latência.
- Todas as exceções.
Da mesma forma, encapsule suas chamadas às ferramentas. Se você tem uma ferramenta `search_web`, o wrapper deve logar a solicitação de pesquisa, o motor de busca utilizado e os N melhores resultados retornados, junto com todos os erros.
Dicas Acionáveis para o Seu Próximo Projeto de Agente
- Projete primeiro para a Observabilidade: Não considere isso uma reflexão posterior. Pense no que você precisaria para fazer depuração antes de escrever seu primeiro passo do agente.
- Adote o Logging Estruturado: Abandone `print()` e `console.log()` para o código de produção. Use uma biblioteca de logging apropriada e retorne dados estruturados (JSON) para cada evento significativo.
- Trace Tudo que é Importante: Faça o logging do início e do fim de cada passo maior, todas as solicitações e respostas 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, logue seu estado interno ou sua memória naquele momento. Isso fornece um contexto crucial para entender por que falhou.
- Utilize IDs Específicos para o Agente: Atribua um ID único a cada execução do agente (por exemplo, um UUID). Isso permite que você filtre e rastreie facilmente um percurso de execução único através de seus logs.
- Visualize Seus Rastros: Se possível, use ou crie 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 lidar com texto bruto. LangSmith faz isso de forma magnífica, mas até um script personalizado pode gerar uma simples linha do tempo em HTML.
- Monitore os Custos: O uso de tokens LLM representa um custo direto. Logue isso. Isso ajuda você a entender para onde está indo seu dinheiro e a otimizar suas solicitações.
Construir agentes é empolgante, mas construir agentes confiáveis é onde está o verdadeiro trabalho (e o verdadeiro valor). E a confiabilidade começa com a compreensão do que acontece nos bastidores. Minha experiência dolorosa com o projeto Chronos me ensinou bem essa lição. Não espere pelo seu “bug misterioso” para se convencer. Comece a logar de forma inteligente a partir de hoje.
Quais são suas estratégias de observabilidade preferidas para agentes? Escreva-me nos comentários ou nas redes sociais. Estou sempre interessado em saber como os outros enfrentam esses desafios!
🕒 Published: