Instrumentar aplicativos de IA generativa

Este documento descreve o benefício de instrumentar seus aplicativos de IA generativa. Ele também resume como instrumentar um aplicativo que usa os frameworks LangGraph ou Kit de Desenvolvimento de Agente (ADK). Os dois frameworks permitem coletar e visualizar comandos e respostas multimodais.

Sobre agentes de IA generativa

Os aplicativos que usam IA generativa dependem de agentes para concluir tarefas ou alcançar metas. Os agentes são aplicativos que concluem tarefas ou buscam metas em nome de um usuário. Por exemplo, um agente de IA generativa pode navegar em um site e emitir comandos de API. Esses comandos de API podem recuperar informações ou realizar uma ação.

Os agentes agem de forma autônoma e usam o raciocínio para determinar como decompor uma meta ou tarefa em subtarefas e, em seguida, determinar quais ferramentas usar para realizar essas subtarefas. No contexto da IA generativa, as ferramentas determinam como o agente pode interagir com o ambiente. Por exemplo, um agente pode ter uma ferramenta que permite emitir comandos de API.

Para saber mais sobre agentes, consulte o seguinte:

Por que instrumentar seus aplicativos de IA generativa

A instrumentação dos aplicativos de IA generativa é a única maneira de entender o raciocínio usado pelos agentes autônomos. Esse processo de raciocínio não é determinístico.

Ao instrumentar um aplicativo de IA generativa, os dados de telemetria incluem as decisões e ações dos agentes. Você pode usar esses dados para validar ou melhorar seu aplicativo.

Como instrumentar seus aplicativos de IA generativa

A instrumentação do aplicativo envolve a geração de telemetria e o envio dela para o local de armazenamento, consulta e análise dos dados. Por exemplo, quando sua instrumentação envia telemetria para seu Google Cloud projeto, você pode usar Google Cloud Observability para visualizar e analisar esses dados.

Práticas recomendadas

O Google recomenda instrumentar seu aplicativo com o OpenTelemetry, que é um projeto de código aberto que fornece um framework unificado para instrumentação de aplicativos. Os exemplos listados neste documento dependem do OpenTelemetry.

O Google também recomenda armazenar 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 dados se os dados recebidos 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.

Exemplos de instrumentação

Para informações de instrumentação, consulte os seguintes documentos:

  • 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:

    • 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 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 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 períodos a um trace.

Como visualizar seus comandos e respostas

O Cloud Trace está configurado para extrair eventos de períodos gravados por aplicativos de IA generativa, desde que os períodos estejam em conformidade com as convenções semânticas do OpenTelemetry para períodos de IA generativa e incluam atributos ou eventos que sigam as convenções semânticas para eventos de IA generativa.

O Cloud Trace também pode mostrar comandos e respostas multimodais. Nesse cenário, os comandos e 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.