Instrumentar um agente LangGraph ReAct 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.

Neste documento, descrevemos as etapas para instrumentar um agente LangGraph ReAct com o OpenTelemetry, permitindo a coleta de telemetria do agente. Os comandos do usuário e as respostas e opções do agente são incluídos na telemetria como atributos anexados a intervalos. As respostas do agente também são incluídas nas entradas de registro correlacionadas com intervalos 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 seu aplicativo de IA generativa para coletar telemetria

Para instrumentar seu aplicativo de IA generativa e 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-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc'

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 seu agente LangGraph, configure o OpenTelemetry para capturar e enviar telemetria ao seu 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 LangGraph, crie um intervalo 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 você queira incluir o código anterior em lugares importantes do código do aplicativo.

Para saber mais sobre como adicionar intervalos e métricas personalizados, consulte Adicionar rastreamentos e métricas personalizados ao seu app.

Executar a amostra

Esta amostra é 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 seu projetoGoogle Cloud .

Perfil do agente LangGraph

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

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)

Executar amostra

Para executar a amostra:

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

4. Crie um ambiente virtual e execute a amostra:

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

   O aplicativo vai mostrar uma mensagem semelhante a esta:

   Starting agent using ephemeral SQLite DB.
   

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

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

   A seguir, ilustramos 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: 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
   );
   
   

6. Para sair, insira Ctrl-C.

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.

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, 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 invoke agent.

   A seção Executar exemplo incluiu um exemplo de execução em que dois comandos são enviados ao aplicativo. 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 invoke_agent. Esse intervalo invoca 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 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: {
         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
       }
     ...
     }
     

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