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

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 or pyproject.toml files. Installing the project environment pulls in the agno SDK, which contains the Nebius model wrapper.

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:

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:

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 (lines 45-48), the repository demonstrates the standard setup:

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 (line 53), the Nebius key is loaded and injected into the voice pipeline:

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 (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:

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:

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, voice_agents/pipecat_agent/main.py, and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}