ChatDev Tutorial: Build Your Multi-Agent Automation Platform from Scratch

Created

Imagine having multiple AI agents work together like a real team — automatically handling data visualization, 3D generation, deep research, and even software development. ChatDev 2.0 (codename DevAll) makes this possible.

What is ChatDev? ChatDev is an open-source multi-agent orchestration platform developed by THUNLP Lab at Tsinghua University and the ModelBest team. With the 2.0 release (DevAll) in January 2026, it has evolved from its original “Virtual Software Company” concept into a general-purpose zero-code multi-agent orchestration platform, allowing users to define agents, orchestrate workflows, and execute complex tasks via YAML configuration or a Web console — without writing code.

ChatDev has evolved from its original “Virtual Software Company” concept (version 1.0) into a general-purpose zero-code multi-agent orchestration platform. You don’t need to write code — just use the visual interface or YAML configuration files to define agents, orchestrate workflows, and execute complex tasks.

Key Data:

  • 🌟 GitHub Stars: 3,300+ (OpenBMB/ChatDev)
  • 📅 2.0 Release: January 7, 2026
  • ⚖️ License: Apache 2.0
  • 🧠 Supported Models: OpenAI, Anthropic, Gemini, Ollama, and any OpenAI-compatible API
  • 📦 Built-in Examples: data visualization, 3D generation, game development, deep research

This tutorial will guide you from a fresh install to running your first AI workflow.

Prerequisites

Before starting, ensure your environment meets these requirements:

  • OS: macOS / Linux / WSL / Windows (all supported)
  • Python: 3.12 or higher
  • Node.js: 18 or higher
  • Package Manager: uv (faster Python package manager)
  • LLM API: An OpenAI-compatible API key (OpenAI, Anthropic, local Ollama, etc.)

💡 Tip: If you don’t have an API key, you can use Ollama to run open-source models locally — completely free.

Overview

ChatDev 2.0 consists of three core components:

  1. Backend Service: A FastAPI-based Python backend that parses YAML workflows and orchestrates agent execution
  2. Web Console: A Vue 3 frontend with a visual workflow editor and real-time monitoring
  3. Workflow Engine: Parses YAML DAGs (Directed Acyclic Graphs) to coordinate agent node execution

The overall flow is simple: write a YAML config → load it into the platform → enter a task prompt → agents execute automatically → results are delivered.

Key Features:

  • Zero-code: Define workflows via YAML or Web UI, no programming required
  • Multi-agent orchestration: Supports DAG and cyclic graph structures for complex agent collaboration
  • Dynamic parallelism: Map/Tree modes for automatic task splitting and merging
  • Human-in-the-loop: human nodes support manual review and intervention
  • Multi-model support: OpenAI, Gemini, Ollama, and any OpenAI-compatible API
  • Open source: Apache 2.0 licensed, available on GitHub

Step 1: Install ChatDev

Clone the Repository

First, clone the ChatDev repository:

1
2
git clone https://github.com/OpenBMB/ChatDev.git
cd ChatDev

Install Backend Dependencies

ChatDev 2.0 uses uv as its Python package manager, which is significantly faster than pip:

1
uv sync

This command reads pyproject.toml and installs all Python dependencies automatically.

Install Frontend Dependencies

The Web console is built with Vue 3 + Vite:

1
cd frontend && npm install

Then return to the project root directory.

Step 2: Configure API Keys

ChatDev needs an LLM API to power its agents. Configuration is straightforward:

1
cp .env.example .env

Then edit the .env file with your API details:

1
2
3
# Example configuration
API_KEY=sk-your-api-key-here
BASE_URL=https://api.openai.com/v1

💡 Tip: ChatDev uses the OpenAI-compatible interface, meaning virtually any LLM provider works — OpenAI, Anthropic, Google Gemini, local Ollama, and more — as long as they support the /v1/chat/completions endpoint.

You can also use ${VAR} placeholders in YAML workflows to reference environment variables:

1
2
3
vars:
  API_KEY: ${API_KEY}
  BASE_URL: ${BASE_URL}

