> ## 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 framework Agno

> Crie agentes de IA para produção com o Agno e o AI Gateway do Toqan Router. Crie agentes que usam ferramentas, com observabilidade completa e acesso a mais de 500 LLMs.

> [card] [AI Gateway](#ai-gateway)
>
> Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: rode sempre no melhor modelo, com o 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 Agno é um framework Python para criar agentes de IA prontos para produção, com fluxos de trabalho estruturados, integração de ferramentas e orquestração multiagente. Ao conectar o Agno ao AI Gateway do Toqan Router, você tem acesso a mais de 500 modelos para seus agentes com uma única alteração de configuração.

### Principais benefícios

O AI Gateway do Toqan Router aprimora suas aplicações Agno com:

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

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

> [card] Otimização de custos
>
> Rastreamento 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 única integração unificada

### Pré-requisitos

Antes de integrar o Agno ao Toqan Router, verifique se você tem:

* Uma conta do Toqan Router e uma chave de API
* Python 3.10 ou superior

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

### Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install agno
```

### Configuração

Configure o Agno para usar o AI Gateway do Toqan Router via `OpenAILike` com uma `base_url` personalizada:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.models.openai.like import OpenAILike

llm = OpenAILike(
    id="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)
```

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

### Exemplo básico de agente

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.agent import Agent
from agno.models.openai.like import OpenAILike

llm = OpenAILike(
    id="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

agent = Agent(
    model=llm,
    instructions="You are a helpful assistant. Keep responses concise.",
    markdown=True,
)

agent.print_response("Explain machine learning in two sentences.")
```

### Agente com ferramentas

Adicione ferramentas ao seu agente para tarefas do mundo real:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.agent import Agent
from agno.models.openai.like import OpenAILike
from agno.tools.yfinance import YFinanceTools

llm = OpenAILike(
    id="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

agent = Agent(
    model=llm,
    tools=[YFinanceTools(enable_stock_price=True)],
    instructions="Use tables to display data. Don't include any other text.",
    markdown=True,
)

agent.print_response("What is the stock price of Apple?", stream=True)
```

### Agente com ferramentas personalizadas

Defina suas próprias funções Python como ferramentas:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.agent import Agent
from agno.models.openai.like import OpenAILike

def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Weather in {city}: Sunny, 22°C."

def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
    """Convert an amount between currencies."""
    return f"{amount} {from_currency} = {amount * 1.1:.2f} {to_currency} (approximate)"

llm = OpenAILike(
    id="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

agent = Agent(
    model=llm,
    tools=[get_weather, convert_currency],
    instructions="Use the available tools to answer questions accurately.",
    markdown=True,
)

agent.print_response("What's the weather in Tokyo and convert 100 USD to EUR?")
```

### Equipe multiagente

Orquestre vários agentes especializados:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.agent import Agent
from agno.models.openai.like import OpenAILike
from agno.team import Team

llm = OpenAILike(
    id="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

researcher = Agent(
    name="Researcher",
    model=llm,
    instructions="You research topics and provide accurate, concise facts.",
    markdown=True,
)

writer = Agent(
    name="Writer",
    model=llm,
    instructions="You take research and turn it into clear, engaging content.",
    markdown=True,
)

team = Team(
    members=[researcher, writer],
    model=llm,
    instructions="Collaborate to produce well-researched, well-written content.",
    markdown=True,
)

team.print_response("Write a short paragraph about renewable energy benefits.")
```

### Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo suportado de mais de 30 provedores:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from agno.models.openai.like import OpenAILike

# Use Claude
claude_llm = OpenAILike(
    id="anthropic/claude-sonnet-5",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

# Use Gemini
gemini_llm = OpenAILike(
    id="google/gemini-2.5-flash",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

# Use Groq
groq_llm = OpenAILike(
    id="groq/qwen/qwen3.8-27b",
    api_key=os.getenv("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)
```

## Observabilidade

### Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install opentelemetry-api \
    opentelemetry-sdk \
    "opentelemetry-exporter-otlp-proto-http" \
    openinference-instrumentation-agno
```

### Configurar a observabilidade do Toqan Router

Configure o tracer provider e instrumente o Agno antes de criar qualquer agente:

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

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

from openinference.instrumentation.agno import AgnoInstrumentor
AgnoInstrumentor().instrument()
```

> [!NOTE]
>
> A configuração do OTEL e a chamada `AgnoInstrumentor().instrument()` devem acontecer antes da instanciação de qualquer agente.

### Exemplo básico

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

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

from openinference.instrumentation.agno import AgnoInstrumentor
AgnoInstrumentor().instrument()

from agno.agent import Agent
from agno.models.openai.like import OpenAILike

agent = Agent(
    name="toqan-demo",
    model=OpenAILike(
        id="openai/gpt-5.4-mini",
        api_key=os.getenv("TOQAN_API_KEY"),
        base_url="https://router.toqan.ai/eu/v3/router",
    ),
    markdown=True,
)
agent.print_response("Summarize the latest AI news.")
```


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