🌟 Highlights

Agent Control is a production-grade, asynchronous AI Agent Control Plane and orchestration engine designed to manage autonomous agents, distributed task dispatching, heartbeat leasing, DAG workflow execution, and data collection pipelines at scale.

• ⚡ Asynchronous & High-Performance: Built on FastAPI, Uvicorn, and SQLAlchemy 2.0.
• 🤖 Agent Lifecycle & Heartbeat Leasing: Distributed state machine with capability matching, automatic lease expiration, and dead-agent eviction.
• 🔀 DAG Workflow Engine: Define multi-stage agent graphs with node dependencies, parallel execution, and conditional branches.
• 🔌 Native MCP (Model Context Protocol) Server: Connect directly to Claude Desktop, Antigravity, Cursor, or custom LLM apps via standardized JSON-RPC stdio tools.
• 📊 Real-time Observability Dashboard: Out-of-the-box responsive web dashboard for agent monitoring, task states, crawl runs, and metrics.
• 🕷️ Production Crawl & Ingestion Pipelines: Integrated scrapers (e.g., government talent qualification announcements, enterprise tender data) with built-in deduplication, HTML cleaning, and structured normalization.
• 💾 Multi-Database Support: Zero-config SQLite for rapid local prototyping; MySQL and PostgreSQL for enterprise production deployments.

🏗️ Architecture

graph TD
    subgraph Clients["LLM & Orchestration Clients"]
        A1["Claude Desktop / Cursor"]
        A2["Antigravity / AutoGPT"]
        A3["Web Dashboard"]
    end

    subgraph Protocol["Interface Layer"]
        B1["MCP Server (JSON-RPC)"]
        B2["FastAPI REST APIs (/docs)"]
    end

    subgraph Core["Agent Control Plane Core"]
        C1["Agent Registry & Heartbeats"]
        C2["Task Dispatcher & Leasing"]
        C3["DAG Workflow Engine"]
        C4["Rule & Deduplication Engine"]
        C5["Cron Scheduler Worker"]
    end

    subgraph Workers["Agents & Pipelines"]
        W1["Coding & Refactoring Agents"]
        W2["Talent Notice Crawlers"]
        W3["Enterprise Bidding Scrapers"]
    end

    subgraph Storage["Persistence Layer"]
        DB[("MySQL / SQLite / PostgreSQL")]
    end

    A1 -->|Stdio MCP| B1
    A2 -->|HTTP REST| B2
    A3 -->|HTTP REST| B2
    B1 --> Core
    B2 --> Core
    Core <--> Workers
    Core <--> DB

⚡ Quickstart

Option 1: One-Click Launch (Recommended)

# Clone the repository
git clone https://github.com/loulanyue/agent-control.git
cd agent-control

# Run with local environment (auto creates venv & installs dependencies)
./start.sh

Visit the services:

• Interactive Dashboard: http://localhost:8000/dashboard
• API Documentation (Swagger UI): http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Option 2: Docker Compose

Launch the complete stack (FastAPI + MySQL 8.0) with a single command:

docker-compose up -d

Option 3: Manual Installation (Python 3.10+)

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Copy environment configuration
cp .env.example .env

# Run FastAPI server
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

🐍 Python SDK (agent-control-sdk)

Agent Control includes an official, fully-typed Python SDK for programmatic task dispatching, agent fleet management, and DAG monitoring:

# Install directly from the repository
pip install -e .

SDK Quickstart

from agent_control_sdk import AgentControlClient, TaskPriority

# 1. Connect to the Control Plane
client = AgentControlClient(base_url="http://localhost:8000")

# 2. Inspect cluster metrics
metrics = client.system.metrics()
print(f"Agents: {metrics.total_agents} | Tasks: {metrics.total_tasks}")

# 3. List online agents
agents = client.agents.list(status="online")
for agent in agents["items"]:
    print(f"Agent: {agent.name} ({agent.agent_type})")

# 4. Dispatch an autonomous task
task = client.tasks.dispatch(
    title="Extract semiconductor job profiles",
    objective="Crawl top 20 chip design companies and normalize skill requirements",
    priority=TaskPriority.HIGH
)
print(f"Dispatched Task #{task.id} (Public ID: {task.public_id})")

# 5. Inspect DAG workflows
graphs = client.graphs.list()
print(f"Active DAG definitions: {graphs['total']}")

🔌 Model Context Protocol (MCP) Integration (10 Built-in Tools)

Agent Control includes a native Model Context Protocol (MCP) server (mcp_server.py) enabling LLMs (Claude Desktop, Cursor, Claude Code) to orchestrate tasks, inspect workflows, and query database state.

10 Standardized MCP Tools:

• control_list_agents: Query active AI agents, status, and capabilities.
• control_list_tasks: Query task execution queue by status, priority, and keyword.
• control_dispatch_task: Dispatch a new autonomous task into the control plane queue.
• control_get_task_status: Retrieve execution logs, attempts, and artifacts of a task.
• control_list_graphs: List DAG workflow pipelines and orchestration topologies.
• control_get_system_metrics: Get real-time cluster health and operational stats.
• mysql_read_query: Safe read queries (SELECT / SHOW / DESCRIBE) against backend data.
• mysql_list_tables: List all 40 system and business data tables.
• mysql_describe_table: Inspect column definitions and indices of any table.
• mysql_execute_statement: Execute transactional DML statements.

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-control": {
      "command": "python3",
      "args": ["/path/to/agent-control/mcp_server.py"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "13306",
        "DB_USER": "root",
        "DB_PASSWORD": "",
        "DB_NAME": "agent_control"
      }
    }
  }
}

🛠️ Management CLI Commands

start.sh provides convenient lifecycle commands:

📚 REST API Overview

Explore all endpoints with interactive testing at http://localhost:8000/docs.

🌐 Ecosystem & Integrations

Agent Control is designed to seamlessly interoperate with the broader agent and developer tooling ecosystem:

• 🏄 Dream XI AI (460+ ⭐): Multi-Agent Collaboration Platform inspired by football dream team formations. Uses Agent Control as its distributed control plane and scheduling engine.
• 📚 Awesome Claude Notes (270+ ⭐): Community-maintained repository of reusable AI coding agents, skills, and workflows with out-of-the-box MCP integration.
• 🎯 Spec Kit ZH (330+ ⭐): Spec-driven development toolkit for Claude Code, Cursor, and Codex agents.

🤝 Contributing

Contributions, bug reports, and feature requests are very welcome! Please check our Contributing Guide and Code of Conduct.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.