Flock Ops

A multi-agent orchestration platform focused on dynamic, autonomous organization of agent fleets.

Flock Ops is a fork of ChatDev 2.0 (DevAll) by OpenBMB. Where ChatDev models agent collaboration around human-driven organizational patterns -- roles like CEO, CTO, and Programmer participating in structured seminars -- Flock Ops takes a different approach: agents are dynamically composed, sequenced, and coordinated as an autonomous fleet, without relying on fixed human hierarchies.

Quick Start

Prerequisites

• OS: macOS / Linux / WSL / Windows
• Python: 3.12+
• Node.js: 18+

Installation

1. Backend Dependencies:

   pip install -r requirements.txt

2. Frontend Dependencies (Vite + Vue 3):

   cd frontend && npm install

Configuration

• Config file:

  cp config.example.yaml config.yaml

• Provider credentials: Set provider.api_key and provider.base_url in config.yaml for your LLM provider.
• YAML placeholders: Use ${VAR} (e.g., ${API_KEY}) in workflow files to reference provider credentials.

Run the Application

Start both backend and frontend:

python dev.py dev

Then access the Web Console at http://localhost:5173.

Manual Commands

1. Start Backend:

   python server_main.py --reload

   Remove --reload if output files (e.g., GameDev) trigger restarts, which interrupts tasks and loses progress.

2. Start Frontend:

   cd frontend && npm run dev

   Then access the Web Console at http://localhost:5173.

   Tip: If the frontend fails to connect to the backend, the default port 6400 may already be occupied. Switch both services to an available port:

   • Backend: start with --port 6401
   • Frontend: set VITE_API_BASE_URL=http://localhost:6401

Utility Commands

• Help command:

  make help

• Sync YAML workflows to frontend:

  make sync

  Uploads all workflow files from yaml_instance/ to the database.

• Validate all YAML workflows:

  make validate-yamls

  Checks all YAML files for syntax and schema errors.

Run with Docker

Alternatively, run the entire application using Docker Compose.

1. Prerequisites:

   • Docker and Docker Compose installed.
   • Ensure you have a .env file in the project root for your API keys.

2. Build and Run:

   docker compose up --build

3. Access:

   • Backend: http://localhost:6400
   • Frontend: http://localhost:5173

The services will automatically restart if they crash, and local file changes will be reflected inside the containers for live development.

---

How to Use

Web Console

The Flock Ops interface provides a seamless experience for both construction and execution.

• Workflow: A visual canvas to design your multi-agent systems. Configure node parameters, define context flows, and orchestrate agent interactions with drag-and-drop ease.

• Launch: Initiate workflows, monitor real-time logs, inspect intermediate artifacts, and provide human-in-the-loop feedback.

Python SDK

For automation and batch processing, use the Python SDK to execute workflows programmatically and retrieve results directly.

from runtime.sdk import run_workflow

result = run_workflow(
    yaml_file="yaml_instance/demo.yaml",
    task_prompt="Summarize the attached document in one sentence.",
    attachments=["/path/to/document.pdf"],
    variables={"API_KEY": "sk-xxxx"}
)

if result.final_message:
    print(f"Output: {result.final_message.text_content()}")

---

For Developers

The project is organized into a modular structure:

• Core Systems: server/ hosts the FastAPI backend, while runtime/ manages agent abstraction and tool execution.
• Orchestration: workflow/ handles the multi-agent logic, driven by configurations in entity/.
• Frontend: frontend/ contains the Vue 3 Web Console.
• Extensibility: functions/ is the place for custom Python tools.

Relevant reference documentation:

• Getting Started: Start Guide
• Core Modules: Workflow Authoring, Memory, and Tooling

---

Workflow Templates

Out-of-the-box templates for common scenarios are located in yaml_instance/.

• Demos: Files named demo_*.yaml showcase specific features or modules.
• Implementations: Files named directly (e.g., ChatDev_v1.yaml) are full workflow implementations.

Category	Workflow	Description
Data Visualization	data_visualization_basic.yaml, data_visualization_enhanced.yaml	Generate charts from datasets
3D Generation	blender_3d_builder_simple.yaml, blender_3d_builder_hub.yaml, blender_scientific_illustration.yaml	3D model generation (requires Blender and blender-mcp)
Game Dev	GameDev_v1.yaml, ChatDev_v1.yaml	Game design and development
Deep Research	deep_research_v1.yaml	Automated research workflows

---

Upstream

Flock Ops is forked from ChatDev by OpenBMB / THUNLP. The original research papers:

@article{chatdev,
    title = {ChatDev: Communicative Agents for Software Development},
    author = {Chen Qian and Wei Liu and Hongzhang Liu and Nuo Chen and Yufan Dang and Jiahao Li and Cheng Yang and Weize Chen and Yusheng Su and Xin Cong and Juyuan Xu and Dahai Li and Zhiyuan Liu and Maosong Sun},
    journal = {arXiv preprint arXiv:2307.07924},
    url = {https://arxiv.org/abs/2307.07924},
    year = {2023}
}

@article{puppeteer,
    title={Multi-Agent Collaboration via Evolving Orchestration},
    author={Yufan Dang and Chen Qian and Xueheng Luo and Jingru Fan and Zihao Xie and Ruijie Shi and Weize Chen and Cheng Yang and Xiaoyin Che and Ye Tian and Xuantang Xiong and Lei Han and Zhiyuan Liu and Maosong Sun},
    journal={arXiv preprint arXiv:2505.19591},
    url={https://arxiv.org/abs/2505.19591},
    year={2025}
}