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 seu 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 seus critérios específicos do domínio.

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 OpenTelemetry e envio de dados de telemetria do OpenTelemetry para Google Cloud Observabilidade. Para ativar isso, configure o 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'

    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 plataforma de agentes do Gemini Enterprise, também vai querer definir a seguinte variável de ambiente:

    GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'

Baixar e executar o aplicativo de amostra

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 começa vazio.

Antes de começar

  1. 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.

  2. Instale a CLI do Google Cloud.

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

  4. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  5. 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.

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

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

  7. Ative as APIs Vertex AI, Telemetria, Cloud Logging, Cloud Monitoring e Cloud Trace:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

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

  8. Instale a CLI do Google Cloud.

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

  10. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  11. 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.

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

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

  13. Ative as APIs Vertex AI, Telemetria, Cloud Logging, Cloud Monitoring e Cloud Trace:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

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

  14. 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étrica e rastreamento.

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

Inicie o aplicativo

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

  1. No Cloud Shell, execute este 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:

Exibição da interação com o sql_agent.

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

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:

    Exibição de intervalos de rastreamento.

    Se você nunca usou o Cloud Trace, o Google Cloud Observability precisa criar um banco de dados para armazenar seus dados de trace. 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 intervalo do Gemini inclui eventos de IA generativa:

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