MetaGPT User Guide

1. Quick Start

MetaGPT is a multi-agent framework that simulates a software company — you give it a one-line idea, and a team of AI agents (Product Manager, Architect, Project Manager, Engineer) collaborates to produce user stories, system designs, API specifications, and working code. The core philosophy is Code = SOP(Team): standardized operating procedures applied to LLM-powered roles.

Key features:

• Generate full software projects from a single natural-language requirement
• Built-in roles: Product Manager, Architect, Project Manager, Engineer, QA Engineer
• Data Interpreter agent for data science, visualization, and machine learning tasks
• RAG (Retrieval-Augmented Generation) pipeline with multiple vector store backends
• Experience Pool for learning from past runs and improving output quality
• Extensible role/action system — build custom agents in minutes
• Multi-LLM support: OpenAI, Azure, Anthropic, Google Gemini, Ollama, Bedrock, DashScope, and more
• Mermaid diagram generation for architecture visualization

Prerequisites: Python 3.9–3.11, an LLM API key (OpenAI, Azure, etc.)

pip install metagpt
metagpt --init-config
metagpt "Create a 2048 game"

Tip

The --init-config command creates ~/.metagpt/config2.yaml. Edit it with your API key before running your first project.

workspace/
├── docs/
│   ├── prd/
│   ├── system_design/
│   └── task/
├── resources/
└── *.py  (generated source files)

What to try next: See Core Usage for software generation details, or jump to Data Interpreter for data science tasks.

2. Installation

System Requirements

Install Methods

pip (recommended)

pip install metagpt

From source

git clone https://github.com/geekan/MetaGPT.git
cd MetaGPT
pip install -e .

Docker

docker pull metagpt/metagpt:latest
mkdir -p /opt/metagpt/{config,workspace}
docker run --rm metagpt/metagpt:latest cat /app/metagpt/config/config2.yaml > /opt/metagpt/config/config2.yaml
# Edit /opt/metagpt/config/config2.yaml with your API key
docker run --rm \
    --privileged \
    -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
    -v /opt/metagpt/workspace:/app/metagpt/workspace \
    metagpt/metagpt:latest \
    metagpt "Write a cli snake game"

Important

On Windows with Docker, replace /opt/metagpt with a directory Docker has write access to, such as D:\Users\x\metagpt.

Optional Extras

pip install metagpt[rag]           # RAG support (llama-index based)
pip install metagpt[selenium]      # Selenium browser engine
pip install metagpt[search-google] # Google search integration
pip install metagpt[search-ddg]    # DuckDuckGo search

Post-Install Verification

metagpt --init-config

Configuration file created at ~/.metagpt/config2.yaml

Mermaid Diagram Rendering (Optional)

MetaGPT generates Mermaid diagrams for architecture visualization. You can use one of several rendering engines:

Warning

The mermaid.ink engine does not support PDF export. Use Playwright or pyppeteer for PDF output.

3. Configuration

MetaGPT uses a YAML configuration file. Initialize it with metagpt --init-config, then edit ~/.metagpt/config2.yaml.

Config file priority (highest to lowest):

1. ~/.metagpt/config2.yaml (user config)
2. config/config2.yaml (project config)
3. Environment variables

Minimal Configuration

llm:
  api_type: "openai"  # or azure / ollama / groq etc.
  model: "gpt-4-turbo"  # or gpt-3.5-turbo
  base_url: "https://api.openai.com/v1"
  api_key: "YOUR_API_KEY"

Per-Role LLM Assignment

You can assign different LLM models to different roles, allowing cost optimization:

roles:
  - role: "ProductManager"
    llm:
      api_type: "openai"
      model: "gpt-4-turbo-1106"
      base_url: "YOUR_BASE_URL"
      api_key: "YOUR_API_KEY"
  - role: "Engineer"
    llm:
      api_type: "azure"
      model: "gpt-35-turbo-1106"
      base_url: "YOUR_BASE_URL"
      api_key: "YOUR_API_KEY"
      api_version: "YOUR_API_VERSION"

Common Configuration Options

Note

For the full configuration reference including search, browser, S3, Redis, embedding, experience pool, and role_zero settings, see the Admin Guide.

Supported LLM Providers

4. Core Usage

Software Project Generation (CLI)

The primary use case: generate a complete software project from a text description.

metagpt "Create a 2048 game"

# Output appears in ./workspace/ with:
# - docs/prd/         Product requirements
# - docs/system_design/  System design
# - docs/task/        Task breakdown
# - resources/        Diagrams (competitive analysis, data/API, sequence)
# - *.py              Generated source code

CLI Flags

# Generate design only (no code)
metagpt "Write a cli snake game" --no-implement

# Generate with code review
metagpt "Write a cli snake game" --code_review

