Olá a todos, Leo aqui do agntdev.com. Espero que todos estejam tendo uma semana produtiva!
Hoje, quero explorar algo que tem me preocupado bastante ultimamente, especialmente desde que comecei a trabalhar em alguns projetos pessoais que envolvem fluxos de trabalho de agentes mais complexos e em várias etapas. Falamos muito sobre a construção de agentes, sobre os LLMs em si, e sobre as coisas legais que eles podem fazer. Mas e quanto ao aspecto menos glamouroso, mas absolutamente crucial, de garantir que nossos agentes funcionem de maneira confiável e eficiente ao longo do tempo?
Mais especificamente, estou falando sobre a observabilidade dos agentes. Não se trata apenas de logging; trata-se de realmente entender o que seu agente está fazendo, por que ele está fazendo, e detectar problemas antes que se tornem incontrolá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 às cegas é uma receita para o desastre. Aprendi isso da maneira difícil, como vou explicar.
O “Erro Misterioso” Que Me Ensinou Tudo
Há alguns meses, eu estava desenvolvendo um agente de assistente pessoal. Chamemos de “Projeto Chronos.” Sua função era monitorar meu calendário, meus feeds de notícias e canais específicos do Slack, e então propor proativamente horários de reunião, resumir atualizações importantes, ou até mesmo redigir respostas iniciais para perguntas comuns. Um funcionamento bastante padrão na superfície.
Eu o construí, testei com alguns cenários, e parecia funcionar corretamente. O configurei para operar durante a noite, pensando que acordaria com um resumo perfeitamente organizado. Em vez disso, acordei com… nada. Ou melhor, um resumo parcial que terminou abruptamente, seguido de uma mensagem de erro críptica nos meus logs de sistema dizendo basicamente “algo falhou.”
Depurar isso foi um pesadelo. Chronos deveria fazer várias coisas: recuperar eventos do calendário, consultar uma API de notícias, acessar uma API do Slack, processar os dados, e então gerar um resumo. Qual etapa falhou? Por quê? Ele chegou a tentar todas as etapas? Foi um limite de taxa da API? Um prompt malformado? Um tempo limite? Eu não fazia ideia.
Meu logging inicial era básico: “Etapa X iniciada,” “Etapa Y concluída,” e então a saída final ou uma erro. Isso não era suficiente. Era como tentar diagnosticar um problema em um carro só sabendo que ele ligou e depois parou, sem nenhuma informação sobre a temperatura do motor, a pressão do combustível, ou falhas elétricas.
Essa experiência ressaltou 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 tardia; é um componente fundamental.
Além do Logging Básico: O Que Significa “Observabilidade” Para Agentes?
Para mim, a observabilidade dos agentes se divide em algumas áreas principais, cada uma oferecendo uma perspectiva diferente sobre como seu agente funciona:
1. Monitoramento da Execução Etapa por Etapa
Isso é o mais crítico. Você precisa saber exatamente o que seu agente está fazendo a cada etapa 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 para o LLM para resumir as informações do calendário.
- A resposta do LLM.
- Todas as ferramentas chamadas, com suas entradas e saídas.
- As mensagens de erro, não apenas “algo falhou,” 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 depois “Resumindo dados do calendário…” sem nada entre os dois. 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 dá, está navegando às cegas. Isso inclui:
- 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 de ferramentas que ele decidiu fazer.
- Uso de tokens (entrada, saída, total) para monitoramento de custos e análise de desempenho.
Isso é crucial para a engenharia de prompts. Se um agente dá respostas sem sentido, ver o prompt exato que recebeu ajuda a depurar se o contexto de entrada estava incorreto ou se o prompt em si estava mal estruturado.
3. Monitoramento de Chamadas de Ferramentas
Os agentes frequentemente interagem com ferramentas externas ou APIs. Cada interação representa um ponto de falha potencial ou um 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.
Para Chronos, se ele tentasse chamar a API do Slack para postar um resumo, eu precisaria saber o canal alvo, 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 bloco de notas, uma memória, uma lista de fatos que eles reuniram. Capturar regularmente esse estado pode ser incrivelmente útil para o depuração. Se um agente ficar preso em um loop ou tomar uma decisão ruim, ver seus “pensamentos” internos em vários momentos pode revelar onde sua compreensão saiu dos trilhos.
Isto diz respeito menos ao logging de cada mudança de variável e mais à captura dos estados chave de tomada de decisão. Para Chronos, isso poderia ser “Compreensão atual da programação do usuário,” ou “Pontos chave dos feeds de notícias até agora.”
Abordagens Práticas: Integrando a Observabilidade
Ok, como colocamos isso em prática sem nos afogar nos logs? Aqui estão algumas estratégias práticas e trechos 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). É crucial aumentar 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:
import logging
import json
import uuid
from datetime import datetime
# Configuração básica do logger (em uma aplicação real, você a configuraria de forma 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 uma chamada de 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 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 trilha
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 pela 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 falha
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}")
Note como `log_agent_step` captura o ID do agente, o nome da etapa, o status e um dicionário de detalhes relevantes. Isso facilita o filtragem dos logs por ID do agente, o acompanhamento de uma execução única ou a pesquisa de 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 ultrapassará o simples registro de arquivos. É aqui que ferramentas especializadas se destacam. Bibliotecas como `LangSmith` de LangChain (ou similares para outros frameworks) fornecem rastreamento integrado, visualização e depuração para aplicações LLM.
Mesmo que você não utilize LangChain, o conceito é transferível. Você pode criar sua própria camada em torno da execução do seu agente que envia eventos estruturados a um serviço de registro (Datadog, Splunk, stack ELK, ou mesmo um simples bucket S3 com processamento Lambda). O essencial é padronizar o esquema dos eventos.
Meu projeto Chronos aprimorado agora utiliza uma classe personalizada `TraceManager` que envolve as operações críticas. Esse gerenciador envia eventos estruturados para um banco de dados local durante o desenvolvimento e para um serviço de registro na nuvem em produção. Isso me permite ver uma “trilha” completa de cada execução de agente, com etapas aninhadas e todos os dados associados (prompt, respostas, entradas/saídas de ferramentas, erros).
Estratégia 3: Interceptação das chamadas LLM e ferramentas
Vários SDK LLM permitem que você configure callbacks ou interceptors para as chamadas de API. Use-os! Em vez de registrar manualmente antes e depois de cada prompt LLM, você pode ter um único interceptor que registra automaticamente:
- O endpoint da API exato utilizado.
- Os cabeçalhos e o corpo da requisição (especialmente o prompt).
- Os cabeçalhos e o corpo da resposta (a conclusão).
- A latência.
- Todas as exceções.
Da mesma forma, encapsule suas chamadas de ferramentas. Se você tem uma ferramenta `search_web`, o wrapper deve registrar a requisição de pesquisa, o motor de busca utilizado e os N melhores resultados retornados, além de quaisquer erros.
Dicas Ação para Seu Próximo Projeto de Agente
- Projete primeiro para a Observabilidade: Não considere isso como uma reflexão posterior. Pense no que você precisa para debugar antes mesmo de escrever seu primeiro passo de agente.
- Adoção do Registro Estruturado: Abandone `print()` e `console.log()` para o código de produção. Use uma biblioteca de registro apropriada e produza dados estruturados (JSON) para cada evento significativo.
- Registre Tudo que é Importante: Registre o início e o fim de cada etapa principal, todos os prompts e respostas LLM (incluindo os parâmetros e contagens de tokens), e cada chamada de ferramenta com suas entradas e saídas.
- Capturar o Estado em Caso de Falha: Quando um agente falha, registre seu estado interno ou memória naquele momento. Isso fornece um contexto crucial para entender por que falhou.
- Use IDs Específicos do Agente: Atribua um ID único a cada execução de agente (por exemplo, um UUID). Isso permite filtrar e acompanhar facilmente um caminho de execução único através de seus logs.
- Visualize Suas Trilhas: Se possível, utilize 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 cru. LangSmith faz isso de forma magnífica, mas até mesmo um script personalizado pode tornar um simples cronograma HTML.
- Monitore os Custos: O uso de tokens LLM representa um custo direto. Registre isso. Isso ajuda a entender para onde vai seu dinheiro e a 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 por saber o que está acontecendo nos bastidores. Minha experiência dolorosa com o projeto Chronos me ensinou bem essa lição. Não espere seu próprio “bug misterioso” para convencê-lo. Comece a registrar inteligentemente 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: