Por que seus Agentes de IA Precisam de Observabilidade

Você lançou um agente de IA. Ele funciona... às vezes. Um usuário relata uma resposta errada. Outro diz que levou 40 segundos. Um terceiro nota que vazou um endereço de e-mail em sua resposta. Mas você não tem logs, não tem métricas, não há como reproduzir o que aconteceu. Você verifica seu painel de APM e vê HTTP 200s em toda parte. Tudo parece bem. Tudo não está bem.

Essa é a lacuna de observabilidade para agentes de IA, e ela está se ampliando à medida que os agentes são implantados em fluxos de trabalho mais críticos.

O APM Tradicional Não Entende Agentes

Ferramentas de monitoramento de desempenho de aplicativos como Datadog, New Relic e Grafana são construídas para serviços de solicitação-resposta. Elas rastreiam códigos de status HTTP, percentis de latência, taxas de erro e throughput. Essas métricas são importantes, mas não capturam o que torna os agentes diferentes.

A execução de um agente não é uma única solicitação. É um fluxo de trabalho de múltiplas etapas: o LLM raciocina sobre a tarefa, seleciona ferramentas, as chama em sequência ou em paralelo, sintetiza resultados e produz uma saída final. Uma única execução de agente pode envolver 5 chamadas de ferramentas, 3 etapas de inferência de LLM e 12.000 tokens. O APM tradicional vê uma solicitação HTTP bem-sucedida. Ele não pode te dizer:

• Qual chamada de ferramenta na cadeia falhou ou retornou dados inesperados
• Se os passos de raciocínio do LLM foram coerentes
• Quanto custou a execução em tokens e dólares
• Se a qualidade da saída se degradou em comparação com a semana passada
• Se o agente vazou PII em sua resposta

Essas são preocupações específicas de agentes. Elas requerem observabilidade específica de agentes.

O Que a Observabilidade de Agentes Realmente Significa

A observabilidade de agentes repousa sobre três pilares:

1. Rastrear cada passo. Registre todo o caminho de execução: entrada, saída, cada intervalo (chamada de LLM, chamada de ferramenta, etapa de recuperação), latência por intervalo, uso de tokens, custo. Armazene em um formato consultável para que você possa reconstruir qualquer execução após o fato. Esta é a base. Sem rastros estruturados, a depuração é um palpite.

2. Avaliar cada saída. O registro é necessário, mas não suficiente. Você precisa de verificações de qualidade automatizadas que rodem em cada saída: A resposta está completa? É relevante para a entrada? Contém PII? Excedeu seu orçamento de custo? A avaliação transforma rastros brutos em sinais acionáveis. Uma pontuação de 0,4 na verificação de completude te diz algo específico. Um HTTP 200 não diz.

3. Detectar desvios. A qualidade do agente se degrada ao longo do tempo. Atualizações de modelo mudam o comportamento. Edições de prompt têm efeitos colaterais não intencionais. Fontes de dados ficam obsoletas. Você precisa rastrear pontuações e métricas ao longo do tempo e detectar quando elas mudam. Uma queda de 15% nas pontuações de relevância nas últimas 48 horas é um sinal que vale a pena agir.

Apresentando o Iris

O Iris é um servidor de observabilidade de código aberto construído especificamente para agentes de IA. Ele implementa o Modelo de Protocolo de Contexto (MCP), o que significa que qualquer agente compatível com MCP pode descobrir e usar o Iris sem integração de SDK, bibliotecas de cliente ou alterações de código. Você adiciona o Iris à lista de servidores MCP do seu agente, e ele ganha três capacidades: registro de rastros, avaliação de saída e consulta de rastros.

Decisões de design chave:

• Nativo do MCP. O Iris não é uma biblioteca que você importa. É um servidor MCP que expõe ferramentas. Qualquer agente que fale MCP (Claude Desktop, Cursor, agentes personalizados construídos com o SDK MCP) pode usá-lo diretamente.
• Auto-hospedado. Seus dados permanecem em sua infraestrutura. Sem dependência de nuvem, sem processamento de dados de terceiros.
• Impulsionado por SQLite. Sem servidor de banco de dados para gerenciar. Os rastros são armazenados em um arquivo SQLite local em ~/.iris/iris.db. Implantações em produção podem apontar para qualquer caminho.

Três Capacidades

1. Registrar um Rastro

A ferramenta log_trace registra uma execução completa do agente:

{
  "agent_name": "support-bot",
  "input": "Como faço para redefinir minha senha?",
  "output": "Navegue até Configurações > Segurança > Redefinir Senha...",
  "tool_calls": [
    { "tool_name": "search_docs", "input": "redefinição de senha", "output": "..." }
  ],
  "latency_ms": 1200,
  "token_usage": { "prompt_tokens": 450, "completion_tokens": 120, "total_tokens": 570 },
  "cost_usd": 0.0034
}

2. Avaliar a Qualidade da Saída

A ferramenta evaluate_output executa sua saída através de regras configuráveis e retorna uma pontuação:

{
  "output": "Navegue até Configurações > Segurança > Redefinir Senha...",
  "eval_type": "safety",
  "trace_id": "trc_abc123"
}

Resposta:

{
  "score": 1.0,
  "passed": true,
  "rule_results": [