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, na sigla em inglês). O framework do ADK inclui a 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 para seu Google Cloud projeto. Este documento descreve as mudanças necessárias e fornece um link para um aplicativo de amostra.

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ária uma configuração adicional. Para mais informações, consulte Coletar e visualizar 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 telemetria de outras partes do seu app ou sua própria instrumentação personalizada para capturar dados específicos do aplicativo e ter uma observabilidade mais detalhada. Por exemplo, no seu aplicativo, você pode escrever um código de instrumentação para:

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

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

Instrumentar o aplicativo de IA generativa para coletar telemetria

Para instrumentar seu agente de IA para coletar dados de registro, métrica e trace, 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 os pacotes do OpenTelemetry

Adicione os seguintes pacotes de instrumentação e exportador 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 para seu Google Cloud projeto 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 opentelemetry-exporter-gcp-monitoring biblioteca. Essa biblioteca invoca endpoints na API Cloud Monitoring.

Os dados de trace 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 Telemetry (OTLP).

Os dados de trace são armazenados em um formato que é 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 trace.

Configurar seu ambiente do ADK

As versões 1.17.0 e mais recentes do framework do ADK incluem suporte integrado para o OpenTelemetry e o envio de dados de telemetria do OpenTelemetry para Google Cloud a observabilidade. 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 trace 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 períodos 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 defina a seguinte variável de ambiente:

  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
  

Fazer o download e executar o aplicativo de amostra

Este exemplo de código implementa um agente de IA generativa criado usando o ADK. O agente é instrumentado com o OpenTelemetry, configurado para enviar métricas, traces e registros para seu Google Cloud projeto. 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 Google Cloud conta do. Se você é novo no Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a Google Cloud CLI.

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: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não planeja manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um projeto atual. Depois de concluir essas etapas, você poderá excluir o projeto, removendo todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do seu Google Cloud projeto.

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

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

Funções necessárias para ativar APIs

Para ativar as APIs, você precisa do papel de administrador de uso de serviços do IAM role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. 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 Google Cloud CLI.

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: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não planeja manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um projeto atual. Depois de concluir essas etapas, você poderá excluir o projeto, removendo todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do seu Google Cloud projeto.

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

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

Funções necessárias para ativar APIs

Para ativar as APIs, você precisa do papel de administrador de uso de serviços do IAM role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. 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 amostra grave dados de registro, métrica e trace, 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 Google Cloud recursos ou em um ambiente de desenvolvimento local.

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

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

Iniciar o aplicativo

Para iniciar o aplicativo de amostra, 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 oferece suporte ao 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 mostra 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 selecione sql_agent na lista de agentes.

   Observação: esse aplicativo exige o compartilhamento de recursos entre origens (CORS). Se você inserir um comando e o CORS estiver bloqueado, o aplicativo mostrará a mensagem Failed to create session e a linha de comando mostrará que os comandos foram rejeitados, POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   É possível ativar o CORS anexando o seguinte ao comando que executa a amostra:
   

   --allow_origins="regex:.*"

Interagir com o agente

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

What can you do for me ?

Da mesma forma, como o sql_agent tem a persona de um especialista em SQL, você pode pedir que ele crie tabelas para seus aplicativos e escreva 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 uma interação de amostra entre o sql_agent e o usuário:

As ações realizadas por agentes de IA generativa não são determinísticas. Portanto, você pode receber uma resposta diferente para o mesmo comando.

Sair do app

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

Visualizar os traces, métricas e registros

Esta seção descreve como visualizar eventos de IA generativa.

Antes de começar

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

• Leitor 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 personalizados papéis ou outros predefinidos papéis.

Visualizar telemetria

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

1. No Google Cloud console, 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, selecione Nome do período e, em seguida, selecione call_llm.

   A seguir, ilustramos a página Explorador de traces após a filtragem dos dados:

   

   Se você nunca usou o Cloud Trace antes, o Google Cloud Observability precisa criar um banco de dados para armazenar os dados de trace. A criação do banco de dados pode levar alguns minutos e, durante esse período, nenhum dado de trace estará disponível para visualização.

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

   A página Detalhes é aberta. Essa página mostra o trace associado e os períodos dele. A tabela na página mostra informações detalhadas sobre o período selecionado. Essas informações incluem o seguinte:

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

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

     

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

     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 para seu Google Cloud projeto, mas não gera nenhuma métrica.