Instrumentar um agente LangGraph ReAct com o OpenTelemetry

Neste documento, descrevemos as etapas para instrumentar um agente ReAct do LangGraph com o OpenTelemetry, permitindo a coleta de telemetria do agente. Os comandos do usuário e as respostas e escolhas do agente são incluídos na telemetria como atributos anexados aos períodos. As respostas do agente também estão incluídas nas entradas de registro correlacionadas com períodos que contêm eventos de IA generativa. As instruções neste documento se aplicam quando o agente usa o ChatVertexAI do Langchain para chamar um modelo do Gemini.

Os aplicativos que usam um agente ReAct do LangGraph também podem coletar comandos e respostas multimodais. Neste documento, descrevemos como coletar comandos de texto e respostas. Se você quiser coletar dados multimodais, será necessário fazer uma configuração adicional. Para mais informações, consulte Coletar e visualizar comandos multimodais.

Instrumentar o aplicativo de IA generativa para coletar telemetria

Para instrumentar o aplicativo de IA generativa para coletar dados de registro, métrica e trace, faça o seguinte:

  1. Instalar pacotes do OpenTelemetry
  2. Configurar o OpenTelemetry para coletar e enviar telemetria
  3. Rastrear a invocação do agente de IA generativa

Instalar pacotes do OpenTelemetry

Adicione os seguintes pacotes de instrumentação e exportador do OpenTelemetry:

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-otlp-proto-grpc'

Os dados de registro, métrica e trace são enviados para o Google Cloud usando a API Telemetry (OTLP), que implementa o protocolo 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 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 o OpenTelemetry para coletar e enviar telemetria

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

Para ver o exemplo completo, selecione o logotipo do GitHub na barra de ferramentas do exemplo.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # 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(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Trace a invocação do agente de IA generativa

Para rastrear a execução da invocação do agente do LangGraph, crie um período personalizado em torno da invocação do agente:

Para ver o exemplo completo, selecione o logotipo do GitHub na barra de ferramentas do exemplo.

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

É recomendável incluir o código anterior em locais importantes do código do aplicativo.

Para saber como adicionar períodos e métricas personalizados, consulte Adicionar traces e métricas personalizados ao seu app.

Executar a amostra

Este exemplo é um agente do LangGraph instrumentado com o OpenTelemetry para enviar traces e registros com comandos e respostas de IA generativa, além de métricas para o projeto do Google Cloud .

Persona do agente do LangGraph

O agente do LangGraph é definido como um especialista em SQL que tem acesso total a um banco de dados SQLite temporário. O agente é implementado com o agente ReAct pré-criado do LangGraph e acessa o banco de dados, que inicialmente está vazio, usando o SQLDatabaseToolkit.

Antes de começar

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

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

    gcloud init

  4. Crie ou selecione um projeto do Google Cloud .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário ter um papel específico do IAM para selecionar um projeto. É possível selecionar qualquer projeto em que você tenha um papel.
    • Criar um projeto: para criar um projeto, é preciso 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 do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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

  6. Ative as APIs Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring e API Cloud Trace, se ainda não estiverem ativadas:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). 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

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

    Essas permissões são suficientes se você executar o exemplo no Cloud Shell, em recursos do Google Cloud ou em um ambiente de desenvolvimento local.

  8. Especifique 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

Executar amostra

Para executar a amostra:

  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/langgraph-sql-agent

  3. Configure as variáveis de ambiente:

    # Capture GenAI prompts and responses
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
# Capture application logs automatically
export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
# Set the location to one that supports gemini-3.5-flash
export GOOGLE_CLOUD_REGION=global

    Se preferir usar um modelo diferente, edite main.py. Verifique se o modelo é compatível com o local especificado. Para mais informações sobre modelos, consulte Modelos do Google.

  4. Crie um ambiente virtual e execute o exemplo:

    uv run main.py

    O aplicativo exibe uma mensagem semelhante a esta:

    Starting agent using ephemeral SQLite DB.

  5. Para criar um banco de dados, insira um valor no prompt Falar com o agente SQL >> e pressione Enter.

    As ações realizadas pelo agente serão exibidas no Cloud Shell.

    Veja a seguir exemplos de interações entre um usuário e o aplicativo:

    Talk to the SQL agent >> Create a new table to hold weather data.
👤 User: Create a new table to hold weather data.
🤖 Agent: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.

CREATE TABLE weather (
  date DATE,
  location VARCHAR(255),
  temperature REAL,
  humidity REAL,
  precipitation REAL
);

🤖 Agent: I have created the weather table.
👤 User: Add altitude to the table.
🤖 Agent

ALTER TABLE weather ADD COLUMN altitude REAL;

  6. Para sair, insira Ctrl-C.

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

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 os dados de registro, métrica e trace, 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, use a página Análise 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 período e invoke agent.

    A seção Executar exemplo incluiu um exemplo de execução em que dois comandos são enviados ao aplicativo. Veja a seguir a página do Trace Explorer depois de filtrar os dados:

    Exibição de períodos de trace.

    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 e, durante esse período, nenhum dado de trace estará 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 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:

    • 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 trace em que um período tem o nome invoke_agent. Esse período invoca o Gemini. O período do Gemini inclui eventos de IA generativa:

      Exibição de eventos de IA generativa.

    • A guia Registros e eventos lista as entradas de registro e os eventos associados ao período. Se você 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 agente do LangGraph. 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: {
    message: {
      role: "model"
      content: [
        0: {
          text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.

          CREATE TABLE weather (
              date DATE,
              location VARCHAR(255),
              temperature REAL,
              humidity REAL,
              precipitation REAL
          );
          "
        }
      ]
    }
  index: 0
  }
...
}

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