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
Что это?Agent Control — управляющий уровень и оркестратор промышленного уровня для автономных ИИ-агентов: распределённая отправка задач, аренда через heartbeat, выполнение DAG-процессов и конвейеры сбора данных, со встроенным MCP-сервером для LLM-клиентов вроде Claude Desktop и Cursor.
Это фреймворк для импорта или отдельный сервис для запуска?Это отдельный сервер на FastAPI, Uvicorn и SQLAlchemy 2.0, который запускается как сервис и открывает REST API, веб-дашборд и MCP-сервер. Отдельный полностью типизированный Python SDK (agent-control-sdk) предоставляется для общения с этим работающим сервисом.
Как это запустить?Есть три варианта: скрипт запуска в один клик, Docker Compose, поднимающий весь стек FastAPI + MySQL 8.0 одной командой, или ручная установка на Python 3.10+.
Нужна ли настоящая СУБД или для пробы хватит SQLite?SQLite работает сразу и без настройки — для локального прототипирования; MySQL или PostgreSQL поддерживаются для корпоративных продакшен-развёртываний. Ручная установка требует Python 3.10+.
Встроенные краулеры универсальные или привязаны к конкретным источникам данных?Входящие в комплект скрейперы сделаны под конкретные сценарии — например, правительственные объявления о квалификации кадров и данные корпоративных тендеров, — это не краулер общего назначения, так что под другие сайты их придётся адаптировать.
Как на самом деле устроена интеграция MCP?Agent Control включает нативный MCP-сервер (mcpserver.py) с 10 стандартизированными инструментами: Claude Desktop, Cursor или Claude Code могут перечислять агентов и задачи, отправлять задачи, просматривать DAG-графы, снимать системные метрики и выполнять безопасные MySQL-запросы на чтение/запись через JSON-RPC stdio.
Что можно делать с Python SDK?Официальный agent-control-sdk полностью типизирован и позволяет программно отправлять задачи, управлять своим парком агентов и следить за выполнением DAG-процессов, не трогая REST API напрямую.
Что показывает дашборд?Готовый адаптивный дашборд показывает в реальном времени состояние агентов, статусы задач, прогоны краулинга и метрики кластера.
Используется ли это в реальных проектах?Да — Dream XI AI (платформа совместной работы нескольких агентов) использует Agent Control как свой распределённый управляющий уровень и планировщик, а также на него ссылаются проекты вроде Awesome Claude Notes и 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