# Specify platform/tool
metagpt "Write a cli snake game based on pygame"

Tip

Use --no-implement first to review the design, then run again with the full pipeline.

Software Project Generation (Python API)

from metagpt.software_company import generate_repo, ProjectRepo

repo: ProjectRepo = generate_repo("Create a 2048 game")
print(repo)  # Prints the repo structure with files

Or build a custom team:

import asyncio
from metagpt.team import Team
from metagpt.roles import ProductManager, Architect, ProjectManager, Engineer

async def startup(idea: str, investment: float = 3.0, n_round: int = 5):
    company = Team()
    company.hire([ProductManager(), Architect(), ProjectManager(), Engineer()])
    company.invest(investment)
    company.start_project(idea)
    await company.run(n_round=n_round)

asyncio.run(startup("Create a 2048 game"))

Data Interpreter

The Data Interpreter is a specialized agent for data science tasks — data analysis, visualization, machine learning, and more.

import asyncio
from metagpt.roles.di.data_interpreter import DataInterpreter

async def main():
    di = DataInterpreter()
    await di.run("Run data analysis on the sklearn Iris dataset and include a plot")

asyncio.run(main())

Note

The Data Interpreter executes code in Jupyter notebook cells internally. It can install packages, read files, and produce visualizations.

Researcher Agent

Conduct automated web research with the built-in Researcher role:

import asyncio
from metagpt.roles.researcher import Researcher

async def main():
    researcher = Researcher()
    await researcher.run("Research the latest trends in AI agent frameworks")

asyncio.run(main())

Building Custom Agents

Create a custom agent by defining Actions and Roles:

from metagpt.actions import Action
from metagpt.roles import Role

class SimpleWriteCode(Action):
    name: str = "SimpleWriteCode"

    async def run(self, instruction: str):
        prompt = f"Write Python code for: {instruction}. Return only code."
        rsp = await self._aask(prompt)
        return rsp

class SimpleCoder(Role):
    name: str = "Alice"
    profile: str = "SimpleCoder"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([SimpleWriteCode])

Building Multi-Agent Teams

from metagpt.team import Team

async def main():
    team = Team()
    team.hire([SimpleCoder(), SimpleTester(), SimpleReviewer()])
    team.invest(investment=3.0)
    team.run_project("Write a calculator")
    await team.run(n_round=5)

Warning

The investment parameter sets a dollar budget. The team stops when this budget is exhausted, based on estimated LLM API costs. Set it high enough for complex projects.

5. Common Tasks

Generate a Web Application

metagpt "Create a Flask-based todo list web application with user authentication"

Goal: Full web app with routes, templates, and database models. Verify: Check ./workspace/ for generated files; run the app locally.

Run Data Analysis

import asyncio
from metagpt.roles.di.data_interpreter import DataInterpreter

async def main():
    di = DataInterpreter()
    await di.run("Load the iris dataset, perform EDA, and train a random forest classifier")

asyncio.run(main())

Verify: Check the generated notebook output for plots and accuracy metrics.

Use RAG for Document Q&A

from metagpt.rag.engines.simple import SimpleEngine

engine = SimpleEngine.from_docs(input_dir="./my_documents/")
answer = await engine.aquery("What is the main conclusion of the report?")
print(answer)

Important

RAG requires the rag extra: pip install metagpt[rag]. You must also configure an embedding model in config2.yaml.

Resume a Failed Project

metagpt "Continue the 2048 game" --recover --project_path ./workspace/2048_game

Prerequisites: A previously generated project directory must exist.

Invoice OCR Processing

import asyncio
from metagpt.roles.invoice_ocr_assistant import InvoiceOCRAssistant

async def main():
    assistant = InvoiceOCRAssistant()
    await assistant.run("Extract data from invoice.pdf")

asyncio.run(main())

Use Chainlit UI

MetaGPT provides a web UI integration via Chainlit:

cd examples/ui_with_chainlit
pip install chainlit
chainlit run app.py

This launches an interactive browser UI where you can submit project ideas and watch the multi-agent team work.

Search-Enhanced Q&A

import asyncio
from metagpt.roles.searcher import Searcher

async def main():
    searcher = Searcher()
    await searcher.run("What are the best practices for Python async programming?")

asyncio.run(main())

Note

Requires search to be configured in config2.yaml with a valid API key (Google, Serper, or DuckDuckGo).

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├── Installation error → Check Python version (3.9-3.11), pip version
├── API key error → Verify config2.yaml, check api_type matches provider
├── No output generated → Check investment budget, increase --n_round
├── Mermaid rendering fails → Install rendering engine, check config
└── Incremental mode crashes → See ValueError below

Error: Please set your API key in config2.yaml

Cause: No valid LLM configuration found in either ~/.metagpt/config2.yaml or config/config2.yaml.

