Instrumente aplicações ADK com o OpenTelemetry

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico 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 a framework do Agent Development Kit (ADK). Esta instrumentação, que tira partido do OpenTelemetry, permite-lhe recolher comandos do utilizador, respostas do agente e escolhas do agente.

A framework ADK está instrumentada com o OpenTelemetry, que captura a telemetria de passos importantes na execução do seu agente. Isto oferece uma observabilidade da aplicação pronta a usar. No entanto, esta observabilidade pode não ser suficiente para o exemplo de utilização da sua aplicação. Pode adicionar bibliotecas de instrumentação adicionais através do OpenTelemetry para capturar telemetria de outras partes da sua app ou a sua própria instrumentação personalizada para capturar dados específicos da aplicação e obter uma observabilidade mais detalhada.

Por exemplo, na sua aplicação, pode escrever código de instrumentação para:

• Acompanhe o consumo de recursos das ferramentas invocadas pelo agente.
• Monitorize falhas de validação específicas da aplicação, violações de regras empresariais ou mecanismos de recuperação de erros personalizados.
• Monitorize os índices de qualidade das respostas dos agentes com base nos seus critérios específicos do domínio.

Instrumente a sua aplicação de IA generativa para recolher telemetria

Para instrumentar o seu agente de IA para recolher dados de registo, métricas e rastreios, faça o seguinte:

1. Instale pacotes do OpenTelemetry
2. Configure o OpenTelemetry para recolher e enviar telemetria
3. Escreva um ponto de entrada personalizado para injetar o OpenTelemetry configurado

O resto desta secção descreve os passos anteriores.

Instale pacotes OpenTelemetry

Adicione os seguintes pacotes de instrumentação e exportador 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 registo e de métricas são enviados para o seu Google Cloud projeto através da API Cloud Logging ou da API Cloud Monitoring. As bibliotecas opentelemetry-exporter-gcp-logging e opentelemetry-exporter-gcp-monitoring invocam pontos finais nessas APIs.

Os dados de rastreio são enviados para Google Cloud através da API Telemetry (OTLP), que suporta o formato OTLP. Os dados recebidos através deste ponto final também são armazenados no formato OTLP. A biblioteca opentelemetry-exporter-otlp-proto-grpc invoca o ponto final da API Telemetry (OTLP).

Configure o OpenTelemetry para recolher e enviar telemetria

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

Para ver o exemplo completo, clique em Mais e, de seguida, 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()

Escreva um ponto de entrada personalizado para usar o OpenTelemetry configurado

Para usar o OpenTelemetry para instrumentação, crie um ponto de entrada personalizado para a sua aplicação ADK. O ponto de entrada personalizado tem de configurar o OpenTelemetry antes de iniciar o agente do ADK.

Na aplicação de exemplo, o método main atua como um ponto de entrada personalizado que inicializa o OpenTelemetry e, em seguida, inicia o servidor FastAPI, que lhe permite interagir com o agente.

Para ver o exemplo completo, clique em Mais e, de seguida, 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)))

Transfira e execute a aplicação de exemplo

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

Perfil do agente ADK

O agente de IA generativa é definido como um especialista em SQL que tem acesso total a uma base de dados SQLite efémera. O agente é criado com o Agent Development Kit e acede a uma base de dados através do SQLDatabaseToolkit. Inicialmente, a base de dados está vazia.

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.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, 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.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, 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 executar o exemplo no Cloud Shell, em Google Cloud resources ou num ambiente de desenvolvimento local, as autorizações indicadas nesta secção são suficientes. Para aplicações de produção, normalmente, uma conta de serviço fornece as credenciais para escrever dados de registo, métricas e rastreio.

   Para receber as autorizações de que precisa para que a aplicação de exemplo escreva dados de registo, métricas e rastreios, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Logs Writer (roles/logging.logWriter)
   • Monitoring Metric Writer (roles/monitoring.metricWriter)
   • Utilizador do Vertex AI (roles/aiplatform.user)

Inicie a aplicação

Para iniciar a aplicação 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. Aceda ao diretório de exemplo:

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

3. Crie um ambiente virtual e execute o exemplo:

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

   A aplicação apresenta uma mensagem semelhante à seguinte:

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

4. Para interagir com o agente, abra um navegador no endereço indicado no passo anterior.

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

Interaja com o agente

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

What can you do for me ?

Da mesma forma, uma vez que o sql_agent tem a personalidade de um especialista em SQL, pode pedir-lhe para criar tabelas para as suas aplicações e escrever consultas para operar nas tabelas criadas. O agente só pode criar uma base de dados efémera suportada por um ficheiro .db criado na máquina que executa a aplicação.

A imagem seguinte ilustra um exemplo de interação entre o sql_agent e o utilizador:

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 pelos agentes de IA generativa não são determinísticas, pelo que pode ver uma resposta diferente para o mesmo comando.

Saia da aplicação

Para sair da aplicação, introduza Ctrl-C na shell usada para iniciar a aplicação.

Veja os rastreios, as métricas e os registos

Esta secção descreve como pode ver eventos de IA generativa.

Antes de começar

Para receber as autorizações de que precisa para ver os dados de registo, métricas e rastreio, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

• Visualizador de registos (roles/logging.viewer)
• Visitante de monitorização (roles/monitoring.viewer)
• Utilizador do Cloud Trace (roles/cloudtrace.user)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Ver telemetria

Para ver os eventos de IA generativa criados pela aplicação, use a página Explorador de rastreios:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

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

   A imagem seguinte ilustra a página do Explorador de rastreios após a filtragem dos dados:

   

   Se nunca usou o Cloud Trace, o Google Cloud Observability tem de criar uma base de dados para armazenar os seus dados de rastreio. A criação da base de dados pode demorar alguns minutos e, durante esse período, não estão disponíveis dados de rastreio para visualização.

3. Para explorar os dados de intervalo e registo, na tabela Intervalos, selecione um intervalo.

   É apresentada a página Detalhes. Esta página apresenta o rastreio associado e os respetivos intervalos. A tabela na página apresenta informações detalhadas para o intervalo selecionado. Estas informações incluem o seguinte:

   • O separador GenAI apresenta eventos para agentes de IA generativa. Para saber mais acerca destes eventos, consulte o artigo Veja eventos de IA generativa.

     A captura de ecrã seguinte ilustra um rastreio, em que um intervalo tem o nome call_llm. Esse intervalo invoca o GML (grande modelo de linguagem) que alimenta este agente. Para este exemplo, é o Gemini. O intervalo do Gemini inclui eventos de IA generativa:

     

   • O separador Registos e eventos apresenta entradas de registo e eventos associados ao intervalo. Se quiser ver os dados de registo no Explorador de registos, na barra de ferramentas deste separador, selecione Ver registos.

     Os dados de registo incluem a resposta do sql_agent. Por exemplo, para a execução de exemplo, 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
             }
           ]
         }
       },
       ...
     }
     

O exemplo está instrumentado para enviar dados de métricas para o seu projeto do Google Cloud , mas não gera métricas.