Instrumentar aplicativos do ADK com o OpenTelemetry

Este documento explica como instrumentar um agente de IA criado com o framework do Kit de Desenvolvimento de Agente (ADK). O framework do ADK inclui instrumentação do OpenTelemetry que coleta telemetria das principais ações do agente. Quando você ativa a instrumentação integrada, ela envia informações como comandos de texto e respostas do agente ao seu projeto Google Cloud . Este documento descreve as mudanças necessárias e fornece um link para um aplicativo de exemplo.

Os aplicativos que usam o ADK também podem coletar comandos e respostas multimodais. Este documento descreve como coletar comandos e respostas de texto. Se você quiser coletar dados multimodais, será necessário fazer mais configurações. Para mais informações, consulte Coletar e conferir comandos e respostas multimodais.

A observabilidade padrão fornecida pelo ADK pode não ser suficiente para o caso de uso do seu aplicativo. Você pode adicionar outras bibliotecas de instrumentação usando o OpenTelemetry para capturar a telemetria de outras partes do app ou sua própria instrumentação personalizada para capturar dados específicos do aplicativo e ter uma capacidade de observação mais refinada. Por exemplo, no seu aplicativo, você pode escrever um código de instrumentação para:

• Acompanhar o consumo de recursos das ferramentas invocadas pelo agente.
• Rastreie falhas de validação específicas do aplicativo, violações de regras de negócios ou mecanismos personalizados de recuperação de erros.
• Acompanhe as pontuações de qualidade das respostas do agente com base nos critérios específicos do seu domínio.

Observação: este documento pressupõe que você está usando um framework ADK com a versão 1.17.0 ou mais recente.

Instrumentar seu aplicativo de IA generativa para coletar telemetria

Para instrumentar seu agente de IA e coletar dados de registro, métricas e rastreamento, faça o seguinte:

1. Instale os pacotes do OpenTelemetry.
2. Configure seu ambiente do ADK.

O restante desta seção descreve as etapas anteriores.

Instalar pacotes do OpenTelemetry

Adicione os seguintes pacotes de instrumentação e exportação do OpenTelemetry:

uv add 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Os dados de registro são enviados ao seu projeto Google Cloud usando a API Cloud Logging ou a API Cloud Monitoring. A biblioteca opentelemetry-exporter-gcp-logging invoca endpoints na API Cloud Logging.

Os dados de métricas não são coletados. Normalmente, os aplicativos que não usam uma solução baseada em coletor incluem a biblioteca opentelemetry-exporter-gcp-monitoring. Essa biblioteca invoca endpoints na API Cloud Monitoring.

Os dados de rastreamento são enviados para Google Cloud usando a API Telemetry (OTLP), que implementa o protocolo de linha do OpenTelemetry. A biblioteca opentelemetry-exporter-otlp-proto-grpc invoca o endpoint de API de telemetria (OTLP).

Os dados de rastreamento são armazenados em um formato geralmente consistente com os arquivos proto definidos pelo protocolo de linha do OpenTelemetry. No entanto, os campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento. Para saber mais sobre o formato de armazenamento, consulte Esquema para dados de rastreamento.

Configurar o ambiente do ADK

As versões 1.17.0 e mais recentes do framework ADK incluem suporte integrado ao OpenTelemetry e envio de dados de telemetria do OpenTelemetry para Google Cloud Observability. Para ativar isso, configure seu ambiente do ADK:

• Se você executar o aplicativo com o comando adk web, inclua a flag --otel_to_cloud.

• No arquivo opentelemetry.env, defina as seguintes variáveis de ambiente:

  OTEL_SERVICE_NAME='adk-sql-agent'
  OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'
  

• Configure o OpenTelemetry para usar as convenções semânticas mais recentes para IA generativa.

  OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
  

• Configure o OpenTelemetry para anexar mensagens como eventos.

  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'
  

  Observação: não defina o valor dessa variável como true. Ao usar as convenções semânticas mais recentes, definir o valor dessa variável como true resulta em uma configuração inválida. Portanto, os dados de registro e rastreamento não são coletados.

  Para mais informações sobre os valores enumerados permitidos, consulte genai/types.py.

• Recomendamos que você também adicione a seguinte variável de ambiente ao arquivo opentelemetry.env:

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
  

  Essa variável de ambiente faz o seguinte:

  • Impede que a instrumentação do ADK anexe atributos de período que excedam o limite de tamanho do atributo.
  • Impede que informações de identificação pessoal (PII) sejam anexadas a intervalos como atributos.

• Talvez seja necessário definir outras variáveis de ambiente. Por exemplo, se você fizer a implantação na Gemini Enterprise Agent Platform, também é preciso definir a seguinte variável de ambiente:

  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
  

Baixar e executar o aplicativo de exemplo

Este exemplo de código implementa um agente de IA generativa criado com o ADK. O agente é instrumentado com o OpenTelemetry e configurado para enviar métricas, traces e registros ao seu projeto Google Cloud . A telemetria enviada ao seu projeto inclui comandos e respostas de IA generativa.

Persona do agente do ADK