Solution:

1. Run metagpt --init-config to generate the config file
2. Edit ~/.metagpt/config2.yaml with your API key and model settings
3. Verify the api_type matches your provider

Prevention: Always run --init-config after a fresh install.

Error: ValueError: Call with_srcs first. (Issue #2007)

Cause: Incremental mode (--inc) crashes when source paths are not properly initialized.

Solution:

1. Ensure the --project_path points to a valid existing project
2. Try running without --inc flag to regenerate from scratch

Prevention: Use incremental mode only with projects that were fully generated by MetaGPT.

Error: NoMoneyException

Cause: The investment budget has been exhausted before the project completed.

Solution:

1. Increase the --investment value (default is 3.0)
2. Use a cheaper model for some roles via per-role LLM config
3. Reduce --n_round if the project is over-iterating

Prevention: Set a higher investment for complex multi-file projects.

Error: KeyError: 'command_name' (Issue #1843)

Cause: Action node parsing failure when LLM output is malformed.

Solution:

1. Enable repair_llm_output: true in config2.yaml
2. Try a more capable model (e.g., GPT-4 instead of GPT-3.5)

Prevention: Use GPT-4-class models for complex projects.

Error: Request timed out

Cause: LLM API call exceeded the timeout threshold (default 300 seconds).

Solution:

1. Set llm.timeout: 600 in config2.yaml for longer operations
2. Check your network connection and proxy settings
3. Verify the LLM provider is not experiencing outages

Prevention: Set a generous timeout value, especially for large code generation tasks.

Mermaid Diagram Generation Fails

Cause: No Mermaid rendering engine installed or configured.

Solution:

1. Install one of: mermaid-cli (Node.js), Playwright, or pyppeteer
2. Set the corresponding mermaid.engine in config2.yaml
3. For pyppeteer, set PUPPETEER_EXECUTABLE_PATH to your Chrome/Chromium path

Prevention: Use mermaid.engine: ink for the simplest setup (no local install needed, but no PDF support).

Warning

If you see npm install errors for mermaid-cli, try installing locally instead of globally: npm install @mermaid-js/mermaid-cli.

Docker Container Permissions

Cause: The container cannot write to mounted volumes.

Solution:

1. Ensure the host directories exist before mounting
2. On Linux, check directory ownership matches the container user
3. Use --privileged flag (required for browser rendering inside the container)

Prevention: Create mount directories with mkdir -p /opt/metagpt/{config,workspace} before first run.

7. FAQ

Q: What LLM models work with MetaGPT?

MetaGPT supports any OpenAI-compatible API, plus native integrations for Azure OpenAI, Anthropic Claude, Google Gemini, Ollama (local models), AWS Bedrock, DashScope, ZhipuAI, Qianfan, Spark, Ark, and OpenRouter. Set the api_type in config2.yaml to match your provider.

Q: Can I use local/self-hosted models?

Yes. Use Ollama (api_type: ollama) to run models locally. Point base_url to your Ollama server (typically http://localhost:11434). Performance depends on model quality — GPT-4-class models produce significantly better results than smaller models.

Q: How much does it cost to generate a project?

Costs depend on the LLM provider and model. With GPT-4, a simple project design costs approximately $0.20, and a full project with code costs approximately $2.00. Use per-role LLM configuration to assign cheaper models to less critical roles.

Q: Can I use MetaGPT with Python 3.12+?

No. MetaGPT requires Python >= 3.9 and < 3.12 as specified in setup.py. Use a conda environment to manage the version: conda create -n metagpt python=3.11 && conda activate metagpt.

Q: How do I use the Data Interpreter for my own data?

Pass a file path or description in the prompt: await di.run("Analyze data in /path/to/data.csv and create visualizations"). The Data Interpreter reads the file, writes analysis code, executes it in a notebook environment, and returns results.

Q: What is the Experience Pool?

The Experience Pool records past successful interactions so the agent can learn from them. Enable it in config2.yaml under exp_pool. It uses either BM25 or ChromaDB for retrieval. See the Admin Guide for full configuration.

Q: Can I assign different models to different agents?

Yes. Use the roles section in config2.yaml to assign specific LLM configurations per role. This allows you to use a powerful model for Architect/PM and a cheaper model for Engineer.

Q: How do I integrate MetaGPT with a web UI?

Use the Chainlit integration in examples/ui_with_chainlit/. Install Chainlit (pip install chainlit), then run chainlit run app.py. This provides a browser-based chat interface for submitting project ideas.

Q: What does the --investment flag control?

It sets a dollar budget for the team. MetaGPT tracks estimated LLM API costs and halts execution when the budget is exhausted. The default of 3.0 is sufficient for simple projects; increase it for complex multi-file applications.