Pular para o conteúdo principal

Observabilidade

Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

Observabilidade

Este guia aborda Python. Para instalação e exemplos em Java, consulte o quickstart do Google ADK para Java.

Primeiros passos

O Google Agent Development Kit (ADK) é um framework flexível e independente de modelo para desenvolver e implantar agentes de IA. O ADK simplifica a criação de arquiteturas de agentes complexas com orquestração de fluxos de trabalho, integração de ferramentas e colaboração entre múltiplos agentes. Integre-o ao Toqan Router para monitorar o comportamento dos agentes, acompanhar o uso de ferramentas, analisar fluxos de trabalho e otimizar seus sistemas de agentes.

Pré-requisitos

Antes de começar, certifique-se de ter:
  • Uma conta no Toqan Router e uma chave de API
  • Chave de API do Google (para acesso aos modelos)
  • Python 3.11+
  • O Google ADK instalado no seu projeto

Instalar dependências

Python:

Configurar o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router: Unix/Linux/macOS:
Windows (PowerShell):
Usando um arquivo .env:

Integrações

Use o instrumentador OpenInference para Google ADK para capturar spans do OpenInference e propagar o contexto de trace para as requisições ao modelo.

Instrumentar o Google ADK

Inicialize a integração antes de criar clientes Gemini ou executar Agents. Passe o TracerProvider existente quando o OpenTelemetry já estiver configurado. Chame GoogleADKInstrumentor().instrument(tracer_provider=provider) uma vez na inicialização.

Combinar tracing com o AI Gateway

Para requisições ao modelo por meio de /v3/google, siga a configuração do Google Gen AI SDK e mantenha as chaves de API do exportador OTLP e do AI Gateway restritas ao mesmo Workspace e Project. A instrumentação HTTP abaixo propaga os cabeçalhos W3C traceparent e tracestate por HTTPX, Requests e aiohttp. Outros transportes precisam de instrumentação OpenTelemetry própria. Encaminhe esses cabeçalhos por qualquer proxy intermediário. As requisições enviadas por esses clientes HTTP instrumentados carregam o contexto do span ativo. Não defina um cabeçalho traceparent fixo nem o reutilize ao longo de uma sessão de Agent. Após a configuração, confirme que o span do modelo exportado e a requisição correspondente no AI Gateway compartilham o mesmo trace ID. Assim, as chamadas correlacionadas podem ser contadas uma única vez em Activity, enquanto ambos os traces continuam disponíveis.
Para ver mais exemplos de implementação do ADK, navegue pelo repositório Google ADK Samples

Próximos passos

Verifique seus traces no Studio do Toqan Router.
Para saber mais sobre os recursos de traces no Toqan Router, consulte Traces