Instrumentar um agente LangGraph ReAct com o OpenTelemetry

Visualizar

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 da fase de lançamento.

Este documento descreve as etapas para instrumentar um agente do LangGraph ReAct 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 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.

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

Instrumentar o aplicativo de IA generativa para coletar telemetria

Para instrumentar o aplicativo de IA generativa para coletar dados de registro, métricas e traces, 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 registro e métricas são enviados ao Google Cloud projeto usando a API Cloud Logging ou a API Cloud Monitoring. As opentelemetry-exporter-gcp-logging e opentelemetry-exporter-gcp-monitoring bibliotecas invocam endpoints nessas APIs.

Os dados de trace são enviados ao projeto usando a API Telemetry (OTLP), que implementa o protocolo de linha do OpenTelemetry. Google Cloud 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 de linha do 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 de 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 Google Cloud projeto:

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 você queira incluir o código anterior em locais importantes no código do aplicativo.

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

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 e métricas ao seu Google Cloud projeto.

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 efêmero. 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

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a 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 CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

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

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Criar um Google Cloud projeto:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

Ative as APIs Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

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

Instale a 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 CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

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

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Criar um Google Cloud projeto:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

Ative as APIs Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring e Cloud Trace:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

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

1. Se você executar o exemplo no Cloud Shell, em Google Cloud recursos ou em um ambiente de desenvolvimento local, as permissões listadas nesta seção serão suficientes. Para aplicativos de produção, normalmente uma conta de serviço fornece as credenciais para gravar dados de registro, métricas e traces.

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

   • Gravador de traces de telemetria da nuvem (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 exemplo

Para executar a amostra:

1. No Cloud Shell, execute o comando a seguir:

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

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 são mostradas 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: 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 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, métricas e registros

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

Antes de começar

Para receber as permissões necessárias para visualizar os dados de registro, métricas e traces, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Visualizador de registros (roles/logging.viewer)
• Leitor do monitoramento (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 personalizados papéis ou outros predefinidos papéis.

Visualizar telemetria

Para visualizar os eventos de IA generativa, use a página Explorador de traces:

1. No Google Cloud console, 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, selecione Nome do intervalo e, em seguida, selecione invoke agent.

   A seção Executar exemplo incluiu uma execução de exemplo em que dois comandos são enviados ao aplicativo. A seguir, ilustramos a página Explorador de traces após a filtragem dos dados:

   

   Se você nunca usou o Cloud Trace antes, o Google Cloud Observability precisa criar um banco de dados para armazenar os 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 explorar seus dados de período e registro, na tabela Intervalos, selecione um período.

   A página Detalhes é aberta. Essa página mostra o trace associado e os intervalos dele. A tabela na página mostra informações detalhadas do intervalo selecionado. Essas informações incluem o seguinte:

   • A guia Entradas/Saídas mostra eventos para agentes de IA generativa. Para saber mais sobre esses eventos, consulte Visualizar eventos de IA generativa.

     A captura de tela a seguir ilustra um trace em que um período tem o nome invoke_agent. Esse intervalo invoca o Gemini. O intervalo do Gemini inclui eventos de IA generativa:

     

   • A guia Registros e eventos lista entradas de registro e eventos associados ao período. Se você quiser visualizar os dados de registro na Análise de registros, na barra de ferramentas dessa guia, selecione Visualizar registros.

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

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