Observabilidade para desenvolvedores de agentes de IA

Se você desenvolve agentes de IA, pode instrumentar seus aplicativos com o OpenTelemetry para observar como seus agentes raciocinam, chamam ferramentas e respondem a comandos. Este guia explica como capturar a telemetria do agente usando frameworks como o LangGraph e o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) e como analisar comandos e respostas multimodais no Cloud Trace.

Instrumentar agentes para entender o comportamento deles

Ao desenvolver ou gerenciar aplicativos de IA generativa, os dados de telemetria capturam as etapas de raciocínio, as chamadas de ferramentas e as interações externas dos seus agentes autônomos. Esses dados são úteis pelos seguintes motivos:

  • Entender o comportamento não determinístico:como o processo de raciocínio de um agente não é determinístico, a telemetria é a única maneira confiável de inspecionar as decisões que um agente toma e as ferramentas que ele seleciona.
  • Solucionar problemas e diagnosticar erros:os traces ajudam a identificar solicitações de API com falha, loops de execução infinitos e gargalos de latência em fluxos de trabalho de agentes distribuídos.
  • Oferecer suporte à governança e validar o tráfego: a telemetria permite visualizar fluxos de comunicação, como na topologia do aplicativo, para verificar se os agentes se comunicam apenas com agentes autorizados, servidores MCP e endpoints externos.
  • Avaliar a qualidade e o custo da saída:a coleta de comandos, respostas e uso de tokens ajuda a avaliar a precisão do modelo, detectar alucinações e otimizar o consumo de recursos.

Como instrumentar seus aplicativos de IA generativa

A instrumentação do aplicativo envolve a geração de telemetria e o envio dela para um destino em que os dados podem ser armazenados, consultados e analisados. Por exemplo, quando a instrumentação envia telemetria para seu Google Cloud projeto, é possível usar Google Cloud Observability para visualizar e analisar esses dados.

O Cloud Trace extrai automaticamente eventos de intervalos gravados por aplicativos de IA generativa quando esses intervalos estão em conformidade com as convenções semânticas de intervalos e eventos. Para mais informações sobre essas convenções, consulte os seguintes documentos:

O Cloud Trace também pode mostrar comandos e respostas multimodais. Nesse cenário, os comandos e as respostas não são anexados aos dados de trace. Em vez disso, eles são armazenados em um bucket do Cloud Storage. Para saber mais sobre essa configuração, consulte Coletar e visualizar comandos e respostas multimodais.

Práticas recomendadas

Recomendamos que você instrumente seu aplicativo com o OpenTelemetry, que é um projeto de código aberto que fornece um framework unificado para instrumentação de aplicativos. Os exemplos de instrumentação listados neste documento usam o OpenTelemetry.

Também recomendamos que você armazene seus comandos e respostas em um bucket do Cloud Storage em vez de uma entrada de registro:

  • Você tem controle refinado sobre o conteúdo no bucket do Cloud Storage. Por exemplo, é possível excluir conversas individuais armazenadas em um bucket. No entanto, não é possível excluir entradas de registro individuais.

  • Os buckets do Cloud Storage podem armazenar objetos muito maiores do que o tamanho máximo de uma entrada de registro, que é limitado a 256 KiB. O Cloud Logging responde com um erro INVALID_ARGUMENT e descarta os dados se eles excederem o tamanho máximo da entrada de registro. Se o comando for concluído sem erros, mas os campos individuais excederem os limites de tamanho, o Cloud Logging vai truncar esses dados.

Para mais informações sobre o OpenTelemetry, consulte O que é o OpenTelemetry?.

Exemplos de instrumentação

Para começar a instrumentar o agente, consulte os seguintes aplicativos e guias de exemplo:

  • Coletar e visualizar comandos e respostas multimodais descreve como configurar um agente LangGraph ReAct ou um agente de IA generativa criado com o ADK para coletar comandos e respostas multimodais. Ele também descreve como fazer o seguinte:

    • Armazenar comandos e respostas em um bucket do Cloud Storage.
    • Visualizar comandos e respostas com a página Trace Explorer.
    • Analisar comandos e respostas com o BigQuery.
    • Avaliar comandos e respostas com o SDK da Vertex AI para Python.

  • Instrumentar um agente LangGraph ReAct com o OpenTelemetry descreve como usar o OpenTelemetry para instrumentar um aplicativo de IA generativa que usa o framework LangChain ou LangGraph. Ele também tem um link para um aplicativo de exemplo que pode ser baixado e executado. O aplicativo de exemplo coleta comandos e respostas de texto.

  • Instrumentar aplicativos ADK com o OpenTelemetry descreve como ativar a instrumentação integrada que coleta telemetria das principais ações do agente. A telemetria inclui comandos de texto e respostas do agente. Ele também tem um link para um aplicativo de exemplo que pode ser baixado e executado. O aplicativo de exemplo coleta comandos e respostas de texto.

  • Investigar chamadas de MCP usando o Trace descreve como configurar seu aplicativo para transmitir o contexto de trace para servidores MCP remotos do Google Cloud, o que permite que esses servidores anexem intervalos a um trace.