Instrumentar aplicativos do ADK com o OpenTelemetry

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

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 do 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 capacidade de observação 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 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 os índices de qualidade das respostas do agente com base nos seus critérios específicos do domínio.

Observação: este documento pressupõe que você esteja usando uma estrutura do 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 o 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:

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

Os dados de registros e métricas são enviados ao seu projeto Google Cloud usando a API Cloud Logging ou a API Cloud Monitoring. As bibliotecas opentelemetry-exporter-gcp-logging e opentelemetry-exporter-gcp-monitoring invocam endpoints nessas APIs.

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

Seus dados de rastreamento são armazenados em um formato geralmente consistente com os arquivos proto definidos pelo protocolo OTLP 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 para o OpenTelemetry e o envio de dados de telemetria do OpenTelemetry para a observabilidade doGoogle Cloud . Para ativar esse recurso, configure o ambiente do ADK:

• Ao executar o aplicativo com o comando da CLI 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
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  

• 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 extensão que excedam o limite de tamanho do atributo.
  • Impede que informações de identificação pessoal (PII) sejam anexadas a intervalos como atributos.

Baixar 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 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 Agentes e acessa um banco de dados usando o SQLDatabaseToolkit. O banco de dados está inicialmente vazio.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

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

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

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

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. Se você executar a amostra no Cloud Shell, em recursos Google Cloud ou em um ambiente de desenvolvimento local, as permissões listadas nesta seção serão suficientes. Para aplicativos de produção, geralmente uma conta de serviço fornece as credenciais para gravar dados de registro, métricas e rastreamento.

   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)

Inicie o aplicativo

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

1. No Cloud Shell, execute o seguinte comando:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git
   

2. Acesse o diretório da amostra:

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

3. Crie um ambiente virtual e execute a amostra:

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud
   

   O aplicativo vai mostrar uma mensagem semelhante a esta:

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

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

5. Expanda Selecionar um representante e escolha sql_agent na lista de representantes.

Interaja 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 uma interação de exemplo 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.

Ver os traces, as métricas e os registros

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

Antes de começar

Para ter as permissões necessárias para acessar 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 traces:

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 para agentes de IA generativa. Para saber mais sobre esses eventos, consulte Ver eventos de 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 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 quiser ver os dados de registro no Explorador 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 seu projeto Google Cloud , mas não gera nenhuma métrica.