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

# SmolAgents integration

> Connect HuggingFace SmolAgents to Orq.ai's AI Router for 300+ LLMs and send traces via OpenTelemetry for full agent observability.

<CardGroup cols={2}>
  <Card title="AI Router" icon="arrow-right-arrow-left" href="#ai-router">
    Route your LLM calls through the AI Router with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for your use case.
  </Card>

  <Card title="Observability" icon="chart-line" href="#observability">
    Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.
  </Card>
</CardGroup>

## AI Router

### Overview

SmolAgents is a lightweight Python agent framework by Hugging Face. Using `OpenAIServerModel` with a custom `api_base`, you can route all LLM calls through Orq.ai's AI Router for access to 300+ models, cost tracking, and reliability features.

### Prerequisites

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Python 3.9 or higher

<Info>
  To setup your API key, see [API keys & Endpoints](/docs/administer/api-keys).
</Info>

### Installation

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

### Configuration

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

model = OpenAIServerModel(
    model_id="openai/gpt-4o",
    api_base="https://api.orq.ai/v3/router",
    api_key=os.environ["ORQ_API_KEY"],
)
```

> **api\_base**: `https://api.orq.ai/v3/router`

### Basic Agent Example

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

model = OpenAIServerModel(
    model_id="openai/gpt-4o-mini",
    api_base="https://api.orq.ai/v3/router",
    api_key=os.environ["ORQ_API_KEY"],
)

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

### Model Selection

With Orq.ai, you can use any supported model from 20+ providers:

```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-4-5-20250929",
    api_base="https://api.orq.ai/v3/router",
    api_key=os.environ["ORQ_API_KEY"],
)

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

# Use Groq
groq_model = OpenAIServerModel(
    model_id="groq/llama-3.3-70b-versatile",
    api_base="https://api.orq.ai/v3/router",
    api_key=os.environ["ORQ_API_KEY"],
)
```

## Observability

### Overview

SmolAgents uses the `openinference-instrumentation-smolagents` library to automatically instrument agent runs and export traces via OpenTelemetry.

### Prerequisites

* An Orq.ai account and [API Key](/docs/administer/api-keys)
* Python 3.9 or higher

### Installation

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

### Configuring Orq.ai Observability

Set up the tracer provider and instrument SmolAgents before creating any agents:

```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://api.orq.ai/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['ORQ_API_KEY']}"},
)
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

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

<Info>
  `SmolagentsInstrumentor` must be called before any agent is instantiated. Once instrumented, all `CodeAgent` and `ToolCallingAgent` runs are automatically traced.
</Info>

### Basic Example

```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://api.orq.ai/v2/otel/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['ORQ_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-4o-mini",
        api_base="https://api.orq.ai/v3/router",
        api_key=os.environ["ORQ_API_KEY"],
    ),
)
agent.run("What is the capital of France?")
```

## Evaluations & Experiments

Once your agents are running, use **Evaluatorq** to score outputs across a dataset and **Experiments** to compare configurations side-by-side.

<CardGroup cols={2}>
  <Card title="Run Evaluations with Evaluatorq" icon="flask" href="/docs/evaluators/build#evaluatorq">
    Run parallel evaluations across your agents and compare results.
  </Card>

  <Card title="Run Experiments via the API" icon="flask-vial" href="/docs/experiments/api">
    Compare agent configurations and view results in the AI Studio.
  </Card>
</CardGroup>