A production-grade multi-agent system where specialised AI agents collaborate to analyse, risk-assess, and optimise complex project schedules. Built with LangGraph-inspired architecture, Claude API integration, enterprise resilience patterns, and zero-dependency deterministic fallbacks.
Project schedules are complex dependency networks. Finding the critical path, detecting circular logic, identifying risk bottlenecks, and recommending optimisations requires deep domain expertise and meticulous analysis. Most scheduling tools provide raw data reports — they don't reason about the schedule the way an expert planner would.
This system deploys three specialised AI agents that collaborate like a team of expert planners:
| Agent | Role | Responsibility |
|---|---|---|
| 🧠 Scheduler Agent | Structural Analyst | Computes critical path, detects circular dependencies, validates logic ties |
| Risk Assessor | Identifies bottlenecks, near-critical activities, and anomaly patterns | |
| 📈 Optimiser Agent | Improvement Advisor | Generates actionable recommendations to compress schedule and reduce risk |
Each agent runs as an independent node with its own state, memory, and tool access — orchestrated by a supervisor that manages routing, error recovery, and result aggregation.
┌─────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (Supervisor) │
│ Routes messages · Manages state · Handles errors · Aggregates │
└──────┬──────────────────────┬──────────────────────┬──────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCHEDULER │ │ RISK │ │ OPTIMISER │
│ AGENT │ │ AGENT │ │ AGENT │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ • CPM calc │ │ • Bottleneck │ │ • Schedule │
│ • Topo sort │ │ detection │ │ compression│
│ • Cycle detect│ │ • Float │ │ • Resource │
│ • Float calc │ │ analysis │ │ levelling │
│ • Forward/ │ │ • Anomaly │ │ • Risk │
│ backward │ │ scanning │ │ mitigation │
│ pass │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
▼
┌──────────────────────┐
│ Structured Report │
│ (JSON + Human) │
└──────────────────────┘
| Decision | Rationale |
|---|---|
| Deterministic-first architecture | Core CPM analysis runs without LLM dependency — schedule logic is always correct |
| LLM augmentation on top | Claude API enriches analysis with natural language reasoning when available |
| Graceful degradation | Every agent has a fallback — the system works even without API keys |
| Pydantic validation | All data passes through strict schemas — no silent failures |
| Circuit breaker pattern | Protects against cascading API failures with auto-recovery |
| Layer | Technology |
|---|---|
| Language | Python 3.11+ (typed, async-capable) |
| Data Models | Pydantic v2 — strict validation, JSON serialisation |
| LLM Integration | Anthropic Claude (optional, with tool-use support) |
| Resilience | Custom retry, circuit breaker, fallback handler |
| Testing | pytest — unit + integration tests |
| Containerisation | Docker + docker-compose |
| CI/CD | GitHub Actions — lint, test, verify on every push |
- Python 3.11+
- (Optional) Anthropic API key for LLM-enriched analysis
# Clone the repository
git clone https://github.com/koate-kpai/ai-agent-engineer.git
cd ai-agent-engineer
# Install dependencies
pip install -r requirements.txt
# Install package in development mode
pip install -e .# Generate a sample schedule and run analysis
python -m src.main --generate-sample
python -m src.main data/sample_schedule.csv
# Run with Claude LLM enrichment (requires ANTHROPIC_API_KEY)
export ANTHROPIC_API_KEY="sk-ant-..."
python -m src.main data/sample_schedule.csv --log-level INFO
# JSON output for programmatic consumption
python -m src.main data/sample_schedule.csv --json
# Docker
docker compose up============================================================
SCHEDULE ANALYSIS REPORT: sample_schedule
============================================================
Total Activities: 10
Critical Path Duration: 62 days
Critical Path: A1000 -> A1010 -> A1020 -> A1040 -> A1050 -> A1060 -> A1070
[SCHEDULER AGENT]
Critical path validated — no circular dependencies detected.
[RISK AGENT]
Bottleneck identified: A1020 (System Design) — float = 0, on critical path.
[OPTIMISER AGENT]
1. Fast-track A1030 (Data Migration) to run parallel with A1020
2. Add resource buffer to A1040 (Dev Sprint 1) — highest cost activity
ai-agent-engineer/
├── src/
│ ├── __init__.py
│ ├── main.py # CLI entry point
│ ├── schedule.py # Pydantic data models
│ ├── analyzer.py # Deterministic CPM schedule analysis
│ ├── agent.py # Multi-agent orchestration system
│ ├── llm_client.py # Claude API integration
│ ├── resilience.py # Retry, circuit breaker, fallback
│ └── logging_config.py # Structured logging setup
├── tests/
│ ├── test_schedule.py # Model validation tests
│ ├── test_analyzer.py # CPM logic tests
│ ├── test_agent.py # Agent orchestration tests
│ └── test_resilience.py # Resilience pattern tests
├── data/
│ └── sample_schedule.csv # Sample project schedule
├── config/
│ └── config.yaml # Application configuration
├── .github/workflows/ci.yml # CI pipeline
├── Dockerfile # Container definition
├── docker-compose.yml # Container orchestration
├── requirements.txt # Python dependencies
├── pyproject.toml # Project metadata
└── README.md # You are here
This system implements production-grade resilience patterns:
| Pattern | Implementation | What It Prevents |
|---|---|---|
| Retry with backoff | @retry(max_attempts=3, backoff_factor=2.0) |
Transient API failures |
| Circuit breaker | CircuitBreaker(failure_threshold=5) |
Cascading failures — opens after 5 errors, auto-recovers after 30s |
| Fallback handler | @FallbackHandler(fallback_func=...) |
Every agent node has a degradation path |
| Graceful degradation | LLM enrichment is optional — core analysis always works | Zero API dependency for basic functionality |
# Run all tests
python -m pytest tests/ -v
# Run with coverage
pip install pytest-cov
python -m pytest tests/ --cov=src --cov-report=term-missingCurrent test coverage:
- Schedule models — creation, validation, topological ordering
- CPM analysis — forward pass, backward pass, critical path, cycle detection
- Agent orchestration — multi-agent run, output aggregation, error recovery
- Resilience patterns — retry logic, circuit breaker states, fallback execution
This project demonstrates exactly what the role demands:
- Agentic workflow design — Multi-agent system with delegation, state management, and result aggregation
- LLM integration — Claude API with tool-use for structured data analysis
- System resilience — Production-grade error handling, retries, circuit breakers
- Domain expertise applied — 20 years of scheduling logic built into deterministic CPM engine
- Production engineering — Type hints, Pydantic validation, Docker, CI/CD, comprehensive tests
George Kpai, PMP, PRINCE2
20 years building complex dependency networks and quantitative logic systems for £1.2B+ infrastructure programmes. Now pivoting into AI engineering — combining deep domain expertise with production-grade Python and modern AI agent frameworks.
- Email: georgekpai@gmail.com
- GitHub: github.com/koate-kpai
MIT