agentic-fleet

Self-Optimizing Multi-Agent Orchestration

Intelligent task routing with DSPy • Robust execution with Microsoft Agent Framework

---

✨ What is AgenticFleet?

AgenticFleet is a production-oriented multi-agent orchestration system that automatically routes tasks to specialized AI agents and orchestrates their execution through a self-optimizing 5-phase pipeline.

The 5-Phase Pipeline

Every task flows through intelligent orchestration:

┌─────────┐    ┌─────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐
│ANALYSIS │───►│ ROUTING │───►│ EXECUTION │───►│ PROGRESS │───►│ QUALITY │
│         │    │         │    │           │    │          │    │         │
│Complexity│    │Agent(s) │    │Delegated/ │    │Complete? │    │Score    │
│Skills    │    │Mode     │    │Sequential/│    │Refine?   │    │0-10     │
│Tools     │    │Subtasks │    │Parallel   │    │Continue? │    │Feedback │
└─────────┘    └─────────┘    └───────────┘    └──────────┘    └─────────┘

How it works:

1. Analysis – DSPy analyzes task complexity, required skills, and recommended tools
2. Routing – Intelligent selection of agents and execution mode based on learned patterns
3. Execution – Agents work in parallel, sequence, or delegation with tool access
4. Progress – Evaluates if task is complete or needs refinement
5. Quality – Scores output (0-10) and identifies missing elements

Key Features

• 🧠 DSPy-Powered Intelligence – Typed signatures with Pydantic validation for reliable structured outputs
• 🔄 6 Execution Modes – Auto, Delegated, Sequential, Parallel, Handoff, and Discussion
• 🎯 9+ Specialized Agents – Researcher, Analyst, Writer, Reviewer, Coder, Planner, Executor, Verifier, Generator
• ⚡ Smart Fast-Path – Simple queries bypass multi-agent routing (<1s response)
• 🛠️ Tool Integration – Web search (Tavily), code execution, browser automation, MCP tools
• 🧍 Human-in-the-Loop (HITL) – Request/response events can pause execution until the user responds
• ♻️ Checkpoint Resume – Resume interrupted runs using agent-framework checkpoint semantics
• 📈 Self-Improvement – Learns from execution history to improve routing decisions
• 📊 Built-in Evaluation – Azure AI Evaluation integration for quality metrics
• 🔍 OpenTelemetry Tracing – Full observability with Jaeger and Azure Monitor export

🚀 Quick Start

Installation

# Clone and install
git clone https://github.com/Qredence/agentic-fleet.git && cd agentic-fleet
uv sync  # or: pip install agentic-fleet

# Configure environment
cp .env.example .env
# Set OPENAI_API_KEY (required)
# Set TAVILY_API_KEY (optional, enables web search)

Run

# Interactive CLI
agentic-fleet

# Single task
agentic-fleet run -m "Research the latest advances in AI agents" --verbose

# Development server (backend + frontend)
agentic-fleet dev

📖 Usage

CLI

agentic-fleet                              # Interactive console
agentic-fleet run -m "Your task"           # Execute a task
agentic-fleet run -m "Query" --mode handoff  # Specific execution mode
agentic-fleet list-agents                  # Show available agents
agentic-fleet dev                          # Start dev servers

Python API

import asyncio
from agentic_fleet.workflows import create_supervisor_workflow

async def main():
    workflow = await create_supervisor_workflow()
    result = await workflow.run("Summarize the transformer architecture")
    print(result["result"])

asyncio.run(main())

Web Interface

agentic-fleet dev  # Backend: http://localhost:8000, Frontend: http://localhost:5173

The web interface provides:

• Real-time streaming responses with workflow visualization
• Conversation history with persistence
• Agent activity display and orchestration insights

Notes:

• The fast-path is intended for first-turn/simple prompts; follow-up turns in an existing conversation are routed through the full workflow so history is respected.
• For advanced streaming semantics (HITL responses and checkpoint resume), see the Frontend Guide.

🤖 Agents & Execution Modes

Specialized Agents

Execution Modes

⚙️ Configuration

Environment Variables

# Required
OPENAI_API_KEY=sk-...

# Optional
TAVILY_API_KEY=tvly-...              # Web search capability
DSPY_COMPILE=true                    # Enable DSPy optimization
ENABLE_OTEL=true                     # OpenTelemetry tracing
OTLP_ENDPOINT=http://...             # Tracing endpoint
ENABLE_SENSITIVE_DATA=true           # Capture prompts in traces/telemetry (default: false)
AGENTICFLEET_USE_COSMOS=true         # Enable Azure Cosmos DB integration
AGENTICFLEET_DEFAULT_USER_ID=user123 # Default user ID for multi-tenant scoping

Workflow Configuration

All runtime settings are in src/agentic_fleet/config/workflow_config.yaml:

dspy:
  model: gpt-5.2 # Primary model for DSPy tasks
  routing_model: grok-4-fast # Fast model for routing decisions
  use_typed_signatures: true # Pydantic-validated outputs
  enable_routing_cache: true # Cache routing decisions
  routing_cache_ttl_seconds: 300 # Cache TTL (5 minutes)

