agent-control README

The project's README from github.com/loulanyue/agent-control. As one markdown file: README.md.

🚀 Agent Control

Modern, High-Performance Control Plane & Task Orchestration Platform for Autonomous AI Agents

License Python Version FastAPI MCP Compatible Docker PRs Welcome

English | 中文说明

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

🏗️ 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

# 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:

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:

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:

Command Description
./start.sh Run in foreground dev mode with live reload
./start.sh start Run as background daemon process
./start.sh stop Gracefully stop the running daemon
./start.sh restart Restart the background service
./start.sh status Check service PID, port status, and healthcheck
./start.sh logs Follow live daemon logs (tail -f)

📚 REST API Overview

Endpoint Method Description
/api/v1/agents/register POST Register a new agent with capabilities
/api/v1/agents/{id}/heartbeat POST Refresh agent lease and report status
/api/v1/tasks POST Dispatch a new task to the queue
/api/v1/tasks/claim POST Agent claims an eligible pending task
/api/v1/graphs POST Create a DAG multi-agent workflow
/api/v1/graphs/{id}/trigger POST Trigger execution of a workflow
/api/v1/rules GET Retrieve and evaluate agent rules

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

📖 Agent Control 控制面平台 (中文说明)

Agent Control 是一个专为智能体集群与自动化流水线设计的生产级控制面系统。

核心特性

  1. 多 Agent 状态机与租约机制：支持分布式心跳汇报、任务租约锁定、超时自动转移与故障驱逐。
  2. DAG 图工作流编排：支持定义包含依赖关系的多步骤图任务，实现跨 Agent 协作。
  3. 原生 MCP 协议支持：内置 mcp_server.py，支持直接与 Claude Desktop、Cursor 等客户端通过标准工具协议对话。
  4. 统一可观测看板：开箱即用可视化面板（/dashboard），实时监控采集作业、任务生命周期及集群指标。
  5. 开箱即用：支持 SQLite 极速体验，支持 MySQL/PostgreSQL 生产环境部署，提供完善的 Docker 与运维脚本。

🌐 Ecosystem & Integrations

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

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

agent-control (loulanyue/agent-control)

Searching Database…

195 ·GitHub
Agent-control
What is this?Agent Control is a production-grade control plane and orchestration engine for autonomous AI agents, handling distributed task dispatching, heartbeat leasing, DAG workflow execution and data-crawling pipelines, with a built-in MCP server for LLM clients like Claude Desktop and Cursor.
Is this a framework I import, or a standalone service I run?It is a standalone server built on FastAPI, Uvicorn and SQLAlchemy 2.0 that you run as a service, exposing a REST API, a web dashboard and an MCP server. A separate, fully-typed Python SDK (agent-control-sdk) is provided to talk to that running service.
How do I get it running?There are three options: a one-click launch script, Docker Compose which spins up the full FastAPI + MySQL 8.0 stack with a single command, or a manual install on Python 3.10+.
Do I need a real database, or is SQLite enough to try it?SQLite works out of the box with zero config for local prototyping; MySQL or PostgreSQL are supported for enterprise production deployments. Manual install requires Python 3.10+.
Are the built-in crawlers generic, or tied to specific data sources?The included scrapers are built for particular use cases, like government talent-qualification announcements and enterprise tender data, not a general-purpose crawler, so you'd need to adapt them for other sites.
How does the MCP integration actually work?Agent Control ships a native MCP server (mcpserver.py) exposing 10 standardized tools, letting Claude Desktop, Cursor or Claude Code list agents and tasks, dispatch tasks, inspect DAG graphs, pull system metrics, and run safe read/write MySQL queries over JSON-RPC stdio.
What can I do with the Python SDK?The official agent-control-sdk is fully typed and lets you programmatically dispatch tasks, manage your agent fleet, and monitor DAG workflow execution without touching the REST API directly.
What does the dashboard show me?The out-of-the-box responsive dashboard gives real-time visibility into agent status, task states, crawl runs, and cluster metrics.
Is this used by any real projects?Yes - Dream XI AI (a multi-agent collaboration platform) uses Agent Control as its distributed control plane and scheduling engine, and it's referenced by projects like Awesome Claude Notes and Spec Kit ZH.
What are similar projects?turnstone, cayu, apowerb, Douyin_TikTok_Download_API, oh-my-subagents, Observal, jarviscore-framework, production-agentic-rag-course
Which topics is it in?task-orchestration, workflow-engine, crawler, async, fastapi, agent-framework, autonomous-agents, mysql, model-context-protocol, agent-orchestration, cursor, sqlite
Creator
loulanyue
Size
1 MB
Stars
195
Updated
CommitOct 15Releasev1.0.0Sep 29
Age
18d
Commits · 90 Days