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

# Integração com o LiveKit Agents

> Conecte o LiveKit Agents ao AI Gateway do Toqan Router para ter observabilidade completa, confiabilidade integrada e acesso a mais de 500 LLMs de mais de 30 provedores.

> [card] [AI Gateway](#ai-gateway)
>
> Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a base URL. Sem dependência de fornecedor: use sempre o melhor modelo pelo menor custo para o seu caso de uso.

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

## AI Gateway

### Visão geral

O LiveKit Agents é um framework para criar agentes de IA de voz e multimodais em tempo real que se comunicam via WebRTC. Ao conectar o LiveKit Agents ao AI Gateway do Toqan Router, você obtém IA de voz pronta para produção com acesso a LLMs de nível empresarial, sem dependência de fornecedor.

### Principais benefícios

O AI Gateway do Toqan Router aprimora seus LiveKit Agents com:

> [card] Observabilidade completa
>
> Acompanhe cada chamada de LLM, uso de ferramenta e interação de agente com traces detalhados

> [card] Confiabilidade integrada
>
> Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

> [card] Otimização de custos
>
> Acompanhamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

> [card] Acesso a múltiplos provedores
>
> Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma integração única e unificada

### Pré-requisitos

Antes de integrar o LiveKit Agents ao Toqan Router, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* Python 3.9 ou superior
* Uma conta no LiveKit com URL, chave de API e secret de API

> [!NOTE]
>
> Para configurar sua chave de API, consulte Chaves de API e endpoints.

### Instalação

Instale o LiveKit Agents com o plugin da OpenAI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "livekit-agents[openai]~=1.0"
```

### Configuração

Configure o LiveKit Agents para usar o AI Gateway do Toqan Router por meio do parâmetro `base_url` do plugin da OpenAI:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from livekit.plugins import openai
import os

# Configure OpenAI-compatible LLM with Toqan Router AI Gateway
llm = openai.LLM(
    model="openai/gpt-5.6-sol",
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
)
```

> **base\_url**: `https://router.toqan.ai/eu/v3/router`

### Variáveis de ambiente

Configure suas credenciais do LiveKit e do Toqan Router:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export LIVEKIT_URL="wss://your-project.livekit.cloud"
export LIVEKIT_API_KEY="your-livekit-api-key"
export LIVEKIT_API_SECRET="your-livekit-api-secret"
export TOQAN_API_KEY="your-toqan-api-key"
```

### Agente de voz básico

Veja um exemplo completo de um agente de voz usando o AI Gateway do Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from livekit.agents import Agent, AgentSession, WorkerOptions, cli
from livekit.plugins import openai

class Assistant(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant.",
        )

async def entrypoint(ctx):
    session = AgentSession(
        llm=openai.LLM(
            model="openai/gpt-5.6-sol",
            base_url="https://router.toqan.ai/eu/v3/router",
            api_key=os.getenv("TOQAN_API_KEY"),
        ),
    )
    await session.start(ctx.room, agent=Assistant())

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

### Agente com function tools

Adicione ferramentas ao seu agente de voz para respostas dinâmicas:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from livekit.agents import Agent, AgentSession, WorkerOptions, cli, function_tool
from livekit.plugins import openai

@function_tool
async def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny and 72°F"

@function_tool
async def get_time(timezone: str) -> str:
    """Get the current time in a timezone."""
    return f"The current time in {timezone} is 14:30"

class Assistant(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant with access to weather and time tools.",
            tools=[get_weather, get_time],
        )

async def entrypoint(ctx):
    session = AgentSession(
        llm=openai.LLM(
            model="openai/gpt-5.6-sol",
            base_url="https://router.toqan.ai/eu/v3/router",
            api_key=os.getenv("TOQAN_API_KEY"),
        ),
    )
    await session.start(ctx.room, agent=Assistant())

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

## Observabilidade

### Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install opentelemetry-api \
    opentelemetry-sdk \
    "opentelemetry-exporter-otlp-proto-http" \
    "livekit-agents[openai]~=1.0"
```

> [!NOTE]
>
> O LiveKit Agents tem suporte integrado a OTEL via `livekit.agents.telemetry`. Nenhum pacote de instrumentação adicional é necessário.

### Configurar a observabilidade do Toqan Router

Use `set_tracer_provider` de `livekit.agents.telemetry` para registrar o exporter. Chame-o antes de o entrypoint do seu agente iniciar:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from livekit.agents.telemetry import set_tracer_provider

exporter = OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
)
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
set_tracer_provider(provider)
```

> [!NOTE]
>
> O LiveKit usa `livekit.agents.telemetry.set_tracer_provider`, e não o padrão `opentelemetry.trace.set_tracer_provider`. `BatchSpanProcessor` é preferível a `SimpleSpanProcessor` para cargas de trabalho de voz em produção.

### Exemplo básico

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from livekit.agents.telemetry import set_tracer_provider
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli
from livekit.plugins import openai


def setup_tracing():
    exporter = OTLPSpanExporter(
        endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
        headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
    )
    provider = TracerProvider()
    provider.add_span_processor(BatchSpanProcessor(exporter))
    set_tracer_provider(provider)


async def entrypoint(ctx: JobContext):
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)

    assistant = openai.realtime.RealtimeModel(voice="alloy")
    agent = openai.realtime.RealtimeAgent(model=assistant)
    agent.start(ctx.room)


if __name__ == "__main__":
    setup_tracing()
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```


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