BubbleRAN Agent Labs

These labs show you how to run AI agents on MX-PDK, and how to build your own agent and add it next to them.

Lab 1: Deploy an agentic blueprint           ready-made agents, in your cluster
   │
Lab 2: Develop a custom agent                your agent, on your computer
   │
Lab 3: Connect your agent to the cluster     your agent, using an agent of the cluster
   │
Lab 4: Onboard a custom agent                your agent, in your cluster
   │
Lab 5: Evaluate your agent                   a test set, scored by bat

Do the labs in order: each lab uses what you built in the previous one.

In the sample outputs, /home/you stands for your own home folder. Dates, times and numbers will also differ from yours.

Prerequisites

For all labs

• MX-PDK O-RAN, AI-RAN or CAMPUS.
• The brc command line and MX-UI. Both come with MX-PDK.
• An LLM for the agents. The labs use OpenAI, with your OpenAI API key. You can also use another provider, free-tier LLMs or local models: see Choose your LLM.

For Labs 2 to 5

• A Linux or macOS computer with curl and make. You can also work directly on the cluster master node.
• If you work on your own computer: SSH access to the cluster master node (Labs 3 to 5).
• Docker (Lab 4).
• A container registry where you can push images (Lab 4). If you don't have one, Lab 4 gives you a ready-made image.
• Basic Python knowledge.

Terminology

Term	What it means
Agent	A program that uses an LLM to do one kind of task. You send it a question, and it sends back an answer.
LLM	Large Language Model, such as GPT. The "brain" an agent uses to understand the question and write the answer.
MCP server	A server that gives agents tools or data, for example access to the metrics database.
A2A	Agent-to-Agent: the protocol agents use to talk to each other over HTTP.
Agent card	A short JSON file that describes an agent: its name, what it does, and example questions. Other agents read it to decide when to call the agent.
Blueprint	A set of agents about one topic, shipped as one container image. For example, the Observability blueprint has agents for KPIs, topology, logs and more.
CompositionModel	The catalog of a blueprint: it lists its agents and how to run each one. Each entry is a mode, written <model>/<mode>, for example observability/kpi.
AIFabric	A YAML file that says which agents to run together, which LLM they use and which MCP servers they can reach. The cluster reads it and starts everything.
Supervisor	An agent that receives your question, decides which agents can answer it, asks them, and writes the final answer.
Worker	An agent that does one kind of task. The supervisor can call every worker.
Element	What the cluster creates for each agent of an AIFabric: a running program and an address (a Kubernetes Service) to reach it.
Port-forward	A temporary tunnel from your computer to a Service inside the cluster.

Choose your LLM

The agents need an LLM. The labs assume you use OpenAI: every example uses the openai provider, with your OpenAI API key stored in a Kubernetes Secret. If you use another LLM, follow the labs as they are and make the changes listed in Using another LLM.

Create the OpenAI API key Secret

Agents read the API key from a Kubernetes Secret, so that the key is never written in your AIFabric files. Create the Secret once, on the cluster master node:

kubectl -n trirematics create secret generic openai-api-key \
  --from-literal=OPENAI_API_KEY=<YOUR_API_KEY>

Replace <YOUR_API_KEY> with your key.

You should see:

secret/openai-api-key created

⚠️ Important

A Kubernetes Secret is not encrypted: anyone who can read Secrets in the cluster can read your key. Only give cluster access to people you trust.

Using another LLM

You can also use one of these:

You want	Use	What to prepare
Another cloud provider	Anthropic, DeepSeek or NVIDIA, with your API key	The Secret above, with the provider's names instead of OpenAI's. For example, for Anthropic: anthropic-api-key and ANTHROPIC_API_KEY.
Free-tier cloud LLMs, with no paid key	OmniRoute, which runs in your cluster and puts the free tiers of many providers behind one address	An OmniRoute API key and its Secret: see the OmniRoute guide.
Local models, on your own hardware	Ollama, which runs open models such as gpt-oss on a GPU of your cluster	No API key and no Secret are needed. See the Ollama guide.

The inference overview helps you choose between OmniRoute and Ollama.

Then, as you follow the labs, make these changes.

Lab 1: the llms part of the AIFabric. Replace it with the entry for your LLM. Keep name: openai: it is only a label, and the agents use it.

The llms entries (click to open)

With another cloud provider, change provider, model and the Secret names. For example, with Anthropic:

  llms:
    - name: openai
      provider: anthropic
      model: <an Anthropic model>
      apiKeySecretRef:
        name: anthropic-api-key
        key: ANTHROPIC_API_KEY

With OmniRoute (auto lets OmniRoute pick a provider for each request; you can also write a model ID, see the OmniRoute guide):

  llms:
    - name: openai
      provider: openai
      model: auto
      endpoint:
        baseUrl: http://omniroute.inference.svc.cluster.local:20128/v1
      apiKeySecretRef:
        name: omniroute-api-key
        key: OPENAI_API_KEY

With Ollama (pick a model you pulled, see the Ollama guide):

  llms:
    - name: openai
      provider: ollama
      model: gpt-oss:20b

Labs 2 and 3: your agent on your computer. In the model part of config.yaml, set the same provider and name (the model) as in the AIFabric. Then:

You use	In .env	In pyproject.toml	Also
Another cloud provider	Its key, for example ANTHROPIC_API_KEY=...	bat-adk[anthropic,telemetry] instead of bat-adk[openai,telemetry] (the provider's name)	—
OmniRoute	OPENAI_API_KEY= your OmniRoute key	No change	Port-forward it on the master node with kubectl -n inference port-forward svc/omniroute 20128, and add base_url: http://localhost:20128/v1 to model.
Ollama	No key	bat-adk[ollama,telemetry] instead of bat-adk[openai,telemetry]	Port-forward it on the master node with kubectl -n inference port-forward svc/ollama 11434, and add base_url: http://localhost:11434 to model.

The port-forwards work like the one to the KPI agent in Lab 3. If you work on your own computer, also carry the port over SSH, for example ssh -L 9310:localhost:9310 -L 11434:localhost:11434 <user>@<master-node>.

Lab 4: no other change is needed.

Lab 5: in eval.yaml, write the same provider and model in models and in judge as in config.yaml, with the same base_url for OmniRoute or Ollama.

Available Labs

• Lab 1: Deploy an agentic blueprint: run a supervisor and two agents of the Observability blueprint, and chat with them in MX-UI.
• Lab 2: Develop a custom agent: build a small agent with the BAT CLI and BAT ADK on your computer: an LLM that uses a tool, in a ReAct loop.
• Lab 3: Connect your agent to the cluster: make your agent ask an agent running in the cluster, through a port-forward.
• Lab 4: Onboard a custom agent: put your agent in a container image, describe it in a CompositionModel, and add it to the AIFabric of Lab 1.
• Lab 5: Evaluate your agent: write a test set for the Throughput Checker, run it with bat eval, and score every answer with exact checks and an LLM judge.

Getting help

If you are stuck, contact BubbleRAN customer support through your usual support channel. Tell them which lab and which step you are on, and copy the error message you see.