# How to Set Up Nebius Models for Agent Inference: A Complete Implementation Guide

> Learn how to set up Nebius models for agent inference with this complete guide. Configure your API key, install the Agno SDK, and implement the Nebius model class effortlessly.

- Repository: [Arindam Majumder /awesome-ai-apps](https://github.com/Arindam200/awesome-ai-apps)
- Tags: how-to-guide
- Published: 2026-05-06

---

**Configure your Nebius API key in a `.env` file, install the Agno SDK, and instantiate the `Nebius` model class from `agno.models.nebius` to pass directly to your `Agent` constructor.**

The awesome-ai-apps repository demonstrates production-ready patterns for integrating Nebius Token Factory models into AI agents. By wrapping Nebius-hosted LLMs through the Agno framework, you can enable agent inference using open-source models like Qwen 3 and Kimi-K2 with minimal boilerplate.

## Install Required Dependencies

All starter agents in the repository declare Nebius client dependencies in their [`requirements.txt`](https://github.com/Arindam200/awesome-ai-apps/blob/main/requirements.txt) or [`pyproject.toml`](https://github.com/Arindam200/awesome-ai-apps/blob/main/pyproject.toml) files. Installing the project environment pulls in the `agno` SDK, which contains the `Nebius` model wrapper.

```bash
pip install -r requirements.txt

```

The `agno` package provides the `Nebius` class at `agno.models.nebius` along with `python-dotenv` for credential management.

## Configure Nebius API Credentials

Nebius authentication requires an API key from the Token Factory platform. Create a `.env` file at the repository root (or copy the provided `.env.example`) and add your key:

```text
NEBIUS_API_KEY=your-nebius-token-factory-key

```

The codebase loads this file using `python-dotenv`. In your agent script, call `load_dotenv()` before retrieving the key:

```python
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("NEBIUS_API_KEY")

```

## Instantiate and Attach the Nebius Model

The canonical integration pattern consists of importing the `Nebius` class, instantiating it with a model identifier and your API key, then passing that instance to the `Agent` constructor via the `model=` parameter.

### Basic Agent Configuration

In [`starter_ai_agents/agno_starter/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/starter_ai_agents/agno_starter/main.py) (lines 45-48), the repository demonstrates the standard setup:

```python
from agno.agent import Agent
from agno.models.nebius import Nebius

agent = Agent(
    name="Tech News Analyst",
    instructions=[INSTRUCTIONS],
    tools=[hackernews_tools],
    model=Nebius(
        id="Qwen/Qwen3-30B-A3B",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    markdown=True,
)

```

### Voice Agent Integration

Voice agents follow the identical credential pattern. In [`voice_agents/pipecat_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/voice_agents/pipecat_agent/main.py) (line 53), the Nebius key is loaded and injected into the voice pipeline:

```python
api_key=os.getenv("NEBIUS_API_KEY"),

```

## Supported Model Identifiers

The repository implements support for multiple Nebius-hosted architectures. According to [`starter_ai_agents/camel_ai_starter/agent.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/starter_ai_agents/camel_ai_starter/agent.py) (lines 19-21), common model IDs include:

- `Qwen/Qwen3-30B-A3B`
- `moonshotai/Kimi-K2-Instruct`
- `zai-org/GLM-4.5-Air`

Each ID corresponds to a specific checkpoint hosted on the Nebius Token Factory inference endpoints.

## Advanced Configuration Options

### Using Separate Models for Generation and Embedding

For RAG agents requiring both generation and embedding capabilities, instantiate distinct Nebius models and pass them to the appropriate `Agent` parameters:

```python
from agno.models.nebius import Nebius

gen_model = Nebius(
    id="Qwen/Qwen3-30B-A3B", 
    api_key=os.getenv("NEBIUS_API_KEY")
)

agent = Agent(
    name="RAG Agent",
    model=gen_model,
    # embedding_model configured separately if supported

)

```

### Custom API Base URLs

For self-hosted Token Factory instances or private endpoints, override the base URL via the `NEBIUS_API_BASE` environment variable:

```python
import os
os.environ["NEBIUS_API_BASE"] = "https://my-private-nebius.com/v1"

agent = Agent(
    model=Nebius(
        id="Qwen/Qwen3-30B-A3B",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
)

```

## Summary

- **Install dependencies** via `pip install -r requirements.txt` to obtain the `agno` SDK containing the `Nebius` wrapper
- **Store credentials** in a `.env` file as `NEBIUS_API_KEY`, loading them with `load_dotenv()` and `os.getenv()`
- **Instantiate the model** using `Nebius(id="model-id", api_key=...)` from `agno.models.nebius`
- **Attach to Agent** by passing the instance to the `model=` parameter in the `Agent` constructor
- **Reference implementations** exist in [`starter_ai_agents/agno_starter/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/starter_ai_agents/agno_starter/main.py), [`voice_agents/pipecat_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/voice_agents/pipecat_agent/main.py), and [`simple_ai_agents/stock_portfolio_analyst/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/simple_ai_agents/stock_portfolio_analyst/main.py)

## Frequently Asked Questions

### What is the exact import path for the Nebius model class?

Import the class using `from agno.models.nebius import Nebius`. This wrapper is available across all agent types in the repository, including voice, RAG, and memory-enabled agents.

### Which environment variables are required for Nebius inference?

You must set `NEBIUS_API_KEY` in your `.env` file or environment. Optionally, configure `NEBIUS_API_BASE` if using a custom or self-hosted Token Factory endpoint rather than the default Nebius hosted service.

### Can I use Nebius models with voice agents?

Yes. The [`voice_agents/pipecat_agent/main.py`](https://github.com/Arindam200/awesome-ai-apps/blob/main/voice_agents/pipecat_agent/main.py) file demonstrates identical credential loading and model instantiation patterns for voice pipelines, proving the `Nebius` class works across modalities.

### How do I select specific Nebius model versions?

Pass the full model identifier string to the `id` parameter when instantiating the `Nebius` class. Valid IDs include `"Qwen/Qwen3-30B-A3B"`, `"moonshotai/Kimi-K2-Instruct"`, and `"zai-org/GLM-4.5-Air"` as shown in the Camel AI starter configuration.