ageclerate-cli 1.0.0
CLI tool to scaffold multi-agent projects using Microsoft's Agent Framework
License: MIT
Requires Python: >=3.11
Keywords: agent, framework, cli, scaffold, multi-agent, ai, llm

# Microsoft's Agent Framework Accelerator

A dynamic, plugin-based multi-agent system built on Microsoft's Agent Framework with automatic tool and agent discovery. Create powerful AI agents with just YAML configuration files - minimal code!

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start - 60 Seconds to Your First Agent

### ⭐ Recommended: Install CLI via pip (Easiest!)

Create a new multi-agent project with one command:

```bash
# 1. Install the CLI tool
pip install ageclerate

# 2. Create your project
create-agent-project my-awesome-project

# 3. Setup and launch (60 seconds!)
cd my-awesome-project
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install agent-framework
cp .env.example .env       # Add your OPENROUTER_API_KEY or Azure credentials
python run_devui.py        # 🎉 You're live at http://localhost:8080
```

**What you get:**
- ✅ 1 Sample Agent (Calculator) already configured
- ✅ 2 Sample Tools (add, multiply) ready to use
- ✅ 1 Sample Workflow showing orchestration
- ✅ Complete framework with auto-discovery
- ✅ DevUI for testing and debugging
- ✅ Step-by-step QUICKSTART.md guide

### Alternative: Clone This Repository

Explore 5 production-ready example agents:

```bash
# 1. Clone the repository
git clone https://github.com/your-org/ms-agentic-framework-accelerator
cd ms-agentic-framework-accelerator

# 2. Setup dependencies
pip install -r requirements.txt

# 3. Configure your LLM provider
cp .env.example .env  # Add your API key

# 4. Launch DevUI
python run_devui.py
# Opens at http://localhost:8080 with Email, Calendar, Stock, Weather, HR agents
```

Or use the CLI from the repository:

```bash
./quickstart/create-agent-project my-project-name
```

📖 **Documentation**: See [quickstart/](quickstart/) for complete guides and [docs/](docs/) for architecture details

## 🎯 Why This Framework?

### Before vs After: The Transformation

<table>
<tr>
<td width="50%" valign="top">

#### ❌ Traditional Microsoft Agent Framework

```python
# 1️⃣ Manually create tools
from azure.ai.projects.agentic import FunctionTool

def weather_tool():
    """Hard-coded tool definition"""
    pass

weather = FunctionTool(weather_tool, ...)

# 2️⃣ Manually register in __init__.py
from .weather import weather_tool
from .stock import stock_tool
# ... repeat for every tool

# 3️⃣ Hard-code agent configuration
agent = ChatAgent(
    name="Weather Agent",
    instructions="Long prompt...",
    tools=[weather, forecast, ...]  # Manual list
)

# 4️⃣ Edit Python for every change
# Want to add a tool? Edit 3+ files
# Want to change prompt? Edit Python
# Want new agent? Write more Python
```

**Pain Points:**
- 🔴 20-30 lines per tool setup
- 🔴 Edit 3+ files per tool
- 🔴 Manual import management
- 🔴 Hard-coded configurations
- 🔴 Code changes for prompts
- 🔴 Complex maintenance

</td>
<td width="50%" valign="top">

#### ✅ This Accelerator Framework

```yaml
# 1️⃣ Drop a tool file - auto-discovered!
# tools/weather/humidity.py
@tool(domain="weather", description="...")
def get_humidity(location: str) -> str:
    return f"Humidity: 65%"

# Done! ✨ Automatically registered

# 2️⃣ Drop a YAML file - instant agent!
# agents/weather_agent.yaml
name: "Weather Assistant"
tool_domains: ["weather"]
instructions: |
  You are a weather assistant...

# Done! ✨ Automatically created

# 3️⃣ Launch DevUI
python run_devui.py
# All agents & tools auto-discovered! 🚀
```

**Benefits:**
- ✅ 5 lines per tool
- ✅ Drop file & done
- ✅ Zero imports needed
- ✅ YAML configuration
- ✅ Edit prompts in YAML
- ✅ Effortless scaling

</td>
</tr>
</table>

