Instrumentar aplicativos do ADK com o OpenTelemetry

Prévia

Este recurso está sujeito aos "Termos das Soluções 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 suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Este documento descreve como instrumentar um agente de IA criado com o framework do Kit de Desenvolvimento de Agente (ADK). Essa instrumentação, que usa o OpenTelemetry, permite coletar comandos do usuário, respostas e escolhas do agente.

O framework ADK é instrumentado com o OpenTelemetry, que captura a telemetria das principais etapas na execução do seu agente. Isso oferece observabilidade valiosa do aplicativo pronta para uso. No entanto, essa capacidade de observação 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 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 as pontuações de qualidade das respostas dos agentes 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. Instalar pacotes do OpenTelemetry
2. Configurar o OpenTelemetry para coletar e enviar telemetria
3. Escrever um ponto de entrada personalizado para injetar o OpenTelemetry configurado

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 'opentelemetry-instrumentation-google-genai' \
  '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 Telemetria (OTLP), que é compatível com o formato OTLP. Os dados recebidos por esse endpoint também são armazenados no formato OTLP. A biblioteca opentelemetry-exporter-otlp-proto-grpc invoca o endpoint da API Telemetry (OTLP).

Configurar o OpenTelemetry para coletar e enviar telemetria

No código de inicialização do agente do ADK, adicione código para configurar o OpenTelemetry e capturar e enviar telemetria ao seu projeto do Google Cloud :

Para ver o exemplo completo, clique em Mais e selecione Ver no GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Escrever um ponto de entrada personalizado para usar o OpenTelemetry configurado

Para usar o OpenTelemetry na instrumentação, crie um ponto de entrada personalizado para seu aplicativo ADK. O ponto de entrada personalizado precisa configurar o OpenTelemetry antes de iniciar o agente do ADK.

No aplicativo de exemplo, o método main funciona como um ponto de entrada personalizado que inicializa o OpenTelemetry e inicia o servidor FastAPI, que permite interagir com o agente.

Para ver o exemplo completo, clique em Mais e selecione Ver no GitHub.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

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 (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 (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 ter 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)

Iniciar 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) python main.py
   

   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, abra um navegador no endereço listado na etapa anterior.

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

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 ilustração a seguir mostra um exemplo de interação entre o sql_agent e o usuário:

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.



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:

• 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 IA generativa mostra eventos de 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 período 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": {
           "role": "model",
           "parts": [
             {
               "executable_code": null,
               "inline_data": null,
               "thought": null,
               "video_metadata": null,
               "code_execution_result": null,
               "function_response": null,
               "thought_signature": null,
               "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
               "file_data": null,
               "function_call": null
             }
           ]
         }
       },
       ...
     }
     

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