Observabilidade de agentes de IA com LangChain4j

Introdução

Estamos vivendo uma onda no desenvolvimento de software impulsionada pelo uso de IA generativa e, mais recentemente, por agentes de IA capazes de tomar decisões, orquestrar chamadas a modelos e interagir com ferramentas externas.

Esses agentes vão além de simples integrações com LLMs. Eles executam fluxos dinâmicos, fazem múltiplas chamadas ao modelo, utilizam ferramentas e tomam decisões com base no contexto. Esse comportamento os aproxima muito mais de sistemas distribuídos.

Com isso, à medida que começamos a levar esses agentes para ambientes corporativos, surge um requisito essencial que não pode ser ignorado: observabilidade e monitoramento.

De forma simplificada:

• Monitoramento está relacionado a acompanhar métricas do sistema, como latência, taxa de erro, uso de recursos e disponibilidade. Ele responde perguntas como "o sistema está saudável?".
• Observabilidade está relacionado a capacidade de entender o comportamento interno do sistema a partir de sinais externos (métricas, logs e traces). Ela permite responder perguntas como "por que o sistema está se comportando dessa forma?".

Precisamos dessa visibilidade para poder responder perguntas como:

• Quantas chamadas ao modelo foram feitas?
• Qual foi o custo em tokens dessa operação?
• Onde está o gargalo de performance?

Esse desafio se torna ainda mais difícil em cenários com multiagentes, onde diferentes agentes interagem entre si, ampliando a complexidade do fluxo e tornando a análise ainda mais difícil sem ferramentas adequadas.

Neste artigo, vamos focar na observabilidade de agentes de IA, explorando como instrumentar e monitorar suas execuções utilizando o LangChain4j em conjunto com sua extensão para o Quarkus, e como visualizar essas informações de forma prática através de dashboards no Grafana.

O que observar em agentes de IA

Diferente de aplicações tradicionais, onde observamos requisições HTTP, bancos de dados e filas, agentes de IA introduzem uma nova complexidade.

Abaixo estão os principais pontos que devem ser observados:

• Latência de cada chamada ao modelo.
• Consumo de tokens de entrada.
• Consumo de tokens de saída.

As métricas são fundamentais em ambientes corporativos, onde o custo precisa ser previsível e controlado.

Usando o LangChain4j com Quarkus

O LangChain4j já fornece mecanismos nativos para observar esses aspectos através de eventos do ciclo de vida da execução do agente, como:

• Início da execução
• Requisição ao modelo
• Resposta recebida
• Execução de ferramentas
• Erros

Na próxima seção, vamos explorar como esses eventos funcionam na prática e como utilizá-los para instrumentar nossos agentes.

Expondo métricas com LangChain4j no Quarkus

Uma das grandes vantagens de utilizar o Quarkus em conjunto com o LangChain4j é a facilidade de integrar observabilidade utilizando padrões já consolidados no ecossistema Java.

Para expor métricas da aplicação (incluindo aquelas relacionadas à execução de agentes de IA), basta incluir a extensão de Micrometer no projeto para que métricas passem a ser expostas automaticamente.

Exemplo de trecho do pom.xml:

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-micrometer</artifactId>
    </dependency>

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

Após incluir essas dependências, o Quarkus automaticamente expõe as métricas da aplicação no endpoint:

Por padrão, elas ficam disponíveis em:

/q/metrics.

Como vamos utilizar o Prometheus, esse comportamento é exatamente o que precisamos. O endpoint já expõe as métricas no formato nativo do Prometheus, permitindo que ele realize o scraping diretamente, sem necessidade de adaptações ou conversões adicionais.

Com essa configuração, qualquer métrica registrada via Micrometer, incluindo as geradas pelo LangChain4j, estará disponível para coleta.

Configurando Prometheus e Grafana

Para visualizar as métricas coletadas, vamos utilizar duas ferramentas bastante conhecidas de observabilidade:

• Prometheus: responsável por coletar (scraping) e armazenar as métricas.
• Grafana: utilizado para visualização e criação de dashboards.

Neste artigo, não vamos nos aprofundar na configuração detalhada dessas ferramentas, pois o foco será a construção dos dashboards para agentes de IA.

Configurando o Grafana e Prometheus

Para que o Prometheus consiga coletar as métricas expostas pelo Quarkus, precisamos apenas configurar um job apontando para o endpoint /q/metrics.

Exemplo de configuração (prometheus.yml):

