Prerequisites

Infrastructure

• A BubbleRAN Cluster with MXK-PDK + MX-AI license.
• One or more GPU installed on the BubbleRAN Cluster OR an OpenAI API key.
  • If you already have an API key from another LLM provider, please contact us for support.

Software

• Python 3.12 or higher (3.13 recommended).
• The uv virtual environment and package manager (Optional).
• BubbleRAN Agentic Toolkit (bat-adk).

Others

• Basic notions about LangGraph, A2A (Agent-to-Agent) and MCP (Model Context Protocol).

AIFabric Custom Resource

The MX-AI license gives you access to the AIFabric resource managed by the odin-operator. An AIFabric is a resource that interconnects Agents with LLMs and MCP Servers:

• Agents: LLM-powered agents compliant to the A2A or MCP protocol. Take a look at the Catalog to see which Agents are currently available in the MX-AI Ecosystem.
• LLMs: LLM API endpoints descriptions, which can be used by agents to perform tasks. The currently supported LLM providers are OpenAI, Nvidia and Ollama. Other providers will be supported in the future: feel free to contact us if you need support for a specific provider.
• MCP Servers: Webservers exposing tools, prompts, datasets or other services in a standardized way for the agents.

The AIFabric resource also allows you to specify a frontend application (UI) to interact with all of these components.

Agent's Codebase setup

Agents in the MX-AI Ecosystem should be implemented as Python applications using the bat-adk library. The library facilitates the development of standard-compliant agents (A2A and MCP) and is based on the widely adopted LangGraph framework. In this guide, we provide suggestions on how to set up your agent's codebase, including the project structure, dependencies, and configuration files.

Although you may choose your own structure, as long as you remain compliant with the Agent2Agent standard, the following structure is already well tested and integrates perfectly with bat-adk and the MX-AI ecosystem. Furthermore, it will facilitate any request from support on BubbleRAN's side.

Agent2Agent (A2A)

A2A defines the way agents discover and communicate with each other. In this context, the only concept that you really need to understand about A2A, is the AgentCard.

The AgentCard is a JSON file that describes the agent's capabilities, inputs, outputs, and other metadata. It is accessible through a well defined API endpoint ./well-known/agent.json.

In MX-AI, the AgentCard is used by domain-specific agents to describe themselves to the orchestrator agent, which is responsible for assigning queries and tasks to the appropriate agents based on their capabilities.

For more details on the AgentCard, refer to the Agent2Agent documentation.

Codebase Setup

If you don't have uv installed, you can create a virtual environement and install it in there. Remember to activate the virtual environement every time you come back to work on the codebase.

python -m venv myvenv
source myvenv/bin/activate
pip install uv

⚠️ Important

You first need to create a virtual environment and install uv in it. Then, you will activate this environment and use uv to create a new environment for your project. This second environment is where all of your project's dependencies are going to be installed, as shown later.

You should not install any project's dependencies (e.g. bat-adk) inside the first virtual environment.

To set up your agent's codebase:

1. Create a new directory as your project root and navigate to it:

   mkdir my_agent
   cd my_agent/

2. Initialize a new uv project and create a virtual environment for it:

   uv init
   uv venv

   uv will create a pyproject.toml file in the project root, which is used to manage dependencies and project metadata. To add dependencies, you can use:

   uv add <package_name>

   For example, to add BAT you would run:

   uv add bat-adk

   The command will automatically update the pyproject.toml file with the new dependency.

   To install all the dependencies specified in pyproject.toml inside of the project's virtual environment, run:

   uv sync

   This will remove all the unnecessary packets that you may have installed in advance, and install all the missing ones.

3. Structure the rest of the codebase as follows:

   my_agent/
   ├── agent.json
   ├── config.yaml
   ├── .env
   ├── __init__.py
   ├── __main__.py
   ├── pyproject.toml
   ├── README.md
   ├── src/
   │   ├── graph.py
   │   ├── __init__.py
   │   └── llm_clients/
   │       ├── __init__.py
   │       └── ...
   ├── uv.lock
   └── .venv/

Available Labs

• Lab 1: Deploying an AIFabric: A simple lab to deploy an AIFabric resource.
• Lab 2: Building a Task-Specific Agent: A lab to implement your own task-specific agent from scratch using BAT.
• Lab 3: Integrating a Task-Specific Agent in MX-AI: A lab to integrate your task-specific agent into the MX-AI Ecosystem.
• Lab 4: End-to-End Anomaly Detection Experiment: A lab to deploy a baseline 5G network, inject interference using a second network, and validate anomaly detection and explainability through the anomaly detection agent.