Microsoft Agent-Lightning Setup and Usage Guide

This guide describes how to use microsoft/agent-lightning to automatically optimize GIIP agent prompts.

🚀 Overview

Agent-Lightning is a framework for tuning agent prompts using reinforcement learning (RL). By leveraging task history as a dataset, it identifies the optimal instructions that lead to higher performance.

[!IMPORTANT] Windows User Notice: agent-lightning relies on Unix-only libraries. You must run it in WSL2 or a Linux environment.

🛠️ Installation (WSL2 / Linux)

1. Prepare Python Environment:

   # Python 3.10+ recommended
   python3 -m venv venv
   source venv/bin/activate

2. Install Library:

   pip install agentlightning

3. Set API Keys: Set environment variables so the training loop can call your LLM.

   export AZURE_OPENAI_API_KEY="your-key"
   export AZURE_OPENAI_ENDPOINT="your-endpoint"

📈 Usage Workflow

Step 1: Generate Training Data

Run the following command in your Windows terminal to convert project task logs into a dataset.

python giipdb/scripts/prompt_optimization/generate_dataset.py

Upon success, giipdb/scripts/prompt_optimization/giip_training_data.jsonl will be created.

Step 2: Start Reinforcement Learning (WSL2)

Use the generated dataset to tune your agent instructions.

# Execute in WSL terminal
python giipdb/scripts/prompt_optimization/train_giip_role.py

Step 3: Apply Optimized Results

Once training is complete, update the respective markdown files in the .agent/roles/ folder with the resulting Optimal Prompt.

📊 Benefits

• Improved Success Rates: Learn from past failures to prevent similar errors.
• Automated Prompt Engineering: Objectively optimize performance using data instead of manual tuning.
• Self-Improving System: Continuously elevate agent intelligence throughout the project lifecycle.

🩺 Troubleshooting

Symptom	Cause	Solution
Unix-library errors when installing or training on Windows	agent-lightning depends on Unix-only libraries	Run training (Step 2) in WSL2 or Linux. Perform only dataset generation (Step 1) on Windows
Dataset not found when running Step 2 training	Step 1 generate_dataset.py was not run, or the path differs	Run Step 1 first and confirm giipdb/scripts/prompt_optimization/giip_training_data.jsonl was created
Authentication error on the LLM call inside the training loop	AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT environment variables are not set	export both variables in the WSL session, then re-run
python: command not found or version error	Python is below 3.10, or the venv is not activated	Install Python 3.10+ and activate the virtual environment with source venv/bin/activate