Step 3: Start ChatDev

ChatDev provides a Makefile for one-command startup:

1
make dev

After startup, visit http://localhost:5173 to open the Web console.

Method 2: Manual Startup

For more granular control, start frontend and backend separately:

Start the backend:

1
uv run python server_main.py --port 6400 --reload

Start the frontend:

1
2
cd frontend
VITE_API_BASE_URL=http://localhost:6400 npm run dev

💡 Tip: If port 6400 is already in use, switch to another port (e.g., --port 6401) and update the frontend VITE_API_BASE_URL accordingly.

Method 3: Using Docker

For containerized deployment:

1
docker compose up --build

Docker handles all dependency management automatically — ideal for production environments.

Step 4: Create Your First Workflow via Web Console

Let’s create a simple workflow using the Web console.

1. Navigate to Launch View

Visit http://localhost:5173 and click Launch View in the left sidebar.

2. Select a Workflow

The left panel lists all available workflow YAML files (located in yaml_instance/). For your first run, select the built-in demo.yaml.

3. Enter a Task Prompt

Type your task description in the text box, for example:

1
Please summarize the core points of the following document into a concise English summary.

4. Upload Attachments (Optional)

If your task involves file processing (PDFs, CSVs, images, etc.), click the upload button to add files.

5. Click Launch

Click the Launch button to start execution. You can monitor in real-time on the right panel:

  • Node status changes (pending → running → success/failed)
  • Real-time agent output logs
  • Generated intermediate results and final outputs

6. Human-in-the-Loop Interaction

If the workflow contains human type nodes (e.g., a review node), execution pauses and displays an input box. You can enter review comments or revision instructions, then submit to continue.

Step 5: Write Custom YAML Workflows

For more complex needs, you can write your own YAML workflows. ChatDev 2.0 workflows use a DAG (Directed Acyclic Graph) structure. Here’s the core structure:

Basic Workflow Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
version: 0.4.0
vars:
  API_KEY: ${API_KEY}
  BASE_URL: ${BASE_URL}
graph:
  id: my_workflow
  description: My First Workflow
  initial_instruction: |
    You are a professional content creation assistant.
  start:
    - Content Creator
  end:
    - Content Creator
  nodes:
    - id: Content Creator
      type: agent
      config:
        provider: openai
        api_key: ${API_KEY}
        base_url: ${BASE_URL}
        name: gpt-4o
        params:
          temperature: 0.1
    - id: Reviewer
      type: human
      config:
        description: Review the content above. Type ACCEPT to approve, otherwise provide revision notes.
  edges:
    - from: Content Creator
      to: Reviewer
    - from: Reviewer
      to: Content Creator
      condition:
        type: keyword
        config:
          none:
            - ACCEPT
          case_sensitive: false

This example workflow has two nodes:

  • Content Creator (agent type): Calls an LLM to generate content
  • Reviewer (human type): Human review — the loop only ends when ACCEPT is typed

Core Node Types

Node Type Purpose
agent LLM-backed agent with tools, memory, and thinking modes
python Executes Python scripts in a shared code workspace
human Pauses for human input
subgraph Embeds a child DAG for complex flow reuse
passthrough Context filtering for graph optimization
literal Emits fixed text payloads
loop_counter Limits loop iteration count
loop_timer Limits loop execution duration

Step 6: Advanced — Dynamic Parallel Execution

ChatDev 2.0 supports dynamic parallel execution, automatically splitting tasks into parallel sub-tasks. The dynamic configuration is defined at the edge level, not the node level:

Map Mode (Fan-Out)

Splits messages into multiple units for parallel execution, producing a flat list of results:

1
2
3
4
5
6
7
8
9
edges:
  - from: Task Distributor
    to: Research Agent
    dynamic:
      type: map
      split:
        type: message
      config:
        max_parallel: 5  # Up to 5 parallel agents
1
2
3
4
5
6
7
nodes:
  - id: Research Agent
    type: agent
    config:
      provider: openai
      name: gpt-4o
      prompt_template: "Research this topic: {{content}}"