O agente de IA generativa é definido como um especialista em SQL com acesso total a um banco de dados SQLite efêmero. O agente é criado com o Kit de Desenvolvimento de Agente e acessa um banco de dados usando o SQLDatabaseToolkit. O banco de dados está inicialmente vazio.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. Para receber as permissões necessárias para que o aplicativo de exemplo grave dados de registros, métricas e rastreamentos, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

   • Gravador de traces de telemetria do Cloud (roles/telemetry.tracesWriter)
   • Gravador de registros (roles/logging.logWriter)
   • Gravador de métricas do Monitoring (roles/monitoring.metricWriter)
   • Usuário da Vertex AI (roles/aiplatform.user)

   Essas permissões são suficientes se você executar a amostra no Cloud Shell, em recursos Google Cloud ou em um ambiente de desenvolvimento local.

   Importante: os aplicativos de Production geralmente dependem de uma conta de serviço para fornecer as credenciais necessárias para gravar dados de registro, métricas e rastreamento. Nesses cenários, conceda os papéis anteriores à conta de serviço.

2. Verifique se você especificou um projeto de cota. A API Vertex AI (aiplatform.googleapis.com) exige que um projeto de cota seja especificado. Para mais informações, consulte Definir o projeto de cota. Por exemplo, o comando a seguir pode definir um projeto de cota.

   gcloud config set billing/quota_project PROJECT_ID

Inicie o aplicativo

Para iniciar o aplicativo de exemplo, faça o seguinte:

1. No Cloud Shell, clone o repositório:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. Acesse o diretório da amostra:

   cd opentelemetry-samples/python/adk-sql-agent
   

   A amostra contém um arquivo .env que define duas variáveis de ambiente. Uma variável controla quais endpoints o SDK usa. A outra variável define um local.

   Se preferir usar um modelo diferente, edite main.py. Verifique se o modelo selecionado é compatível com o local especificado no arquivo .env. Para informações sobre modelos, consulte Modelos do Google.

3. Crie um ambiente virtual e execute a amostra:

   uv run --env-file opentelemetry.env adk web --otel_to_cloud
   

   O aplicativo vai mostrar uma mensagem semelhante a esta:

   Appplication startup complete
   Uvicorn running on http://127.0.0.1:8080
   

4. Para interagir com o agente, selecione o URL mostrado na saída da etapa anterior.

5. Expanda Selecionar um app e escolha sql_agent na lista de agentes.

   Observação: este aplicativo requer o compartilhamento de recursos entre origens (CORS). Se você inserir um comando e o CORS for bloqueado, o aplicativo vai mostrar a mensagem Failed to create session, e a linha de comando vai indicar que os comandos foram rejeitados, POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   Para ativar o CORS, adicione o seguinte ao comando que executa o exemplo:
   

   --allow_origins="regex:.*"

Interagir com o agente

Para interagir com o agente, faça uma pergunta ou dê um comando. Por exemplo, você pode perguntar:

What can you do for me ?

Da mesma forma, como o sql_agent tem a personalidade de um especialista em SQL, você pode pedir para ele criar tabelas para seus aplicativos e escrever consultas para operar nas tabelas criadas. O agente só pode criar um banco de dados efêmero com suporte de um arquivo .db criado na máquina que executa o aplicativo.

A seguir, ilustramos um exemplo de interação entre o sql_agent e o usuário:

As ações realizadas por agentes de IA generativa não são deterministas. Por isso, você pode receber uma resposta diferente para o mesmo comando.

Sair do aplicativo

Para sair do aplicativo, insira Ctrl-C no shell usado para iniciar o aplicativo.

Visualizar traces, métricas e registros

Nesta seção, descrevemos como visualizar eventos de IA generativa.

Antes de começar

Para ter as permissões necessárias para visualizar seus dados de registros, métricas e rastreamentos, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Visualizador de registros (roles/logging.viewer)
• Leitor do Monitoring (roles/monitoring.viewer)
• Usuário do Cloud Trace (roles/cloudtrace.user)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ver telemetria

Para conferir os eventos de IA generativa criados pelo aplicativo, use a página Explorador de rastreamentos:

1. No console Google Cloud , acesse a página Explorador de traces:

   Acessar o Explorador de traces

   Também é possível encontrar essa página usando a barra de pesquisa.

2. Na barra de ferramentas, selecione Adicionar filtro, Nome do intervalo e call_llm.

   A imagem a seguir ilustra a página do Trace Explorer após a filtragem dos dados:

   

   Se você nunca usou o Cloud Trace, o Google Cloud Observability precisa criar um banco de dados para armazenar seus dados de rastreamento. A criação do banco de dados pode levar alguns minutos. Durante esse período, nenhum dado de rastreamento fica disponível para visualização.

3. Para analisar os dados de período e de registro, selecione um período na tabela Períodos.

   A página Detalhes é aberta. Essa página mostra o rastreamento associado e seus intervalos. A tabela na página mostra informações detalhadas sobre o intervalo selecionado. Essas informações incluem o seguinte:

   • A guia Entradas/Saídas mostra eventos de agentes de IA generativa. Para saber mais sobre esses eventos, consulte Ver eventos da IA generativa.

     A captura de tela a seguir ilustra um rastreamento em que um período tem o nome call_llm. Esse intervalo invoca o LLM (modelo de linguagem grande) que alimenta esse agente. Neste exemplo, é o Gemini. O intervalo do Gemini inclui eventos de IA generativa:

     

   • A guia Registros e eventos lista entradas de registro e eventos associados ao período. Se quiser ver os dados de registro na Análise de registros, selecione Ver registros na barra de ferramentas dessa guia.

     Os dados de registro incluem a resposta do sql_agent. Por exemplo, para a execução de amostra, o payload JSON inclui o seguinte conteúdo:

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "parts": [
             0: {
               "text": "Now I can create the table."
             }
             1: {1}
             ],
           "role": "model"
         }
       },
       ...
     }
     

A amostra é instrumentada para enviar dados de métricas ao projeto Google Cloud , mas não gera nenhuma métrica.