### 📊 Impact Comparison

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **Lines of Code per Tool** | 20-30 | 5-8 | 75% reduction |
| **Files to Edit per Agent** | 3-5 | 1 | 80% reduction |
| **Time to Add Tool** | 15-20 min | 2-3 min | 85% faster |
| **Time to Add Agent** | 30-45 min | 5 min | 90% faster |
| **Manual Imports** | Every tool | Zero | 100% automated |
| **Configuration Changes** | Edit Python | Edit YAML | Non-technical friendly |

### 🎬 Workflow Comparison

```
Traditional Approach:
─────────────────────────────────────────────────────────────────
Create tool.py → Edit __init__.py → Import in agent.py →
Create agent class → Register agent → Test → Debug imports →
Restart → Test again
⏱️  Time: ~45 minutes per agent

This Framework:
─────────────────────────────────────────────────────────────────
Drop tool.py → Drop agent.yaml → Run DevUI
⏱️  Time: ~5 minutes per agent

🚀 10x faster development
```

## 🌟 Features

### Dynamic Tool Discovery
- **Zero-Code Tool Integration**: Drop a Python file in `tools/domain/` and it's automatically available
- **Decorator-Based Registration**: Simple `@tool` decorator handles all registration
- **Domain Organization**: Tools organized by business domain (weather, stock, email, calendar)
- **Tag-Based Filtering**: Fine-grained control over which tools each agent gets
- **Hot-Reload Support**: Modify tools without restarting the system

### Automatic Agent Discovery
- **YAML-Based Configuration**: Define agents declaratively without writing Python
- **Zero-Code Agent Creation**: Drop a YAML file in `agents/` and it's immediately available
- **Automatic Tool Attachment**: Agents automatically discover and attach tools based on domains/tags
- **No Manual Registration**: No need to edit `__init__.py` or import statements

### Microsoft Agent Framework Integration
- **Sequential Workflows**: Chain agents in sequence for complex workflows
- **Parallel Execution**: Run multiple agents concurrently with fan-out/fan-in patterns
- **Custom Aggregators**: Combine parallel results with custom logic
- **Multi-Provider LLM Support**: Azure OpenAI, OpenRouter, and direct OpenAI with automatic fallback

### Developer Experience
- **DevUI Integration**: Built-in web interface for testing and debugging
- **Comprehensive Logging**: Detailed logs for tool discovery and agent creation
- **Mock & Real APIs**: Easy toggle between mock data and real API integrations
- **Gmail Integration**: Full OAuth2 support for real email operations
- **OpenRouter Support**: Access to 100+ LLM models through a single API
- **Type Safety**: Full type hints and annotations throughout

## 📋 Table of Contents

- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Project Structure](#-project-structure)
- [Core Concepts](#-core-concepts)
- [Creating Tools](#-creating-tools)
- [Creating Agents](#-creating-agents)
- [Running the System](#-running-the-system)
- [Examples](#-examples)
- [Architecture](#-architecture)
- [Configuration](#-configuration)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Quick Start

### Prerequisites

- Python 3.11 or higher
- **One of the following LLM providers:**
  - Azure OpenAI (with Azure CLI)
  - OpenRouter API key ([Get one here](https://openrouter.ai/keys))
  - Direct OpenAI API key
- **Optional:**
  - Gmail account (for real email features)
  - Google Cloud project (for Gmail API)

### Installation

1. **Clone the repository**
```bash
git clone https://github.com/yourusername/agentic-ms.git
cd agentic-ms
```

2. **Create virtual environment**
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

3. **Install dependencies**
```bash
pip install -r requirements.txt
```

4. **Configure environment**
```bash
# Copy example environment file
cp .env.example .env

# Edit with your API keys and configuration
nano .env  # or use your preferred editor
```

**Choose your LLM provider** (edit `.env`):

- **Option A: OpenRouter** (Easiest for testing)
  ```env
  OPENROUTER_API_KEY=sk-or-v1-your-key-here
  OPENROUTER_MODEL=openai/gpt-4-turbo
  ```

- **Option B: Azure OpenAI**
  ```bash
  az login  # Authenticate Azure CLI
  ```
  ```env
  AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
  AZURE_OPENAI_DEPLOYMENT=gpt-4o
  ```

- **Option C: Direct OpenAI**
  ```env
  OPENAI_API_KEY=sk-your-key-here
  OPENAI_MODEL=gpt-4-turbo-preview
  ```

5. **Optional: Enable Gmail Integration**

See [Setup Guide - Gmail Section](docs/SETUP_GUIDE.md#gmail-api-setup) for detailed instructions.

Quick setup:
```env
USE_REAL_EMAIL_API=true
GMAIL_CREDENTIALS_FILE=credentials.json
GMAIL_USER_EMAIL=your.email@gmail.com
```

6. **Run the DevUI**
```bash
# Using bun (recommended)
bun run agent

# Or using Python directly
python run_devui.py
```

Open http://localhost:8080 in your browser and start chatting with agents!

**🚀 New to the project?** Check out the [Quick Start Guide](QUICK_START.md) (5 min setup!)

**📚 For detailed setup instructions**, see the [Complete Setup Guide](docs/SETUP_GUIDE.md)

## 📁 Project Structure

```
agentic-ms/
├── agents/                      # Agent YAML configurations
│   ├── agent_factory.py        # Factory for creating agents from YAML
│   ├── __init__.py             # Auto-discovery of all agents
│   ├── weather_agent.yaml      # Weather assistant configuration
│   ├── stock_agent.yaml        # Stock market assistant configuration
│   ├── email_agent.yaml        # Email assistant configuration
│   ├── calendar_agent.yaml     # Calendar assistant configuration
│   └── general_openrouter_agent.yaml  # OpenRouter-powered agent (NEW)
│
├── tools/                       # Tool library (auto-discovered)
│   ├── _decorators.py          # @tool decorator for registration
│   ├── _registry.py            # Central tool registry (singleton)
│   ├── _loader.py              # Auto-discovery engine
│   ├── __init__.py             # Package initialization
│   │
│   ├── weather/                # Weather domain tools
│   │   ├── current_weather.py
│   │   └── forecast.py
│   │
│   ├── stock/                  # Stock market domain tools
│   │   ├── stock_price.py
│   │   ├── stock_analysis.py
│   │   └── stock_history.py
│   │
│   ├── email/                  # Email domain tools
│   │   ├── send_email.py
│   │   ├── read_inbox.py
│   │   ├── search_emails.py
│   │   └── gmail_utils.py      # Gmail API integration (NEW)
│   │
│   ├── calendar/               # Calendar domain tools
│   │   ├── create_event.py
│   │   ├── list_events.py
│   │   └── find_free_time.py
│   │
│   └── common/                 # Shared utility tools
│
├── workflows/                   # Workflow orchestrations
│   ├── financial_workflow.py  # Sequential workflow example
│   └── reusable_workflows.py  # Parallel workflow examples
│
├── docs/                        # Documentation
│   ├── DYNAMIC_TOOL_ARCHITECTURE.md
│   ├── AGENT_WORKFLOW_ARCHITECTURE.md
│   ├── PARALLEL_EXECUTION_QUICKSTART.md
│   ├── SETUP_GUIDE.md          # Complete setup guide (NEW)
│   └── EMAIL_AGENT_DEMO.md
│
├── demos/                       # Demo scripts
│   ├── demo_parallel_execution.py
│   └── workflow_runner.py
│
├── run_devui.py                # Launch DevUI with all agents
├── test_agent_factory.py       # Test YAML-based agents
├── test_auto_discovery.py      # Test automatic discovery
└── requirements.txt            # Python dependencies
```

## 💡 Core Concepts

### 1. Tools

Tools are Python functions decorated with `@tool` that provide specific capabilities to agents.

**Key Features:**
- Automatic discovery via filesystem scanning
- Domain-based organization (weather, stock, email, etc.)
- Tag-based filtering for fine-grained control
- Mock vs real API support

### 2. Agents

Agents are AI assistants configured via YAML files that automatically discover and use tools.

**Key Features:**
- Declarative YAML configuration
- Automatic tool attachment based on domains/tags
- Editable prompts without code changes
- Azure OpenAI integration

### 3. Workflows

Workflows orchestrate multiple agents to solve complex tasks.

**Types:**
- **Sequential**: Agents run one after another
- **Parallel**: Agents run concurrently (fan-out/fan-in)
- **Custom**: Build complex routing and conditional logic

## 🛠 Creating Tools

### Step 1: Create a Tool File

Create a Python file in the appropriate domain folder:

```python
# tools/weather/humidity.py
from typing import Annotated
from tools._decorators import tool

@tool(
    domain="weather",
    description="Get humidity levels for a location",
    tags=["weather", "humidity", "conditions"],
    mock=True,  # Set to False when using real APIs
)
def get_humidity(
    location: Annotated[str, "The location to check humidity for"]
) -> str:
    """Get humidity percentage for a given location.

    Args:
        location: City name or location string

    Returns:
        Formatted string with humidity information
    """
    # Mock implementation
    return f"Humidity in {location}: 65%"
```

### Step 2: That's It!

The tool is now:
- ✅ Automatically discovered at startup
- ✅ Registered in the tool registry
- ✅ Available to all agents with `tool_domains: ["weather"]`

**No code editing, imports, or registration needed!**

### Tool Decorator Parameters

```python
@tool(
    domain: str,              # Required: Tool domain (weather, stock, email, etc.)
    name: Optional[str],      # Optional: Tool name (defaults to function name)
    description: Optional[str], # Optional: Description (defaults to docstring)
    tags: Optional[list],     # Optional: Additional tags for filtering
    mock: bool = False,       # Optional: Is this a mock implementation?
    requires_api_key: Optional[str], # Optional: API key environment variable
)
```

## 🤖 Creating Agents

### Step 1: Create a YAML Configuration

Create a YAML file in the `agents/` directory:

```yaml
# agents/news_agent.yaml
name: "News Assistant"
description: "Provides latest news headlines and articles"

# Tool Discovery - automatically finds matching tools
tool_domains:
  - news

tool_tags:
  - news
  - headlines
  - articles

# Optional: Exclude specific tools
# exclude_tools:
#   - news.experimental_feature

# Agent Instructions (the "prompt")
instructions: |
  You are a news assistant. Provide latest news headlines
  and articles when asked. Always cite your sources and
  present information objectively.

  When users ask about news:
  1. Use the appropriate tool to fetch articles
  2. Summarize key points clearly
  3. Provide source attribution

# Model Configuration - Multi-Provider with Automatic Fallback
model:
  # Provider list (will try in order until one succeeds)
  providers:
    - "openrouter"  # Try OpenRouter first (easiest, no auth issues)
    - "azure"       # Fall back to Azure if available
    - "openai"      # Fall back to OpenAI if available

  # Azure configuration (used if azure provider succeeds)
  endpoint: "https://your-azure-openai.openai.azure.com/"
  deployment: "gpt-4o"
  credential_type: "azure_cli"

  # OpenRouter/OpenAI config loaded from environment:
  # OPENROUTER_API_KEY, OPENROUTER_MODEL, OPENAI_API_KEY
```

### Step 2: Create Domain Tools (if needed)

If the domain doesn't exist, create tools for it:

```python
# tools/news/get_headlines.py
from tools._decorators import tool

@tool(domain="news", description="Get latest news headlines")
def get_headlines(category: str = "general") -> str:
    """Fetch latest news headlines."""
    # Implementation here
    return "Latest headlines..."
```

### Step 3: Restart and Use!

```bash
python run_devui.py
```

The news agent is now automatically:
- ✅ Discovered from the YAML file
- ✅ Created with matching tools attached
- ✅ Available in the DevUI

**No Python code editing required!**

## 🏃 Running the System

### DevUI (Web Interface)

Launch the development web interface:

```bash
python run_devui.py
```

Features:
- Chat with individual agents
- Test workflows
- View agent capabilities
- Debug tool calls

### Python API

Use agents programmatically:

```python
from agents import get_all_agents
import asyncio

async def main():
    # Get all auto-discovered agents
    agents = get_all_agents()

    # Use weather agent
    weather_agent = agents['weather_agent']
    response = await weather_agent.run("What's the weather in Tokyo?")
    print(response)

asyncio.run(main())
```

### Testing

Run the test suites:

```bash
# Test tool discovery
python -c "from tools import ToolRegistry; print(ToolRegistry().get_summary())"

# Test agent creation
python test_agent_factory.py

# Test automatic discovery
python test_auto_discovery.py
```

## 📚 Examples

### Example 1: Simple Agent Query

```python
from agents import get_all_agents
import asyncio

async def main():
    agents = get_all_agents()
    weather_agent = agents['weather_agent']

    response = await weather_agent.run(
        "What's the weather forecast for Seattle this week?"
    )
    print(response)

asyncio.run(main())
```

### Example 2: Sequential Workflow

```python
from agent_framework import SequentialBuilder
from agents import get_all_agents

agents = get_all_agents()
stock_agent = agents['stock_agent']
weather_agent = agents['weather_agent']

workflow = (
    SequentialBuilder()
    .add_agent(stock_agent)
    .add_agent(weather_agent)
    .build()
)

# Execute: stock analysis → weather check
result = await workflow.run("Analyze AAPL and check weather in Cupertino")
```

### Example 3: Parallel Workflow

```python
from agent_framework import ConcurrentBuilder
from agents import get_all_agents

agents = get_all_agents()

workflow = (
    ConcurrentBuilder()
    .participants([agents['stock_agent'], agents['weather_agent']])
    .build()
)

# Both agents run simultaneously
result = await workflow.run("Get AAPL price and Seattle weather")
```

### Example 4: Creating a Custom Tool

```python
# tools/news/search_articles.py
from typing import Annotated
from tools._decorators import tool

@tool(
    domain="news",
    description="Search news articles by keyword",
    tags=["news", "search", "articles"],
    mock=True
)
def search_articles(
    query: Annotated[str, "Search query"],
    days: Annotated[int, "Days to look back"] = 7
) -> str:
    """Search for news articles matching the query."""
    return f"Found 10 articles about '{query}' from last {days} days"
```

## 🏗 Architecture

### Complete Framework Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                 MS-AGENTIC FRAMEWORK ACCELERATOR                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                      AGENT LAYER (YAML)                      │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │   │
│  │  │ Weather Agent│  │Calendar Agent│  │  Stock Agent │        │   │
│  │  │   .yaml      │  │    .yaml     │  │    .yaml     │        │   │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘        │   │ 
│  └─────────┼──────────────────┼──────────────────┼──────────────┘   │
│            │                  │                  │                  │
│  ┌─────────▼──────────────────▼──────────────────▼──────────────┐   │
│  │              AGENT FACTORY (Dynamic Discovery)               │   │
│  │  • YAML Parser      • Tool Discovery Integration             │   │ 
│  │  • Chat Client      • Multi-Provider Fallback                │   │
│  │  • Context Injector • Azure/OpenRouter/OpenAI Support        │   │ 
│  └─────────┬────────────────────────────────────────────────────┘   │
│            │                                                        │
│  ┌─────────▼────────────────────────────────────────────────────┐   │
│  │            TOOL REGISTRY & DISCOVERY ENGINE                  │   │
│  │  ┌────────────────────────────────────────────────────┐      │   │
│  │  │         Automatic Tool Discovery                   │      │   │
│  │  │  • Recursive directory scanning                    │      │   │
│  │  │  • @tool decorator detection                       │      │   │
│  │  │  • Metadata extraction                             │      │   │
│  │  │  • Dynamic registration                            │      │   │
│  │  └────────────────────────────────────────────────────┘      │   │
│  │                                                              │   │
│  │  ┌────────────────────────────────────────────────────┐      │   │
│  │  │         Tool Registry (Singleton)                  │      │   │
│  │  │  • Domain filtering (weather, calendar, stock)     │      │   │
│  │  │  • Tag filtering (forecast, event, price)          │      │   │
│  │  │  • Metadata storage (docs, params, types)          │      │   │
│  │  │  • Hot-reload support                              │      │   │
│  │  └────────────────────────────────────────────────────┘      │   │
│  └──────────────────────────┬───────────────────────────────────┘   │
│                             │                                       │
│  ┌──────────────────────────▼───────────────────────────────────┐   │
│  │              TOOL DOMAINS (4 Active Domains)                 │   │
│  │                                                              │   │
│  │  ┌────────────┐  ┌────────────┐  ┌─────────┐  ┌──────────┐   │   │
│  │  │  WEATHER   │  │  CALENDAR  │  │  STOCK  │  │  EMAIL   │   │   │
│  │  │  Domain    │  │  Domain    │  │ Domain  │  │  Domain  │   │   │
│  │  ├────────────┤  ├────────────┤  ├─────────┤  ├──────────┤   │   │
│  │  │ current_   │  │ create_    │  │ stock_  │  │ send_    │   │   │
│  │  │ weather    │  │ event      │  │ price   │  │ email    │   │   │
│  │  │            │  │            │  │         │  │          │   │   │
│  │  │ forecast   │  │ list_      │  │ stock_  │  │ read_    │   │   │
│  │  │            │  │ events     │  │ analysis│  │ inbox    │   │   │
│  │  │            │  │            │  │         │  │          │   │   │
│  │  │            │  │ delete_    │  │ stock_  │  │ search_  │   │   │
│  │  │            │  │ event      │  │ history │  │ emails   │   │   │
│  │  │            │  │            │  │         │  │          │   │   │
│  │  │            │  │ find_free_ │  │         │  │ organize │   │   │
│  │  │            │  │ time       │  │         │  │ _email   │   │   │
│  │  │            │  │            │  │         │  │          │   │   │
│  │  │ (2 tools)  │  │ (4 tools)  │  │(3 tools)│  │ (4 tools)│   │   │
│  │  └────────────┘  └────────────┘  └─────────┘  └──────────┘   │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                             │                                       │
│  ┌──────────────────────────▼───────────────────────────────────┐   │
│  │                 DEVUI & ORCHESTRATION                        │   │
│  │  • Web-based UI for agent interaction                        │   │
│  │  • Real-time tool discovery display                          │   │
│  │  • Auto-startup agent loading                                │   │
│  │  • Sequential & parallel workflow execution                  │   │
│  │  • Live execution monitoring                                 │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Dynamic Tool Discovery Flow

```
┌────────────────────────────────────────────────────────────────┐
│                    START: run_devui.py                         │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────────────────────┐
        │  ToolLoader.discover_tools()        │
        │  • Scans tools/ directory           │
        │  • Recursively walks subdirectories │
        │  • Finds all .py files              │
        └─────────────────────────────────────┘
                              │
                ┌─────────────┼─────────────┐
                │             │             │
                ▼             ▼             ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │ tools/       │  │ tools/       │  │ tools/       │
    │ weather/     │  │ calendar/    │  │ stock/       │
    │              │  │              │  │              │
    │ current_     │  │ create_      │  │ stock_       │
    │ weather.py   │  │ event.py     │  │ price.py     │
    │              │  │              │  │              │
    │ forecast.py  │  │ list_        │  │ stock_       │
    │              │  │ events.py    │  │ analysis.py  │
    │              │  │              │  │              │
    │              │  │ delete_      │  │ stock_       │
    │              │  │ event.py     │  │ history.py   │
    └──────────────┘  └──────────────┘  └──────────────┘
                │             │             │
                └─────────────┼─────────────┘
                              │
                              ▼
        ┌─────────────────────────────────────┐
        │  For each file:                     │
        │  • Import module dynamically        │
        │  • Find @tool decorated functions   │
        │  • Extract metadata                 │
        │  • Register in ToolRegistry         │
        └─────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────────────────────┐
        │  ToolRegistry (Singleton)           │
        │  _tools = {                         │
        │    "weather.current_weather": {...},│
        │    "calendar.create_event": {...},  │
        │    "stock.stock_price": {...},      │
        │    ...                              │
        │  }                                  │
        │                                     │
        │  ✓ 11+ tools registered             │
        │  ✓ 4 domains active                 │
        └─────────────────────────────────────┘
```

### Agent Discovery & Creation Flow

```
┌────────────────────────────────────────────────────────────────┐
│         AgentFactory.discover_all_agents()                     │
│         • Scans agents/ directory for *.yaml files             │
└────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         │                                         │
         ▼                                         ▼
┌──────────────────────────┐         ┌──────────────────────────┐
│  weather_agent.yaml      │         │  stock_agent.yaml        │
│  ┌──────────────────────┐│         │  ┌──────────────────────┐│
│  │ 1. Load YAML config  ││         │  │ 1. Load YAML config  ││
│  │                      ││         │  │                      ││
│  │ 2. Parse domains:    ││         │  │ 2. Parse domains:    ││
│  │    [weather]         ││         │  │    [stock, weather]  ││
│  │                      ││         │  │                      ││
│  │ 3. Query registry:   ││         │  │ 3. Query registry:   ││
│  │    get_tools_by_     ││         │  │    get_tools_by_     ││
│  │    domain("weather") ││         │  │    domain("stock")   ││
│  │                      ││         │  │                      ││
│  │ 4. Results:          ││         │  │ 4. Results:          ││
│  │    [current_weather, ││         │  │    [stock_price,     ││
│  │     forecast]        ││         │  │     stock_analysis,  ││
│  │                      ││         │  │     stock_history] + ││
│  │ 5. Build client:     ││         │  │    [current_weather] ││
│  │    Try providers:    ││         │  │                      ││
│  │    - OpenRouter ✓    ││         │  │ 5. Build client:     ││
│  │                      ││         │  │    Try providers:    ││
│  │ 6. Inject context:   ││         │  │    - OpenRouter ✓    ││
│  │    Add tool docs to  ││         │  │                      ││
│  │    instructions      ││         │  │ 6. Inject context    ││
│  │                      ││         │  │                      ││
│  │ 7. Create ChatAgent  ││         │  │ 7. Create ChatAgent  ││
│  │    ✓ Ready!          ││         │  │    ✓ Ready!          ││
│  └──────────────────────┘│         │  └──────────────────────┘│
└──────────────────────────┘         └──────────────────────────┘
                              │
                              ▼
           ┌──────────────────────────────────┐
           │ All agents loaded:               │
           │ {                                │
           │   'weather_agent': <ChatAgent>,  │
           │   'calendar_agent': <ChatAgent>, │
           │   'stock_agent': <ChatAgent>,    │
           │   'email_agent': <ChatAgent>     │
           │ }                                │
           └──────────────────────────────────┘
                              │
                              ▼
           ┌──────────────────────────────────┐
           │ StartupLogger displays:          │
           │ • Tools discovered by domain     │
           │ • Agents created                 │
           │ • Agent → Tool mappings          │
           │ • Model provider info            │
           └──────────────────────────────────┘
                              │
                              ▼
           ┌──────────────────────────────────┐
           │ DevUI Server Launch              │
           │ serve(entities=agents)           │
           │ → http://localhost:8080          │
           └──────────────────────────────────┘
```

### Multi-Provider Fallback System

```
┌──────────────────────────────────────────────────────────┐
│  Agent YAML Configuration                                │
│  ┌────────────────────────────────────────────────────┐  │
│  │ model:                                             │  │
│  │   providers:           ← Try in order             │  │
│  │     - "openrouter"     ← 1st: Easy, no auth       │  │
│  │     - "azure"          ← 2nd: Enterprise          │  │
│  │     - "openai"         ← 3rd: Direct API          │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
        ┌──────────┐    ┌──────────┐    ┌──────────┐
        │OpenRouter│    │  Azure   │    │ OpenAI   │
        │  Client  │    │ OAI Client│   │  Client  │
        └─────┬────┘    └─────┬────┘    └─────┬────┘
              │               │               │
              │  Try connect  │               │
    Success? ─┼─ YES ──┐      │               │
              │        │      │               │
              │  NO ───┼──────┼─ Try Azure    │
              │        │      │               │
              │        │ Success? ───┐        │
              │        │      │      │        │
              │        │  NO ─┼──────┼── Try OpenAI
              │        │      │      │        │
              │        │      │   Success? ───┤
              │        │      │               │
              ▼        ▼      ▼               ▼
        ┌──────────────────────────────────────────┐
        │  Return working client to AgentFactory   │
        │  • Zero config changes needed            │
        │  • Automatic failover                    │
        │  • Production-ready reliability          │
        └──────────────────────────────