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. Neste guia, explicamos como capturar a telemetria do agente usando frameworks como o LangGraph e o Kit de Desenvolvimento de Agente (ADK) 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 determinista:como o processo de raciocínio de um agente não é determinista, a telemetria é a única maneira confiável de inspecionar as decisões que um agente toma e as ferramentas que ele seleciona.
  • Resolver 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 Agentic Workflows distribuídos.
  • Oferecer suporte à governança e validar o tráfego:a telemetria permite visualizar os 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:coletar comandos, respostas e o 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 possam ser armazenados, consultados e analisados. Por exemplo, quando sua instrumentação envia telemetria para o projeto do Google Cloud , é possível usar o Google Cloud Observability para visualizar e analisar esses dados.

O Cloud Trace extrai automaticamente eventos de períodos gravados por aplicativos de IA generativa quando esses períodos estão em conformidade com as convenções semânticas para períodos e eventos. Para 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, um projeto de código aberto que fornece um framework unificado para instrumentação de aplicativos. As amostras de instrumentação listadas neste documento usam o OpenTelemetry.

Também recomendamos que você armazene os comandos e as respostas em um bucket do Cloud Storage em vez de em 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?.

Amostras de instrumentação

Para começar a usar a instrumentação de agentes, consulte os seguintes aplicativos de exemplo e guias:

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

    • Armazene comandos e respostas em um bucket do Cloud Storage.
    • Confira os comandos e as respostas na página Trace Explorer.
    • Analisar comandos e respostas com o BigQuery.
    • Avalie comandos e respostas com o SDK da Vertex AI para Python.

  • Instrumentar um agente ReAct do LangGraph 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 inclui um link para um aplicativo de amostra que pode ser baixado e executado. O aplicativo de exemplo coleta comandos de texto e respostas.

  • Instrumentar aplicativos do 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 inclui um link para um aplicativo de exemplo que pode ser baixado e executado. O aplicativo de exemplo coleta comandos de texto e respostas.

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