Tree Mode (Fan-Out + Reduce)

Ideal for chunked summarization of long texts — parallel processing with recursive merging:

1
2
3
4
5
6
7
8
9
10
11
edges:
  - from: Text Splitter
    to: Summary Agent
    dynamic:
      type: tree
      split:
        type: regex
        pattern: "(?s).{1,2000}(?:\\s|$)"  # Split every ~2000 chars
      config:
        group_size: 3   # Merge every 3 results into 1
        max_parallel: 10

Step 7: Use the Python SDK

ChatDev also provides a Python SDK (PyPI package chatdev) for programmatic workflow execution:

1
pip install chatdev

💡 Note: runtime.sdk is an internal ChatDev project path. When using it in a standalone project, consider adding the ChatDev repository as a submodule or setting the PYTHONPATH environment variable.

1
2
3
4
5
6
7
8
9
10
11
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": "your-api-key"}
)

if result.final_message:
    print(result.final_message.text_content())

FAQ

Q: What’s the difference between ChatDev 2.0 and 1.0?
A: ChatDev 1.0 was a “Virtual Software Company” focused on software development automation (with roles like CEO, CTO, programmer). 2.0 (DevAll) has evolved into a general-purpose zero-code multi-agent orchestration platform supporting diverse scenarios like data visualization, 3D generation, and deep research. The 1.0 code is maintained on the chatdev1.0 branch.

Q: What LLM models does ChatDev support?
A: ChatDev uses the OpenAI-compatible interface, supporting all models that provide a /v1/chat/completions endpoint. This includes: OpenAI (GPT-4o, o1, etc.), Anthropic (Claude), Google Gemini, local Ollama models, and more.

Q: The Web page won’t load after startup?
A: Make sure the frontend npm run dev is running. Check the browser console for errors.

Q: Frontend can’t connect to the backend?
A: Confirm the backend uv run python server_main.py is running. Check if the port is occupied and that both frontend and backend use the same port.

Q: The workflow list is empty?
A: Check if there are YAML files in the yaml_instance/ directory. You can use make sync to sync workflows to the frontend.

Q: WebSocket disconnected during execution?
A: Refresh the page to re-establish the connection.

Q: Can I use a local model (e.g., Ollama)?
A: Set BASE_URL=http://localhost:11434/v1 in .env. The API_KEY can be left empty or set to any value.

Q: How do I extend custom node types?
A: See the workflow authoring docs for node extension guides, and check the functions/ directory for custom tool development examples.

Conclusion

Through this tutorial, you’ve learned the core capabilities of ChatDev 2.0:

  1. ✅ Installed ChatDev 2.0 from scratch
  2. ✅ Configured LLM API keys
  3. ✅ Created and executed workflows via the Web console
  4. ✅ Wrote custom YAML workflows
  5. ✅ Used dynamic parallel execution for large-scale tasks
  6. ✅ Integrated workflows via the Python SDK

ChatDev 2.0’s strength lies in its zero-code approach — you don’t need to be a programming expert to orchestrate complex multi-agent collaboration. Whether it’s automated content creation, data analysis, or 3D generation, ChatDev makes it accessible.

Next, explore the built-in example workflows (data visualization, 3D generation, game development, etc.) or create entirely new workflows tailored to your needs.

📖 More documentation: ChatDev Official Docs

How to cite this article: Based on the official ChatDev README (verified 2026-05-22), workflow_authoring.md, dynamic_execution.md, and PyPI chatdev package. All commands verified against ChatDev 2.0 (DevAll).

References

  1. ChatDev GitHub Repository — Official repo with full source code and examples
  2. ChatDev User Guide — Official user documentation
  3. Multi-Agent Collaboration via Evolving Orchestration — NeurIPS 2025 paper on dynamic orchestration algorithms
  4. ChatDev Python SDK (PyPI) — Official PyPI package
  5. ChatDev 1.0 Original Paper — Foundational research on multi-agent collaboration