workflow:
  supervisor:
    max_rounds: 15
    enable_streaming: true
  quality:
    refinement_threshold: 8.0
    enable_refinement: false # Disabled for speed

agents:
  researcher:
    model: gpt-4.1-mini
    tools: [TavilySearchTool]
  coder:
    model: gpt-5.1-codex-mini
    tools: [HostedCodeInterpreterTool]

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Entry Points                                    │
│    ┌─────────┐         ┌─────────┐         ┌─────────────────────────┐      │
│    │   CLI   │         │ Web UI  │         │      Python API         │      │
│    │ (Typer) │         │ (React) │         │ create_supervisor_      │      │
│    │         │         │         │         │ workflow()              │      │
│    └────┬────┘         └────┬────┘         └───────────┬─────────────┘      │
│         └──────────────────┬┴──────────────────────────┘                    │
│                            │                                                │
│                   ┌────────▼────────┐                                       │
│                   │ SupervisorWorkflow │ ◄── 5-Phase Pipeline               │
│                   └────────┬────────┘                                       │
│         ┌──────────────────┼──────────────────┐                             │
│         │                  │                  │                             │
│  ┌──────▼──────┐   ┌───────▼───────┐  ┌──────▼──────┐                       │
│  │DSPyReasoner │   │  AgentFactory │  │ ToolRegistry│                       │
│  │ (Analysis,  │   │ (Creates      │  │ (Tavily,    │                       │
│  │  Routing,   │   │  Specialized  │  │  Code, MCP) │                       │
│  │  Quality)   │   │  Agents)      │  │             │                       │
│  └─────────────┘   └───────────────┘  └─────────────┘                       │
└─────────────────────────────────────────────────────────────────────────────┘

Directory Structure

src/agentic_fleet/
├── workflows/        # Orchestration: supervisor.py (entry), executors.py (5 phases)
│   ├── supervisor.py # Main workflow entry + fast-path detection
│   ├── executors.py  # AnalysisExecutor, RoutingExecutor, ExecutionExecutor, etc.
│   └── strategies.py # Execution modes (delegated/sequential/parallel)
├── dspy_modules/     # DSPy intelligence layer
│   ├── reasoner.py   # DSPyReasoner (orchestrates all DSPy modules)
│   ├── signatures.py # TaskAnalysis, TaskRouting, QualityAssessment
│   ├── typed_models.py # Pydantic output models
│   └── assertions.py # DSPy assertions for validation
├── agents/           # Agent definitions & AgentFactory (coordinator.py)
├── tools/            # Tavily, browser, MCP bridges, code interpreter
├── app/              # FastAPI backend, WebSocket streaming
├── config/           # workflow_config.yaml (source of truth)
├── utils/            # Organized into subpackages:
│   ├── cfg/          # Configuration loading
│   ├── infra/        # Tracing, resilience, telemetry
│   └── storage/      # Cosmos DB, history, persistence
└── cli/              # Typer CLI commands

src/frontend/         # React 19 + Vite + Tailwind UI

Key Design Principles

1. Config-Driven – All models, agents, and thresholds in workflow_config.yaml
2. Offline Compilation – DSPy modules compiled offline, never at runtime in production
3. Type Safety – Pydantic models for all DSPy outputs (typed signatures)
4. Assertion-Driven – DSPy assertions validate routing decisions
5. Self-Improving – Learns from execution history via BridgeMiddleware

🧪 Development

make install           # Install dependencies
make dev               # Run backend + frontend
make test              # Run tests
make check             # Lint + type-check (run before committing)
make clear-cache       # Clear DSPy cache after module changes

📚 Documentation

For Users

For Developers

🆕 What's New in v0.6.95

Highlights

• Secure-by-Default Tracing – capture_sensitive defaults to false everywhere
• Package Reorganization – utils/ split into cfg/, infra/, storage/ subpackages
• Cosmos DB Fixes – Single-partition queries, user-scoped history loads
• Cache Telemetry Redaction – Task previews redacted by default

Core Features (v0.6.9+)

• Typed DSPy Signatures – Pydantic models for validated, type-safe outputs
• DSPy Assertions – Hard constraints and soft suggestions for routing validation
• Routing Cache – TTL-based caching (5 min) for routing decisions
• Smart Fast-Path – Simple queries bypass pipeline (<1s response)

See CHANGELOG.md for full release history.

🤝 Contributing

We welcome contributions! Here's how to get started:

# Fork and clone
git clone https://github.com/YOUR_USERNAME/agentic-fleet.git
cd agentic-fleet

# Install dev dependencies
uv sync

# Create a branch
git checkout -b feature/your-feature-name

# Make changes, then run checks
make check              # Lint + type-check
make test               # Run tests

# Submit a PR

Guidelines:

• Follow the existing code style (Ruff formatting, type hints)
• Add tests for new features
• Update documentation as needed
• Use conventional commits (optional but appreciated)

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License – you're free to use, modify, and distribute this software for any purpose.

See the LICENSE file for the full text.

🙏 Acknowledgments

AgenticFleet stands on the shoulders of giants. Special thanks to:

And to all our contributors who help make AgenticFleet better! 💜

---

🐛 Report Bug • ✨ Request Feature • 💬 Discussions

_{Made with ❤️ by Qredence}