Instrumentar um agente LangGraph ReAct com o OpenTelemetry

Este documento descreve as etapas para instrumentar um LangGraph ReAct Agent com o OpenTelemetry, permitindo a coleta de telemetria do agente. As solicitações do usuário e as respostas e escolhas do agente são incluídas na telemetria como atributos anexados a spans. As respostas do agente também são incluídas nas entradas de registro que estão relacionadas a spans 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.

Instrumentar o aplicativo de IA generativa para coletar telemetria

Para instrumentar o aplicativo de IA generativa para coletar dados de registro, métrica e rastreamento, 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:

pip install 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc'

Os dados de registro e métrica são enviados ao 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 trace são enviados para Google Cloud usando a API Telemetry (OTLP), que oferece suporte ao 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 de API de telemetria (OTLP).

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 a telemetria ao projeto 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: "langgraph-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()
    VertexAIInstrumentor().instrument()

Rastrear 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, clique em Mais e selecione Ver no GitHub.

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

Talvez seja necessário incluir o código anterior em lugares importantes do código do aplicativo.

Para saber mais sobre como adicionar spans e métricas personalizadas, consulte Adicionar rastros e métricas personalizados ao seu app.

Executar a amostra

Este exemplo é um agente do LangGraph instrumentado com o OpenTelemetry para enviar rastros e registros com comandos e respostas de IA generativa e métricas para o projetoGoogle Cloud .

Perfil do agente do LangGraph

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

Antes de começar

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

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

  3. Para receber as permissões necessárias para que os aplicativos de exemplo gravem dados de registro, métricas e rastreamento, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Executar amostra

Para executar a amostra:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Clone o repositório:

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

  3. Acesse o diretório da amostra:

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

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

  5. Crie um ambiente virtual e execute o exemplo:

    python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
python main.py

    O aplicativo mostra uma mensagem semelhante a esta:

    Starting agent using ephemeral SQLite DB.

  6. Para criar um banco de dados, insira um valor no comando Fale com o agente do SQL >> e pressione Enter.

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

    O exemplo a seguir ilustra 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: I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation.

Talk to the SQL agent >> Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
👤 User: Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
🤖 Agent

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

  7. Para sair, insira Ctrl-C.

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

Visualizar os traces, as métricas e os registros

Esta seção descreve como visualizar eventos de IA generativa.

Antes de começar

Para ter as permissões necessárias para visualizar seus dados de registro, métrica e rastreamento, 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 por meio de papéis personalizados ou de outros papéis predefinidos.

Conferir a telemetria

Para conferir os eventos de IA generativa, use a página Trace Explorer:

  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 span e invoke agent.

    A seção Run sample incluiu uma execução de exemplo em que duas solicitações são enviadas ao aplicativo. A ilustração a seguir mostra a página Trace Explorer após a filtragem dos dados:

    Exibição de intervalos de trace.

    Se você nunca usou o Cloud Trace, a Observabilidade do Google Cloud precisa criar um banco de dados para armazenar os dados de trace. A criação do banco de dados pode levar alguns minutos. Durante esse período, nenhum dado de rastreamento está disponível para visualização.

  3. Para analisar os dados de período e registro, selecione um período na tabela Períodos.

    A página Detalhes é aberta. Essa página mostra o rastro associado e os intervalos dele. A tabela na página mostra informações detalhadas sobre o período selecionado. Essas informações incluem:

    • A guia GenAI mostra eventos para agentes de IA generativa. Para saber mais sobre esses eventos, consulte Conferir 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 Logs e eventos lista as entradas de registro e os eventos associados ao período. Se você quiser conferir os dados de registro no Análise de registros, selecione Visualizar 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 exemplo, o payload JSON inclui o seguinte conteúdo:

      {
  logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
  jsonPayload: {
    finish_reason: "stop"
    message: {
      role: "model"
      content: [
        0: {
          text: "I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation."
        }
      ]
    }
  index: 0
  }
...
}

O exemplo atual é instrumentado para enviar dados de métricas ao projeto Google Cloud , mas não gera nenhuma métrica.