FlexNGIA 2.0 Congestion Control Agent - Tutorial

QuickStart: How to run FlexNGIA 2.0 congestion control agent?

FlexNGIA 2.0 proposes a TCP Congestion Control (CC) Agent for TCP [PDF, POSTERS, BibTeX] integrated into Linux kernel to perform the following tasks (see Figure 1):

Evaluate the current runtime status, application performance, and network characteristics.
Make one of the following TCP congestion control decisions at runtime:

Keep the current TCP CC scheme and adjust its parameters.
Switch to an existing TCP CC scheme.
Design, implement, and deploy a new TCP CC scheme.

Figure 1 - Operation of the Congestion Control Agent

To experiment with the FlexNGIA 2.0 CC agent and reproduce the presented experimental results and potentially build on it to create your own CC agent, we provide a preconfigured virtual machine (VM) implementing the CC agent.

The VM runs Ubuntu 24.04 LTS and includes all required dependencies and components needed to execute the experiments. The VM contains the following components:

Linux Kernel 6.13.7: patched with a real-time TCP monitoring module developed and used in [PDF, BibTex].
Mininet-WiFi: wireless network emulator (https://mininet-wifi.github.io/).
Floodlight SDN Controller: to control the mininet.
CC Agent implementation: implemented in Python and responsible for dynamically managing congestion control strategies during experiments.

In the following you will find how to set up the environment

Setting up the environment

Download and Launch the VM: Download the provided VM image (format .ova) using this link (8 GB to download and 20GB when uncompressed), then open it with Oracle VirtualBox or VMware Workstation. The username/password are: FlexNGIA/flexngia (use “flexngiq” as password if your keyboard is Azerty)
Run to get the latest version of the CC agent:

git fetch https://github.com/Youneskr/FlexNGIA-2.0.git && git reset --hard FETCH_HEAD

Test the access to the LLM:If there is a problem accessing the LLM, please make sure the VM has access to the Internet and check whether the LLM API is still valid.

To generate a new API key or to change the LLM’s provider, model, and temperature, please check this Section “How to customize the CC Agent?”

Running Experiments

Start the Floodlight SDN Controller: launch the VM, open a terminal and run the command “floodlight” to start the Floodlight controller. Keep this terminal open.

FlexNGIA@flexngia-vm:~$ floodlight

Start the CC Agent: Keep the first terminal open and open another one. Start the CC agent using the following command:

sudo agent/venv/bin/python agent/main.py

Once started, the agent enters a listening state, waiting for a new Mininet experiment to be launched. During the experiments, it receives IFA_Report every 60 seconds and dynamically adjusts congestion control behavior.

Keep the terminal open to make sure the agent is running.

Start a New Experiment: Now open another terminal (make sure to keep other terminals open), then start the following script:

sudo ./run_test.sh

This script launches the Mininet-WiFi emulator, creates the network below (Figure 2), and launches a TCP server on Host 2, starts a TCP client on Host 1 using a single connection to send traffic towards Host 2 for 200 seconds. This connection uses TCP Reno as the default congestion control algorithm. The CC agent is operating in Host 1 where it is in charge of the management of the congestion control for this particular TCP connection.

Figure 2. Simulated topology

Experimental Results: Traces and Figures

The results of the experiments are stored in a folder “EXP{ID}” where the {ID} is an automatically-generated ID for the experiment. It contains the following sub-directories:

TCPTraces: it contains a file with metrics related to TCP (CC window, throughput, loss, RTT) are collected during the experiment and stored in the directory results/{experiment_ID}, where {experiment_ID} is an automatically-generated ID for the experiment.
Figures: it contains several figures showing measurement of key performance metrics (throughput, cc window, RTT) during the experiment.
AgentTraces: it contains the IFA reports and the output of the agent at each evaluation interval (set to 60 seconds). For instance “IFA_Report_1.txt”^[d] contains the report during the evaluation interval 1. LLM outputs (name{EI}}^[e]^[f]: it corresponds to the output of the LLM and contain the step-by-step reasoning and decisions of the agent at the evaluation interval {EI} which follows the format defined the output schema (sample of an LLM Output). LLM_CC_V0_5: contains the CC code generated by the LLM for 0 at the evaluation interval 5 (sample of a generated code)

How to customize the CC Agent?

In the following, we demonstrate how to modify the agent’s configuration, including the LLM provider, the selected model, and its temperature. We also show how to customize the agent’s reasoning steps, decision-making process, output format, as well as the instructions and templates used for algorithm synthesis.

Select and Configure the Agent’s LLM

The CC agent implemented in the provided VM is configured to use a free API key offered by Groq and the model llama-3.3-70b-versatile.

However, you can change the LLM provider (e.g., Groq, OpenAI, or Google Gemini), the LLM model and temperature as well as the API key by modifying the content of the file cc-agent/agent/.env.

Customize the System Prompt

The CC Agent relies on a system prompt to guide its decision-making process, including analysis steps. This prompt is available in the VM at agent/system_prompt.txt.

You can customize it in order to modify the agent’s behavior, reasoning steps, congestion control selection criteria, output format and structure, as well as the CC module template.

Update the Agent’s Output Schema

The LLM generates a structured output. This output might contain its reasoning steps, decision and the generated CC algorithm or any other information that you might request from the LLM.

The output format is defined in agent/schemas.py and it is organized into fields. You can modify existing fields in the output or add new fields. For instance, you can add this line to add a new output field where you request the LLM to provide an analysis of the performance of the current CC scheme:

step_9: str = Field(description="analyze the performance of the current CC scheme)").

Note that ideally the system prompt should be aligned with the expected output format (e.g., same number of steps or code structure) to maintain consistent results.

Modify the IFA Report Structure

You can modify the IFA Report structure in the following file: cc-agent/agent/IFA_Report_Template.j2

CC Management tool: A new tool to manage CC schemes in Linux System

The CC tool allows the management of congestion control modules (algorithms) available in a Linux system. In particular, it allows providing the basic information about congestion control schemes currently available in the system, and also to load, unload, activate, or rename CC modules.

A CC module (i.e., CC algorithm) can be:

Built-in (provided by the Linux kernel like TCP Reno)
LLM-generated (generated by the CC agent)
Trace-derived (imported from experiment traces)^[h]

The cc tool supports the following options to manage congestion control modules:

-ls: list all available modules with details
-l: list module names only
-s <module>: load (compile and insert) a module into the kernel
-a <module>: activate a congestion control module
-d <module> "description" : add or update a module description
-d <module> : display the module description
-d <module> --clear : remove the module description
-r <old> <new>: create a renamed copy of a module (with updated internal references)
-u <module>: unload a module from the kernel (cannot unload built-in or active modules)

To run the cc command : sudo cc [option + parameters]