Advanced AI agents for discrete event simulation using self-reflection and task planning
An intelligent agent system that demonstrates reasoning patterns for simulation experimentation through the Model Content Protocol (MCP). This project showcases two agent architectures—self-reflection and task planning—applied to a healthcare call centre optimization problem.
This pilot project explores how AI agents can autonomously discover, configure, and experiment with discrete event simulation models. By implementing advanced reasoning patterns like self-reflection and multi-step task planning, the agents can intelligently reason about simulation parameters, learn from validation failures, and run models based on natural language interaction.
- 🧠 Self-Reflection Agent: Uses LangGraph state machines to iteratively refine parameters through validation feedback loops
- 📋 Planning Agent: Employs LangChain and a dual-LLM architecture for task decomposition and execution planning
- 🔄 MCP Integration: Uses the Model Content Protocol for standardized tool and resource access to the simulation model
- ⚡ Intelligent Parameter Generation: Converts natural language to structured simulation parameters with validation
- 🎯 Application: Healthcare call centre optimization with nurse callback modeling
The system consists of three main layers connected through the Model Content Protocol:
Two complementary agent architectures demonstrate different reasoning approaches:
Planning Agent (agent_planning_workflow.py)
- Dual LLM Architecture: Separate models for reasoning/planning and result summarization
- Dynamic Task Planning: LLM generates step-by-step execution plans from available MCP capabilities
- Memory-Driven Execution: Maintains state between plan steps for complex workflows
- Flexible Model Selection: Command-line options for different LLM models and debug modes
Self-Reflection Agent (agent_self_reflection.py)
- LangGraph State Machine: Graph-based workflow with conditional routing and retry logic
- Validation-Driven Learning: Analyzes parameter validation failures and iteratively improves
- Bounded Retry Logic: Intelligent bailout mechanisms prevent infinite loops
- Failure Analysis: Tracks validation history and provides detailed error reporting
FastMCP Server (mcp_server.py) provides standardized access to:
- 🛠️ Tools: Simulation execution and parameter validation
- 📚 Resources: Schema definition for the model parameters and model documentation
- 💬 Prompts: LLM templates for parameter generation
- 🔍 Auto-Discovery: Dynamic capability enumeration for agent planning
Healthcare Call Centre Model (model.py) - A simple discrete event simulation featuring:
- 👥 Resources: Call operators and nurses with configurable capacity
- 📞 Patient Flow: Exponential arrival patterns with triangular service times
- 🔄 Nurse Callbacks: 40% of patients require follow-up consultations
- 📊 Performance Metrics: Wait times, utilization rates, and callback statistics
- 🎲 Stochastic Modeling: Multiple probability distributions (Exponential, Triangular, Uniform, Bernoulli)
- 🔀 Multiple Random Streams: Reproducible results, using common random numbers
- ⏱️ Event-Driven Processing:
SimPybased discrete event engine - 🎛️ Configurable Parameters: Staff levels, demand patterns, service times, callback probabilities
- Mean waiting times for operators and nurses
- Resource utilization rates for staff optimization
- Callback rates for service quality assessment
- Patient throughput for capacity planning
- Python 3.11+
- Ollama server running locally
- Mamba/conda or pip for environment management
This project was developed and tested on the following system configuration:
Hardware Specifications:
- System: Dell XPS 8960
- CPU: 13th Gen Intel i9-13900K (32 cores) @ 5.900GHz
- GPU: NVIDIA GeForce RTX 4080
- RAM: 64GB
- Operating System: Ubuntu 24.04
Performance Notes:
- LLM inference with larger models (gemma3:27b, deepseek-r1:32b) benefits significantly from the high-core CPU and substantial RAM
- GPU acceleration is utilized for compatible models through Ollama
- The system handles concurrent agent execution and simulation processing efficiently
Note: While these specifications represent the development environment, the project can run on more modest hardware configurations. Minimum requirements are Python 3.11+ and sufficient RAM for your chosen LLM models.
-
Clone the repository
git clone https://github.com/pythonhealthdatascience/des_agent cd des-agent -
Create and activate environment
# Using mamba (recommended) mamba env create -f environment.yml mamba activate des-agent# Or using pip pip install fastmcp pandas simpy langgraph langchain langchain-ollama rich -
Set up Ollama models
# Install recommended models ollama pull gemma3:27b # Best performance for planning and parameter generation ollama pull llama3:latest # Good for summarization ollama pull mistral:7b # Potentially faster alternative for self-reflection
-
Start the MCP server
python mcp_server.py
Server will be available at
http://localhost:8001/mcp -
Run the Self-Reflection Agent
python agent_self_reflection.py --llm gemma3:27b
Example interaction:
Simulation request: Simulate 14 operators, 12 nurses and 5% extra demand -
Run the Planning Agent
python agent_planning_workflow.py --planning gemma3:27b --summary llama3:latest
The self-reflection agent demonstrates error recovery and learning:
python agent_self_reflection.py --llm gemma3:27bNatural Language Input:
"Simulate 14 operators, 12 nurses and 5% extra demand""Run scenario with high staffing and normal call volume""Test configuration with minimal staff"
Key Features:
- ✅ Automatic Parameter Validation: Catches invalid parameters and self-corrects
- 🔄 Retry Logic: Up to 4 attempts with validation feedback incorporation
- 📈 Learning from Errors: Uses validation messages to improve subsequent attempts
- 📊 Detailed Reporting: Shows validation history and failure analysis
The planning agent showcases sophisticated task decomposition:
python agent_planning_workflow.py --planning gemma3:27b --summary llama3:latest --debugWorkflow Demonstration:
- 🧠 Task Planning: LLM analyzes available MCP capabilities and creates execution plan
- 📋 Step Execution: Dynamically executes each planned step (resource queries, parameter generation, validation, simulation)
- 💾 Memory Management: Maintains state between steps for complex workflows
- 📊 Result Formatting: Second LLM summarizes parameters and results in structured tables
Both agents support flexible LLM model configuration:
# Self-reflection agent
python agent_self_reflection.py --llm mistral:7b
# Planning agent with dual models
python agent_planning_workflow.py \
--planning deepseek-r1:32b \
--summary llama3.1:8b \
--debugThe healthcare call centre model supports extensive configuration through the JSON schema:
{
"n_operators": 14, // Call operators (1-100)
"n_nurses": 12, // Nurses for callbacks (1-50)
"mean_iat": 0.57, // Inter-arrival time (0.1-10.0 minutes)
"call_low": 5.0, // Min call duration
"call_mode": 7.0, // Most likely call duration
"call_high": 10.0, // Max call duration
"callback_prob": 0.4, // Nurse callback probability (0-1)
"nurse_consult_low": 10.0, // Min nurse consultation time
"nurse_consult_high": 20.0, // Max nurse consultation time
"run_length": 1000, // Simulation runtime (minutes)
"random_seed": 42 // For reproducible results
}The LangGraph-based agent demonstrates sophisticated error handling:
- 🔍 Validation Analysis: Parses structured error messages from parameter validation
- 🔄 Iterative Improvement: Incorporates feedback into subsequent parameter generation attempts
- 📊 History Tracking: Maintains detailed logs of validation attempts and outcomes
- 🎯 Bounded Retry: Intelligent bailout after maximum attempts to prevent infinite loops
The planning agent showcases advanced reasoning about task decomposition:
- 🧠 Dynamic Planning: Generates execution plans based on available MCP server capabilities
- 📋 Step-by-Step Execution: Breaks complex requests into manageable subtasks
- 🔗 Dependency Management: Ensures information dependencies are resolved in correct order
- 💾 Stateful Execution: Maintains memory across plan steps for complex workflows
Both agents leverage the full Model Content Protocol specification:
- 🛠️ Tool Discovery: Dynamic enumeration of available simulation and validation tools
- 📚 Resource Access: Automatic retrieval of schemas, documentation, and configuration data
- 💬 Prompt Templates: Server-provided LLM prompts ensure consistent parameter generation
- 🔄 Standardized Communication: JSON-RPC messaging for reliable agent-server interaction
The healthcare model provides the following performance metrics:
| Metric | Description | Use Case |
|---|---|---|
| Mean Waiting Time | Average time patients wait for operators | Service quality assessment |
| Operator Utilization | Percentage of time operators are busy | Staffing optimization |
| Nurse Waiting Time | Average wait for nurse callbacks | Callback service efficiency |
| Nurse Utilization | Percentage of nurse availability used | Nurse staffing planning |
| Callback Rate | Percentage of calls requiring nurse follow-up | Service complexity analysis |
This project demonstrates several cutting-edge research areas:
- 🔄 Self-Reflection: How agents can learn from failures and iteratively improve
- 📋 Task Planning: LLM-driven decomposition of complex multi-step workflows
- 🧠 Meta-Reasoning: Agents reasoning about their own reasoning processes
- 🤖 AI-Driven Modeling: Natural language interfaces for complex simulation configuration
- ⚡ Automated Experimentation: Agents conducting systematic simulation studies
- 📊 Intelligent Analysis: Automated interpretation of simulation results
- 🌐 MCP Adoption: Practical implementation of Anthropic's Model Content Protocol
- 🔧 Tool Integration: Seamless connection of AI agents with external systems
- 📋 Capability Discovery: Dynamic enumeration and utilization of available tools
- 👥 Agent Collaboration: Multiple agents working together on complex experiments
- 🎯 Specialized Roles: Planning, execution, analysis, and reporting agents
- 🔄 Workflow Coordination: Advanced orchestration patterns for simulation studiea
- 🏥 Multi-Model Support: Integration with diverse simulation domains beyond healthcare
- 📊 Real-time Analytics: Live dashboard updates during simulation execution
- 🎛️ Interactive Parameter Tuning: Dynamic adjustment of simulation parameters
- 🧠 Causal Reasoning: Understanding cause-and-effect relationships in simulation results
- 📈 Optimization Integration: Automatic parameter optimization using simulation feedback
- 🎯 Goal-Oriented Planning: Agents working backwards from desired outcomes
MCP Server Connection Failed
- Ensure the MCP server is running on
http://localhost:8001/mcp - Check that no other processes are using port 8001
- Verify FastMCP installation:
pip install fastmcp
Ollama Model Not Found
- Confirm model installation:
ollama list - Pull missing models:
ollama pull gemma3:27b - Check Ollama server status:
ollama serve
Parameter Validation Failures
- Review the schema.json file for parameter constraints
- Ensure numeric values are within specified ranges
- Verify all required parameters are provided
Agent Timeout or Performance Issues
- Try smaller LLM models (e.g.,
llama3:latestinstead ofgemma3:27b) - Increase retry limits in agent configuration
- Monitor system resources during execution
For additional support, please open an issue with detailed error logs and system information.
This project welcomes contributions in several areas:
- 🔬 New Agent Architectures: Alternative reasoning patterns and workflow designs
- 🏥 Simulation Models: Additional domains and model types
- 🛠️ MCP Extensions: New tools, resources, and capabilities
- 📊 Analysis Features: Enhanced result interpretation and visualization
This project is released under the MIT License. See LICENSE file for details.
Built for the future of intelligent simulation 🚀
This project demonstrates advanced AI agent capabilities for simulation experimentation, showcasing self-reflection, task planning, and protocol standardization through practical healthcare optimization applications.