⚠️ Active Development Notice This project is under active development. Features, APIs, and workflows may change. We recommend pinning to specific versions for production use.

• 🖥️ Interactive CLI – Rich terminal interface for direct agent interaction
• 🌐 Web Frontend – Modern React UI wired to agent-as-workflow pattern (default)
• 📓 Jupyter Notebooks – Exploration and prototyping environments in notebooks/

• Python 3.12+
• uv package manager
• OpenAI API key (set as OPENAI_API_KEY)

# 1. Clone the repository
git clone https://github.com/Qredence/agentic-fleet.git
cd agentic-fleet

# 2. Configure environment
cp .env.example .env
# Edit .env to add your OPENAI_API_KEY

# 3. Install dependencies
make install

# 4. Launch the fleet (runs frontend + backend)
uv run agentic-fleet
# Alternatives:
#   make dev          # Same as agentic-fleet
#   uv run fleet      # CLI/REPL only

• 🎯 Magentic-Native Architecture – Built on Microsoft Agent Framework's MagenticBuilder with intelligent planning and progress evaluation
• 🤖 Specialized Agent Fleet – Pre-configured researcher, coder, and analyst agents with domain-specific tools
• 🌐 Modern Web Frontend – React-based UI with agent-as-workflow pattern for seamless agent interaction
• 📓 Interactive Notebooks – Jupyter notebooks for experimentation, prototyping, and learning
• 💾 State Persistence – Checkpoint system saves 50-80% on retry costs by avoiding redundant LLM calls
• 🛡️ Human-in-the-Loop (HITL) – Configurable approval gates for code execution, file operations, and sensitive actions
• 📊 Full Observability – Event-driven callbacks for streaming responses, plan tracking, and tool monitoring
• 🧠 Long-term Memory – Optional Mem0 integration with Azure AI Search for persistent context
• 🔧 Declarative Configuration – YAML-based agent configuration for non-engineers to tune prompts and tools
• 🎨 Multiple Interfaces – CLI, web frontend, and notebooks for different workflows

• Python 3.12+
• uv package manager
• OpenAI API key (set as OPENAI_API_KEY)

# 1. Clone the repository
git clone https://github.com/Qredence/agentic-fleet.git
cd agentic-fleet

# 2. Configure environment
cp .env.example .env
# Edit .env to add your OPENAI_API_KEY

# 3. Install dependencies
make install

# 4. Launch the fleet (runs frontend + backend)
uv run agentic-fleet
# Frontend runs on port 5173, backend on port 8000
# Alternatives:
#   make dev          # Same as agentic-fleet
#   uv run fleet      # CLI/REPL only

Web Frontend (Default): Run uv run agentic-fleet (or make dev) to launch both frontend and backend. Access the web UI at http://localhost:5173 to interact with agents through a modern React interface using the agent-as-workflow pattern.

CLI Interface: For command-line interaction only, run uv run fleet:

AgenticFleet v0.5.4
________________________________________________________________________
Task                ➤ Analyze Python code quality in my repository
Plan · Iteration 1  Facts: User needs code analysis | Plan: Use coder agent...
Progress            Status: In progress | Next speaker: coder
Agent · coder       Analyzing repository structure...
Result              Found 12 files, 3 quality issues...

Built-in CLI commands:

• History navigation: ↑ / ↓ or Ctrl+R
• Checkpoints: checkpoints, resume <id>
• Exit: quit or Ctrl+D

Jupyter Notebooks: Explore example workflows in notebooks/ including:

• magentic.ipynb – Magentic One pattern examples
• agent_as_workflow.ipynb – Agent-as-workflow demonstrations
• mem0_basic.ipynb – Memory integration tutorial
• azure_responses_client.ipynb – Azure AI responses client usage

✅ Production Ready - v0.5.4

AgenticFleet is now production-ready with enterprise-grade features:

• 🔒 Type Safe: 100% mypy compliance, zero type errors
• 🧪 Well Tested: Configuration validation + orchestration tests
• 📊 Observable: Full OpenTelemetry tracing integrated
• 🛡️ Secure: Human-in-the-loop approval system
• ⚡ Performant: Checkpoint system reduces retry costs by 50-80%
• 🎨 Modern UI: Production-ready React frontend with real-time streaming

AgenticFleet implements the Magentic One workflow pattern with a manager-executor architecture:

1. PLAN – Manager analyzes task, gathers facts, creates structured action plan
2. EVALUATE – Progress ledger checks: request satisfied? in a loop? who acts next?
3. ACT – Selected specialist executes with domain-specific tools, returns findings
4. OBSERVE – Manager reviews response, updates context, decides next action
5. REPEAT – Continues until completion or limits reached (configurable in workflow.yaml)

All agents use OpenAI Response API format via OpenAIResponsesClient and return structured Pydantic models for reliable downstream parsing.

See Architecture Documentation for detailed design patterns.

AgenticFleet uses a declarative YAML-first approach:

