# 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.)

```bash
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.

```text
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

| Requirement | Version |
|---|---|
| Python | 3.9, 3.10, or 3.11 |
| Node.js | Required for Mermaid diagram rendering (optional) |
| OS | Linux, macOS, Windows |

### Install Methods

=== "pip (recommended)"
    ```bash
    pip install metagpt
    ```

=== "From source"
    ```bash
    git clone https://github.com/geekan/MetaGPT.git
    cd MetaGPT
    pip install -e .
    ```

=== "Docker"
    ```bash
    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

```bash
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

```bash
metagpt --init-config
```

```text
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:

| Engine | Install | Config |
|---|---|---|
| Node.js mermaid-cli | `npm install -g @mermaid-js/mermaid-cli` | `mermaid.engine: nodejs` |
| Playwright | `pip install playwright && playwright install --with-deps chromium` | `mermaid.engine: playwright` |
| pyppeteer | `pip install pyppeteer` | `mermaid.engine: pyppeteer` |
| mermaid.ink (remote) | None | `mermaid.engine: ink` |

> [!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

```yaml
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:

```yaml
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

| Key | Type | Default | Description |
|---|---|---|---|
| `llm.api_type` | string | `"openai"` | LLM provider type |
| `llm.model` | string | `"gpt-4-turbo"` | Model name |
| `llm.base_url` | string | — | API endpoint URL |
| `llm.api_key` | string | — | API key |
| `llm.proxy` | string | — | HTTP proxy for LLM requests |
| `llm.timeout` | int | `300` | Request timeout in seconds |
| `proxy` | string | — | Global proxy for tools (requests, Playwright, etc.) |
| `repair_llm_output` | bool | `true` | Attempt to repair invalid JSON output |
| `language` | string | `"English"` | Output language |

> [!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

| Provider | `api_type` Value |
|---|---|
| OpenAI | `openai` |
| Azure OpenAI | `azure` |
| Anthropic Claude | `anthropic` |
| Google Gemini | `gemini` |
| Ollama (local) | `ollama` |
| AWS Bedrock | `bedrock` |
| DashScope (Alibaba) | `dashscope` |
| ZhipuAI | `zhipuai` |
| Qianfan (Baidu) | `qianfan` |
| Spark (iFlytek) | `spark` |
| Ark (Volcengine) | `ark` |
| OpenRouter | `openrouter` |
| Fireworks | `fireworks` |

## 4. Core Usage

### Software Project Generation (CLI)

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

```bash
metagpt "Create a 2048 game"
```

```text
# 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

| Flag | Type | Default | Description |
|---|---|---|---|
| `IDEA` | string (positional) | — | Your project description |
| `--investment` | float | `3.0` | Budget cap in dollars |
| `--n_round` | int | `5` | Number of collaboration rounds |
| `--code_review` | flag | off | Enable code review by QA |
| `--no-implement` | flag | off | Generate design only, skip coding |
| `--recover` | flag | off | Resume from a saved project |

```bash
# 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)

```python
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:

```python
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.

```python
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:

```python
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:

```python
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

```python
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

```bash
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

```python
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

```python
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

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

**Prerequisites:** A previously generated project directory must exist.

### Invoice OCR Processing

```python
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:

```bash
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

```python
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

```text
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.

---

_Generated May 2026 from FoundationAgents/MetaGPT at 11cdf46. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._