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

> Conecte o SmolAgents da HuggingFace ao AI Gateway do Toqan Router para acessar mais de 500 LLMs e enviar traces via OpenTelemetry para observabilidade completa dos agentes.

> [card] [AI Gateway](#ai-gateway)
>
> Encaminhe suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: execute 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 SmolAgents é um framework leve de agentes em Python criado pela Hugging Face. Usando `OpenAIServerModel` com um `api_base` personalizado, você pode encaminhar todas as chamadas de LLM pelo AI Gateway do Toqan Router e ter acesso a mais de 500 modelos, rastreamento de custos e recursos de confiabilidade.

### Pré-requisitos

* Uma conta no Toqan Router e uma chave de API
* Python 3.9 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 smolagents
```

### Configuração

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="openai/gpt-5.6-sol",
    api_base="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ["TOQAN_API_KEY"],
)
```

> **api\_base**: `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 smolagents import CodeAgent, OpenAIServerModel

model = OpenAIServerModel(
    model_id="openai/gpt-5.4-mini",
    api_base="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ["TOQAN_API_KEY"],
)

agent = CodeAgent(tools=[], model=model)
agent.run("What is the capital of France?")
```

### Seleção de modelo

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

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from smolagents import OpenAIServerModel

# Use Claude
claude_model = OpenAIServerModel(
    model_id="anthropic/claude-sonnet-5",
    api_base="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ["TOQAN_API_KEY"],
)

# Use Gemini
gemini_model = OpenAIServerModel(
    model_id="google/gemini-2.5-flash",
    api_base="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ["TOQAN_API_KEY"],
)

# Use Groq
groq_model = OpenAIServerModel(
    model_id="groq/qwen/qwen3.8-27b",
    api_base="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ["TOQAN_API_KEY"],
)
```

## Observabilidade

### Visão geral

O SmolAgents usa a biblioteca `openinference-instrumentation-smolagents` para instrumentar automaticamente as execuções de agentes e exportar traces via OpenTelemetry.

### Pré-requisitos

* Uma conta no Toqan Router e uma chave de API
* Python 3.9 ou superior

### Instalação

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

### Configurando a observabilidade do Toqan Router

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

```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 openinference.instrumentation.smolagents import SmolagentsInstrumentor

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

SmolagentsInstrumentor().instrument(tracer_provider=tracer_provider)
```

> [!NOTE]
>
> `SmolagentsInstrumentor` deve ser chamado antes de qualquer agente ser instanciado. Após a instrumentação, todas as execuções de `CodeAgent` e `ToolCallingAgent` são rastreadas automaticamente.

### 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 openinference.instrumentation.smolagents import SmolagentsInstrumentor

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))
SmolagentsInstrumentor().instrument(tracer_provider=tracer_provider)

from smolagents import CodeAgent, OpenAIServerModel

agent = CodeAgent(
    tools=[],
    model=OpenAIServerModel(
        model_id="openai/gpt-5.4-mini",
        api_base="https://router.toqan.ai/eu/v3/router",
        api_key=os.environ["TOQAN_API_KEY"],
    ),
)
agent.run("What is the capital of France?")
```


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