fleet:
  manager:
    model: "gpt-5"
    instructions: |
      You coordinate researcher, coder, and analyst agents.
      Delegate based on task requirements...

  orchestrator:
    max_round_count: 30 # Maximum workflow iterations
    max_stall_count: 3 # Triggers replan
    max_reset_count: 2 # Complete restart limit

  callbacks:
    streaming_enabled: true
    log_progress_ledger: true

name: researcher
model: gpt-5
temperature: 0.3
max_tokens: 4000

system_prompt: |
  You are a research specialist. Use web_search_tool to find information...

tools:
  - name: web_search_tool
    enabled: true

# Required
OPENAI_API_KEY=sk-...

# Optional: Memory (Mem0)
MEM0_HISTORY_DB_PATH=./var/mem0
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Optional: Observability
ENABLE_OTEL=true
OTLP_ENDPOINT=http://localhost:4317

# Install with dev dependencies
make install

# Run configuration validation
make test-config

# Run all quality checks (lint, format, type-check)
make check

# Run test suite
make test

All commands use uv run prefix (managed by Makefile):

• Configuration Tests: tests/test_config.py validates env vars, YAML structure, tool imports
• Fleet Tests: tests/test_magentic_fleet.py covers 14 orchestration scenarios
• Memory Tests: tests/test_mem0_context_provider.py validates Mem0 integration
• Mock LLM Calls: Always patch OpenAIResponsesClient to avoid API costs in tests

• Python 3.12+ with strict typing (Type | None instead of Optional[Type])
• 100-character line limit (Black formatter)
• Ruff linting with pyupgrade and isort rules
• MyPy strict checks (except for test files)
• Pydantic models for all tool return types

See Contributing Guide for detailed conventions.

Comprehensive documentation organized by audience:

• Getting Started – Installation, configuration, first steps
• User Guides – Task-oriented tutorials
• Agent Catalog – Detailed agent capabilities & tools
• Troubleshooting – FAQ & common issues

• Architecture – System design & patterns
• Features – Implementation deep-dives
• Contributing – Development workflow & standards
• API Reference – REST API & Python SDK

📚 Documentation Index – Complete navigation guide

• Memory Bank Integration: Added comprehensive memory-bank instructions for AI context persistence
• Documentation Expansion: Enhanced AGENTS documentation with detailed capability descriptions
• UI/UX Polish: Significant frontend improvements for better user experience
• Backend Cleanup: Code quality improvements and architectural refinements
• Security Enhancements: Fixed workflow permissions and expression injection vulnerabilities
• CI/CD Improvements: Updated workflows for release triggering and code scanning
• Version Management: Consistent v0.5.4 versioning across all documentation

Extend the fleet with domain-specific agents:

mkdir -p src/agenticfleet/agents/planner/{tools,}
touch src/agenticfleet/agents/planner/{__init__.py,agent.py,config.yaml}

# src/agenticfleet/agents/planner/agent.py
from agenticfleet.config.settings import settings
from agent_framework import ChatAgent
from agent_framework.azure_ai import OpenAIResponsesClient

def create_planner_agent() -> ChatAgent:
    config = settings.load_agent_config("planner")

    return ChatAgent(
        name=config["name"],
        model=config["model"],
        system_prompt=config["system_prompt"],
        client=OpenAIResponsesClient(model_id=config["model"]),
        tools=[],  # Add tools here
    )

We welcome contributions! Please follow these steps:

1. Read Contributing Guidelines
2. Review Code of Conduct
3. Check existing Issues

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

# 2. Create feature branch
git checkout -b feat/your-feature

# 3. Make changes
# Edit code, update docs, add tests

# 4. Run quality checks
make check          # Lint, format, type-check
make test-config    # Validate configurations
make test           # Full test suite

# 5. Commit with conventional format
git commit -m "feat(agents): add planner agent with breakdown tool"

# 6. Push & open PR
git push origin feat/your-feature

• ✅ Tests pass (make test)
• ✅ Code formatted (make check)
• ✅ Documentation updated
• ✅ YAML configs validated (make test-config)
• ✅ Commit messages follow feat:, fix:, docs: convention

Do NOT open public issues for security vulnerabilities.

Please follow the process outlined in SECURITY.md.

• Store API keys in .env (never commit)
• Use HITL approval for code execution
• Enable audit logging for sensitive operations
• Review tool permissions in agent configs
• Keep dependencies updated (uv sync)

AgenticFleet is released under the MIT License.

Copyright (c) 2025 Qredence

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

See LICENSE for full terms.

Built with:

• Microsoft Agent Framework – Core orchestration
• Mem0 – Long-term memory layer
• uv – Fast Python package manager
• Rich – Beautiful terminal UI
• Pydantic – Data validation

Special thanks to the Microsoft Agent Framework team for the Magentic One pattern.

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: qredence.ai

⬆ Back to Top

Made with ❤️ by Qredence