scrape_configs:
  - job_name: 'quarkus-app'
    metrics_path: '/q/metrics'
    static_configs:
      - targets: ['localhost:8080']

Com isso, o Prometheus já será capaz de coletar todas as métricas expostas pela aplicação.

Para facilitar, você pode utilizar uma imagem pronta que já inclui Prometheus, Grafana e outras ferramentas integradas. Uma ótima opção é a imagem
grafana/otel-lgtm.

Dashboards no Grafana para agentes de IA

Em aplicações corporativas, é comum termos diversos dashboards cobrindo diferentes aspectos do sistema, como:

• Métricas de APIs REST (latência, throughput, erros)
• Banco de dados (conexões, tempo de query)
• Infraestrutura (CPU, memória)
• Métricas da JVM (GC, threads, heap)

Esses dashboards continuam sendo fundamentais e fazem parte da base de qualquer estratégia de observabilidade.

No entanto, ao introduzirmos agentes de IA, surge uma nova complexidade que precisa ser monitorada. Aqui, vamos focar exclusivamente em como observar agentes de IA através de dashboards no Grafana.

Métricas disponíveis com LangChain4j no Quarkus

Utilizando a extensão do LangChain4j com o Quarkus, as seguintes métricas estão disponíveis:

• langchain4j_aiservices_counted_total
  
  Total de execuções de serviços de IA (quantidade de chamadas realizadas)

• langchain4j_aiservices_timed_seconds_count
  
  Número de execuções monitoradas para cálculo de tempo

• langchain4j_aiservices_timed_seconds_sum
  
  Soma total do tempo gasto nas execuções

• langchain4j_aiservices_timed_seconds_max
  
  Tempo máximo registrado em uma execução

Construindo dashboards no Grafana

Com base nas métricas expostas pelo LangChain4j, podemos construir os dashboards no Grafana.

A seguir estão alguns exemplos de painéis e as métricas utilizadas em cada um deles:

AI Services (visão geral)

Um painel do tipo tabela pode ser utilizado para exibir uma visão geral dos serviços de IA.

Métrica utilizada:

• langchain4j_aiservices_counted_total

Com essa métrica, conseguimos:

• Identificação dos agentes de IA

Input Token Usage Total

Esse painel exibe o total de tokens de entrada (input) consumidos pelos agentes de IA.

Métrica utilizada:

gen_ai_client_token_usage_total{gen_ai_token_type="input"}

Output Token Usage Total

Esse painel exibe o total de tokens de saída (output) gerados pelos agentes de IA.

Métrica utilizada:

gen_ai_client_token_usage_total{gen_ai_token_type="output"}

AI Estimated Cost Total

Esse painel exibe o custo estimado total das interações com os modelos de IA ao longo do tempo.

Métrica utilizada:

gen_ai_client_estimated_cost_total

AI Client Operation Duration (latência média)

Esse painel exibe a latência média das chamadas ao modelo (LLM) realizadas pelos agentes de IA.

Métrica utilizada:

sum by (service_name) (
  rate(gen_ai_client_operation_duration_seconds_sum[5m])
)
/
sum by (service_name) (
  rate(gen_ai_client_operation_duration_seconds_count[5m])
)

AI Services Duration (latência média do agente)

Esse painel exibe a latência média de execução dos serviços de IA, ou seja, o tempo total que um agente leva para processar uma requisição completa.

Métrica utilizada:

sum by (aiservice) (
  rate(langchain4j_aiservices_timed_seconds_sum[5m])
)
/
sum by (aiservice) (
  rate(langchain4j_aiservices_timed_seconds_count[5m])
)

Você pode importar diretamente o dashboard e adaptar conforme sua necessidade:

👉 https://github.com/denis-arruda/langchain4j-grafana-dashboard

Considerações finais

Aplicações que utilizam agentes de IA, e principalmente cenários com multiagentes, trazem uma nova complexidade para o desenvolvimento de software.

Esses sistemas se comportam, na prática, como aplicações distribuídas, com fluxos dinâmicos e múltiplas interações com modelos de linguagem. Isso torna ainda mais desafiador entender seu comportamento em produção.

Por esse motivo, observabilidade deixa de ser um diferencial e passa a ser um requisito essencial, especialmente em ambientes corporativos.

Ao longo deste artigo, vimos é simples dar os primeiros passos.

A integração entre Prometheus e Grafana é bastante natural e já consolidada no ecossistema Java, o que reduz significativamente o esforço de adoção.

Além de construir agentes inteligentes, é preciso entender como eles se comportam em produção.