🚀 Agent Control

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.

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

# 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

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

docker-compose up -d

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

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 .

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']}")

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.

• 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.

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"
      }
    }
  }
}

start.sh provides convenient lifecycle commands:

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

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.

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

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