> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google ADK

> Conecte o Google Agent Development Kit ao Toqan Router via OpenTelemetry. Rastreie fluxos de trabalho de agentes, chamadas de ferramentas e interações com modelos Gemini.

> [card] [Observabilidade](#observability)
>
> 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](https://google.github.io/adk-docs/get-started/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:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install google-adk openinference-instrumentation-google-adk opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-httpx opentelemetry-instrumentation-requests opentelemetry-instrumentation-aiohttp-client httpx requests aiohttp
```

### Configurar o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router:

**Unix/Linux/macOS:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=google-adk-app,service.version=1.0.0"
export GOOGLE_API_KEY="your-google-api-key"
```

**Windows (PowerShell):**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=google-adk-app,service.version=1.0.0"
$env:GOOGLE_API_KEY = "your-google-api-key"
```

**Usando um arquivo .env:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=google-adk-app,service.version=1.0.0
GOOGLE_API_KEY=your-google-api-key
```

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

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openinference.instrumentation.google_adk import GoogleADKInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

GoogleADKInstrumentor().instrument(tracer_provider=provider)
set_global_textmap(TraceContextTextMapPropagator())
HTTPXClientInstrumentor().instrument(tracer_provider=provider)
RequestsInstrumentor().instrument(tracer_provider=provider)
AioHttpClientInstrumentor().instrument(tracer_provider=provider)

# Now use ADK normally - all agent operations will be traced
import google.adk as adk
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
import asyncio


def get_weather(location: str) -> str:
    """Return current weather for a location."""
    return f"Sunny in {location}, 22C"


async def main():
    # Create an agent with a tool
    agent = adk.Agent(
        name="Helper",
        instruction="Use the provided tool to answer questions briefly.",
        model="gemini-2.5-flash",
        tools=[get_weather],
    )

    # Create session and runner
    session_service = InMemorySessionService()
    runner = Runner(
        agent=agent,
        app_name="simple-helper",
        session_service=session_service
    )

    # Create a session (await the async call)
    session = await session_service.create_session(
        app_name="simple-helper",
        user_id="user1"
    )

    # Simple one-shot example
    question = "What's the weather in Paris?"
    content = types.Content(role='user', parts=[types.Part(text=question)])

    # Run the agent (this is also async)
    events = runner.run_async(
        user_id="user1",
        session_id=session.id,
        new_message=content
    )

    # Get the response
    async for event in events:
        if event.is_final_response():
            response = event.content.parts[0].text
            print(f"Q: {question}")
            print(f"A: {response}")

# Run the async main function
if __name__ == "__main__":
    try:
        asyncio.run(main())
    finally:
        provider.force_flush()
        provider.shutdown()
```

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

> [!NOTE]
>
> Para ver mais exemplos de implementação do ADK, navegue pelo [repositório Google ADK Samples](https://github.com/google/adk-samples)

### Próximos passos

**Verifique seus traces** no Studio do **Toqan Router**.

> [!NOTE]
>
> Para saber mais sobre os recursos de traces no Toqan Router, consulte [Traces](/docs/pt-BR/ai-studio/observability/traces.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.