# MetaGPT Administration & Developer Guide

## Executive Summary

MetaGPT is a multi-agent framework that models software development as a collaborative process between LLM-powered roles—Product Manager, Architect, Project Manager, Engineer, and QA Engineer—coordinated through standardized operating procedures (SOPs). The core philosophy, `Code = SOP(Team)`, encodes structured workflows into agent interactions so that a single natural-language requirement produces complete project artifacts: PRDs, system designs, task breakdowns, source code, and tests.

This guide covers architecture, configuration, deployment, security, operations, and developer internals for MetaGPT version 1.0.0 (source commit `11cdf46`, 2026-01-21). It targets administrators, DevOps engineers, and developers who need to deploy, configure, extend, or maintain MetaGPT installations.

---

## Architecture Overview

### Core Object Model

MetaGPT's architecture is built on four primary abstractions that mirror a real software company:

```
Team
 └── Environment
      ├── Role (ProductManager, Architect, Engineer, QA, ...)
      │    ├── Action (WritePRD, WriteDesign, WriteCode, WriteTest, ...)
      │    │    └── ActionNode (structured LLM prompting with schema validation)
      │    ├── Memory (short-term message buffer)
      │    └── ContextMixin (config/LLM injection)
      └── MessageQueue (publish-subscribe message routing)
```

| Component | Class | Module | Purpose |
|-----------|-------|--------|---------|
| **Team** | `Team` | `metagpt/team.py` | Top-level orchestrator; hires roles, manages budget, runs execution rounds |
| **Environment** | `Environment` | `metagpt/environment/base_env.py` | Shared workspace; routes messages between roles via publish-subscribe |
| **Role** | `Role` | `metagpt/roles/role.py` | Agent with profile, goal, constraints, actions, and memory |
| **Action** | `Action` | `metagpt/actions/action.py` | Single unit of work executed by a role (e.g., write code, run tests) |
| **ActionNode** | `ActionNode` | `metagpt/actions/action_node.py` | Structured prompt template with JSON/Markdown schema validation |
| **Message** | `Message` | `metagpt/schema.py` | Inter-role communication envelope with routing metadata |
| **Context** | `Context` | `metagpt/context.py` | Runtime container for config, LLM instances, and cost tracking |
| **Config** | `Config` | `metagpt/config2.py` | YAML-backed configuration with environment variable merging |

### Message Routing

Roles communicate through the `Environment`'s `MessageQueue`. Each message carries routing metadata:

- `sent_from`: originating role
- `send_to`: target role(s) or `<all>` for broadcast
- `cause_by`: the action type that produced the message

Roles subscribe to message types via the `_watch()` method. When a role calls `publish_message()`, the environment distributes it to all roles whose watch list matches the message's `cause_by` field.

> [!NOTE]
> Messages route by action type, not by role name. A role watching `WritePRD` will receive any message caused by that action, regardless of which role produced it.

### Execution Model

The `Team.run()` method drives execution in rounds:

1. **Start project**: Injects the user requirement as a `UserRequirement` message into the environment
2. **Per round**: Each role checks its message queue, runs `_observe()` → `_think()` → `_act()` → `_publish_message()`
3. **Termination**: Rounds continue until `n_round` is exhausted or all roles are idle (no pending messages)

Roles support three react modes (`RoleReactMode`):

| Mode | Behavior |
|------|----------|
| `REACT` | Iterative think-act loop until the role decides to stop |
| `BY_ORDER` | Execute actions in the order they were registered |
| `PLAN_AND_ACT` | Create a plan first, then execute tasks sequentially |

### Cost Management

The `CostManager` tracks cumulative token usage and cost across all LLM calls. The `Team.invest()` method sets a budget ceiling; if `total_cost` exceeds the investment, a `NoMoneyException` is raised and execution halts.

> [!WARNING]
> The budget is denominated in USD and applies across all roles collectively. Set `investment` high enough for multi-role workflows—a typical software generation project with 5 roles and GPT-4 can consume $2–$10 per run depending on code complexity.

---

## System Requirements

### Python

| Requirement | Version |
|-------------|---------|
| Python | >=3.9, <3.12 |
| pip | Latest recommended |

### Core Dependencies

MetaGPT has ~90 direct dependencies. Key ones:

| Package | Version | Purpose |
|---------|---------|---------|
| `openai` | ~1.64.0 | OpenAI and OpenAI-compatible LLM providers |
| `anthropic` | 0.47.2 | Anthropic Claude provider |
| `pydantic` | >=2.5.3 | Data models, config validation |
| `typer` | 0.9.0 | CLI framework |
| `fire` | 0.4.0 | CLI for extension scripts |
| `loguru` | 0.6.0 | Logging |
| `tiktoken` | 0.7.0 | Token counting |
| `tenacity` | 8.2.3 | Retry logic |
| `gitpython` | 3.1.40 | Git repository management |
| `redis` | ~5.0.0 | Optional: long-term memory, brain memory |
| `faiss_cpu` | 1.7.4 | Vector similarity search |
| `rank-bm25` | 0.2.2 | BM25 retrieval for experience pool |
| `rich` | 13.6.0 | Terminal output formatting |
| `networkx` | ~3.2.1 | Graph-based code analysis |

### Optional Dependency Groups

Install via `pip install metagpt[group]`:

| Group | Packages | Purpose |
|-------|----------|---------|
| `rag` | llama-index ecosystem (core, embeddings, retrievers, rankers) | RAG pipeline support |
| `selenium` | selenium, webdriver_manager, beautifulsoup4 | Browser automation (alternative to Playwright) |
| `search-google` | google-api-python-client | Google search integration |
| `search-ddg` | duckduckgo-search | DuckDuckGo search integration |
| `pyppeteer` | pyppeteer>=1.0.2 | Mermaid diagram rendering |
| `android_assistant` | pyshine, opencv-python, tensorflow, torch, transformers, groundingdino-py | Android device automation |
| `test` | All of the above + pytest suite | Full test environment |
| `dev` | pylint, black, isort, pre-commit | Development tooling |

### System-Level Dependencies

| Tool | Required For | Notes |
|------|-------------|-------|
| Node.js + npm | Mermaid CLI diagrams, Minecraft environment | `npm install -g @mermaid-js/mermaid-cli` |
| Chromium/Chrome | Playwright/Pyppeteer browser automation | Path configured in `mermaid.pyppeteer_path` |
| Git | Project workspace management | Used internally via GitPython |
| Chromium (for Puppeteer) | Mermaid rendering | Config in `config/puppeteer-config.json` |

> [!IMPORTANT]
> On Windows with Python 3.9, MetaGPT applies a compatibility patch for `asyncio.WindowsProactorEventLoopPolicy` at import time (`metagpt/_compat.py`). This is automatic and requires no configuration.

---

## Configuration Reference

### Configuration Loading Priority

Configuration merges in this order (later wins):

1. **Environment variables** (`os.environ`)
2. **Project-level config**: `{METAGPT_ROOT}/config/config2.yaml`
3. **User-level config**: `~/.metagpt/config2.yaml`
4. **Programmatic overrides**: `Config.from_llm_config()` or `Config.default(reload=True, **kwargs)`

The `METAGPT_PROJECT_ROOT` environment variable overrides project root detection. If unset, MetaGPT walks up from the package directory looking for `.git`, `.project_root`, or `.gitignore`.

### Primary Configuration File (`config2.yaml`)

#### LLM Configuration

```yaml
llm:
  api_type: "openai"       # Required. See LLMType enum below
  base_url: "https://api.openai.com/v1"
  api_key: "sk-..."        # Required
  model: "gpt-4-turbo"     # Required
  proxy: ""                # HTTP proxy for LLM API calls only
  timeout: 600             # Default: 300 (seconds). 0 = use default
  pricing_plan: ""         # Azure only: map to OpenAI model name for cost calc
```

**Supported `api_type` values** (`LLMType` enum in `metagpt/configs/llm_config.py`):

| api_type | Provider | Notes |
|----------|----------|-------|
| `openai` | OpenAI | Default |
| `azure` | Azure OpenAI | Requires `api_version` |
| `anthropic` | Anthropic Claude | |
| `gemini` | Google Gemini | |
| `ollama` | Ollama (local) | |
| `metagpt` | MetaGPT-compatible API | OpenAI-compatible wrapper |
| `fireworks` | Fireworks AI | Custom cost manager |
| `open_llm` | Open LLM (local) | Token-based cost manager |
| `spark` | iFlyTek Spark | |
| `qianfan` | Baidu Qianfan | Requires `access_key` + `secret_key` |
| `dashscope` | Alibaba DashScope | |
| `zhipuai` | ZhipuAI (GLM) | |
| `bedrock` | AWS Bedrock | Uses AWS env vars for auth |
| `ark` | Volcengine Ark | |
| `openrouter` | OpenRouter | Reasoning model support |

> [!TIP]
> For AWS Bedrock, set authentication via environment variables rather than config: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, and `AWS_DEFAULT_REGION`.

#### Embedding Configuration

```yaml
embedding:
  api_type: ""             # openai / azure / gemini / ollama
  base_url: ""
  api_key: ""
  model: ""
  api_version: ""          # Azure only
  embed_batch_size: 100
  dimensions:              # Output dimension of embedding model
```

If embedding is not configured and the LLM's `api_type` is `openai` or `azure`, embedding falls back to the LLM config automatically.

#### Per-Role LLM Assignment

Assign different LLM providers or models to specific roles for cost optimization:

```yaml
roles:
  - role: "ProductManager"     # Class name or role_id
    llm:
      api_type: "openai"
      model: "gpt-4-turbo"
      base_url: "https://api.openai.com/v1"
      api_key: "sk-..."
  - role: "Engineer"
    llm:
      api_type: "azure"
      model: "gpt-35-turbo-1106"
      base_url: "https://your-resource.openai.azure.com/"
      api_key: "..."
      api_version: "2024-02-01"
```

> [!TIP]
> Use a cheaper model (e.g., GPT-3.5/GPT-4o-mini) for Engineer and QA roles that primarily generate boilerplate code, while reserving GPT-4-class models for ProductManager and Architect roles that handle design decisions.

#### Search Configuration

```yaml
search:
  api_type: "google"       # google / serpapi / serper / ddg / custom
  api_key: "YOUR_API_KEY"
  cse_id: "YOUR_CSE_ID"   # Google Custom Search Engine ID

enable_search: false       # Master toggle
```

#### Browser Configuration

```yaml
browser:
  engine: "playwright"     # playwright / selenium
  browser_type: "chromium" # playwright: chromium/firefox/webkit
                           # selenium: chrome/firefox/edge/ie
```

#### Mermaid Diagram Rendering

```yaml
mermaid:
  engine: "pyppeteer"      # pyppeteer / ink / playwright / nodejs
  pyppeteer_path: "/Applications/Google Chrome.app"
```

#### Storage: Redis

```yaml
redis:
  host: "localhost"
  port: 6379
  password: ""
  db: "0"
```

Used for `BrainMemory` persistence and long-term memory when `enable_longterm_memory: true`.

#### Storage: S3

```yaml
s3:
  access_key: "YOUR_ACCESS_KEY"
  secret_key: "YOUR_SECRET_KEY"
  endpoint: "YOUR_ENDPOINT"
  secure: false
  bucket: "test"
```

#### Experience Pool

```yaml
exp_pool:
  enabled: false
  enable_read: false
  enable_write: false
  persist_path: .chroma_exp_data
  retrieval_type: bm25     # bm25 / chroma
  use_llm_ranker: true
  collection_name: experience_pool
```

> [!NOTE]
> When `retrieval_type` is `chroma`, you must configure an embedding model. The `bm25` type works without embeddings.

#### RoleZero Configuration

```yaml
role_zero:
  enable_longterm_memory: false
  longterm_memory_persist_path: .role_memory_data
  memory_k: 200            # Short-term memory capacity
  similarity_top_k: 5      # Long-term memory retrieval count
  use_llm_ranker: false
```

#### Miscellaneous Settings

```yaml
repair_llm_output: false   # Attempt to fix invalid JSON in LLM responses
prompt_schema: "json"      # json / markdown / raw
language: "English"        # Output language for generated artifacts
enable_longterm_memory: false
code_validate_k_times: 2   # Code validation retry count

# Global proxy (for tools: requests, playwright, selenium)
proxy: ""

# Text-to-speech
azure_tts_subscription_key: ""
azure_tts_region: "eastus"
iflytek_api_id: ""
iflytek_api_key: ""
iflytek_api_secret: ""

# OmniParse (document parsing)
omniparse:
  api_key: ""
  base_url: ""
```

### Models Configuration (Multi-Model Registry)

The `models` section in `config2.yaml` registers named model configurations that extensions (AFlow, SPO) reference by name:

```yaml
models:
  "gpt-4o":
    api_type: "openai"
    base_url: "https://api.openai.com/v1"
    api_key: "sk-..."
  "claude-3-5-sonnet-20240620":
    api_type: "anthropic"
    base_url: "https://api.anthropic.com"
    api_key: "sk-ant-..."
```

### Vault Configuration (`vault.yaml`)

Stores credentials for tools to access programmatically:

```yaml
vault:
  github:
    values:
      access_token: "ghp_..."
    descriptions:
      access_token: "Get github access token"
  azure_tts:
    values:
      subscription_key: "..."
      region: "eastus"
```

Access in code: `from metagpt.tools.libs.env import get_env; token = await get_env(key="access_token", app_name="github")`

### Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `METAGPT_PROJECT_ROOT` | Override project root directory | Auto-detected |
| `METAGPT_REPORTER_URL` | URL for progress reporting webhook | `""` |
| `METAGPT_ROLE` | Current role name for reporting context | `""` |
| `AWS_ACCESS_KEY_ID` | Bedrock authentication | — |
| `AWS_SECRET_ACCESS_KEY` | Bedrock authentication | — |
| `AWS_SESSION_TOKEN` | Bedrock authentication (optional) | — |
| `AWS_DEFAULT_REGION` | Bedrock region | — |
| `LLM_LOG` | LLM logging level | `"debug"` |
| `NO_PROXY` / `no_proxy` | Proxy exclusion list | — |

### Key Path Constants

Defined in `metagpt/const.py`:

| Constant | Default Value | Purpose |
|----------|---------------|---------|
| `CONFIG_ROOT` | `~/.metagpt` | User-level config directory |
| `METAGPT_ROOT` | Auto-detected | Project root |
| `DEFAULT_WORKSPACE_ROOT` | `{METAGPT_ROOT}/workspace` | Generated project output |
| `PROMPT_PATH` | `{METAGPT_ROOT}/metagpt/prompts` | Prompt templates |
| `SKILL_DIRECTORY` | `{METAGPT_ROOT}/metagpt/skills` | Skill definitions |
| `TOOL_LIBS_PATH` | `{METAGPT_ROOT}/metagpt/tools/libs` | Built-in tool implementations |
| `MEM_TTL` | `2592000` (30 days) | Memory time-to-live in seconds |
| `LLM_API_TIMEOUT` | `300` | Default LLM timeout in seconds |
| `DEFAULT_MAX_TOKENS` | `1500` | Default max response tokens |

---

## Deployment

### pip Installation

```bash
pip install metagpt
metagpt --init-config    # Creates ~/.metagpt/config2.yaml
```

### Development Installation

```bash
git clone https://github.com/FoundationAgents/MetaGPT.git
cd MetaGPT
pip install -e ".[dev]"
```

### Docker Deployment

```bash
docker pull metagpt/metagpt:latest
mkdir -p /opt/metagpt/{config,workspace}

# Extract default config
docker run --rm metagpt/metagpt:latest \
  cat /app/metagpt/config/config2.yaml > /opt/metagpt/config/config2.yaml

# Edit config with your API keys
vim /opt/metagpt/config/config2.yaml

# Run
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"
```

> [!WARNING]
> The `--privileged` flag is required for Playwright/Chromium browser automation inside the container. If you are not using browser features, you can omit it.

### Workspace Structure

Each project run creates a workspace directory:

```
workspace/{project_name}_{timestamp}/
├── docs/
│   ├── prd/                    # Product requirements
│   ├── system_design/          # Architecture documents
│   ├── task/                   # Task breakdowns
│   ├── code_plan_and_change/   # Incremental change plans
│   ├── code_summary/           # Code summaries
│   ├── class_view/             # Class diagrams
│   └── graph_repo/             # Code graph DB
├── resources/
│   ├── competitive_analysis/
│   ├── data_api_design/
│   ├── seq_flow/               # Sequence diagrams
│   └── prd/                    # PDF versions
├── tests/                      # Generated test files
├── test_outputs/               # Test execution results
├── requirement.txt             # Original requirement
└── .git/                       # Auto-initialized Git repo
```

---

## Operations

### CLI Usage

The primary entry point is `metagpt.software_company:app`, registered as the `metagpt` console script:

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

Key CLI parameters (from `CLIParams`):

| Parameter | Type | Default | Purpose |
|-----------|------|---------|---------|
| `--project-path` | str | `""` | Path to existing project (enables incremental mode) |
| `--project-name` | str | `""` | Project name |
| `--inc` | bool | `false` | Incremental development mode |
| `--reqa-file` | str | `""` | Requirements file path |
| `--max-auto-summarize-code` | int | `0` | Max automatic code summarization rounds |
| `--git-reinit` | bool | `false` | Reinitialize Git repository |

> [!IMPORTANT]
> Setting `--project-path` automatically enables incremental mode (`--inc`) and derives the project name from the path if not explicitly set.

### Programmatic Usage

```python
from metagpt.team import Team
from metagpt.roles import ProductManager, Architect, ProjectManager, Engineer, QaEngineer

team = Team()
team.hire([
    ProductManager(),
    Architect(),
    ProjectManager(),
    Engineer(n_borg=5, use_code_review=True),
    QaEngineer(),
])
team.invest(investment=3.0)  # USD budget
team.run_project(idea="Create a 2048 game")
await team.run(n_round=5)
```

### Logging

MetaGPT uses `loguru` for all logging. Default configuration:

- **Console**: `INFO` level
- **File**: `DEBUG` level, written to `{METAGPT_ROOT}/logs/{YYYYMMDD}.txt`

Customize with:

```python
from metagpt.logs import define_log_level
logger = define_log_level(print_level="DEBUG", logfile_level="DEBUG", name="myapp")
```

### Progress Reporting

MetaGPT includes a pluggable reporting system (`metagpt/utils/report.py`) with multiple reporter backends:

| Reporter | Output |
|----------|--------|
| `TerminalReporter` | Console (default) |
| `BrowserReporter` | WebSocket to browser UI |
| `ServerReporter` | HTTP POST to `METAGPT_REPORTER_URL` |
| `NotebookReporter` | Jupyter notebook cells |
| `FileReporter` | File system |

### Serialization & Recovery

Roles and Teams support serialization for crash recovery:

```python
# Save state
serialized = team.serialize()

# Recover from saved state
team = Team()
team.deserialize(serialized)
```

`SerializationMixin` provides automatic JSON serialization with class type tracking for polymorphic deserialization. State is stored in `{DEFAULT_WORKSPACE_ROOT}/storage/`.

---

## Performance

### Token Optimization

- **Per-role model assignment**: Use cheaper models for code generation, expensive models for design
- **`max_auto_summarize_code`**: Controls how many rounds of automatic code summarization occur (reduces context for later rounds)
- **`code_validate_k_times`**: Number of code validation retries before accepting (default: 2)
- **`repair_llm_output`**: When `true`, attempts to fix malformed JSON responses rather than re-querying

### Memory Management

- Short-term memory (`Memory`): In-process list of `Message` objects, bounded by role context
- Long-term memory (`LongTermMemory`): Persists to vector store (FAISS), recoverable across sessions
- `RoleZeroLongTermMemory`: RAG-backed memory with configurable `memory_k` (capacity) and `similarity_top_k` (retrieval count)

### Timeout Configuration

| Setting | Default | Notes |
|---------|---------|-------|
| `llm.timeout` | 300s | Per-request LLM timeout |
| `USE_CONFIG_TIMEOUT` (0) | Uses `llm.timeout` | Sentinel value |
| `LLM_API_TIMEOUT` | 300s | Fallback timeout constant |

---

## Security

### API Key Management

> [!CAUTION]
> API keys in `config2.yaml` are stored in plaintext. Protect this file with appropriate filesystem permissions (`chmod 600`). For production deployments, prefer environment variables or vault integration.

Configuration precedence for API keys:

1. `~/.metagpt/config2.yaml` (user-level, highest priority)
2. `{project}/config/config2.yaml` (project-level)
3. Environment variables (lowest priority)

If both user-level and project-level configs contain API keys, MetaGPT raises a warning:

```
Please set your API key in {root_config_path}. If you also set your config in {repo_config_path},
the former will overwrite the latter. This may cause unexpected result.
```

### Code Execution Safety

MetaGPT generates and executes Python code as part of the Data Interpreter workflow. The `RunCode` action (`metagpt/actions/run_code.py`) supports:

- `run_text()`: Executes code strings via `exec()`
- `run_script()`: Runs scripts as subprocesses

There is no sandbox or container isolation for generated code execution. The Data Interpreter executes notebook cells internally using `nbclient`.

> [!CAUTION]
> Generated code runs with the same privileges as the MetaGPT process. In production environments, run MetaGPT in a restricted user context or container with minimal filesystem and network access.

### Proxy Configuration

MetaGPT supports two levels of proxy:

- `llm.proxy`: Applied only to LLM API calls
- `proxy` (top-level): Applied to tools (requests, playwright, selenium)
- `NO_PROXY` / `no_proxy` environment variables are respected

### Known Security Issues

GitHub issue #1929 reports a potential command injection vector in `Terminal.run_command` where user-supplied input could be passed to shell execution without proper sanitization.

---

## Developer Internals

### Module Reference

#### Core Framework (`metagpt/`)

| Module | Lines | Purpose |
|--------|-------|---------|
| `config2.py` | ~220 | Configuration class, YAML loading, merge logic |
| `context.py` | ~100 | Runtime context: LLM instantiation, cost tracking |
| `context_mixin.py` | ~100 | Mixin for config/context/LLM injection into any component |
| `schema.py` | ~1000 | Message, Plan, Task, Document, serialization, UML models |
| `team.py` | ~120 | Team orchestration, hiring, budget, execution loop |
| `software_company.py` | ~90 | CLI entry point, project recovery |
| `const.py` | ~150 | Path constants, magic strings, defaults |
| `llm.py` | ~15 | LLM factory function |
| `logs.py` | ~100 | Logging setup, LLM stream, tool output hooks |
| `repo_parser.py` | ~800 | AST-based Python code analysis, class view generation |
| `subscription.py` | ~30 | Event subscription runner |
| `document.py` | ~180 | File system document operations, indexable documents |

#### Roles (`metagpt/roles/`)

| Role | Class | Actions |
|------|-------|---------|
| `ProductManager` | `RoleZero` | `WritePRD` |
| `Architect` | `RoleZero` | `WriteDesign` |
| `ProjectManager` | `RoleZero` | `WriteTasks` |
| `Engineer` | `Role` | `WriteCode`, `WriteCodeReview`, `SummarizeCode`, `FixBug` |
| `QaEngineer` | `Role` | `WriteTest`, `RunCode`, `DebugError` |
| `Researcher` | `Role` | `CollectLinks`, `WebBrowseAndSummarize`, `ConductResearch` |
| `TutorialAssistant` | `Role` | `WriteDirectory`, `WriteContent` |
| `Assistant` | `Role` | `TalkAction`, `SkillAction` |
| `Sales` / `CustomerService` | `Role` | Conversational handlers |
| `Teacher` | `Role` | `WriteTeachingPlanPart` |
| `Searcher` | `Role` | `SearchAndSummarize` |

#### Actions (`metagpt/actions/`)

44 action classes total. Key ones:

| Action | Purpose |
|--------|---------|
| `UserRequirement` | Injects user requirement into the pipeline |
| `WritePRD` | Generates product requirements document |
| `WriteDesign` | Produces system design and API specifications |
| `WriteTasks` | Breaks design into implementation tasks |
| `WriteCode` | Generates source code files |
| `WriteCodeReview` | Reviews and rewrites code |
| `WriteTest` | Generates unit tests |
| `RunCode` | Executes code (text or script) |
| `DebugError` | Analyzes and fixes test failures |
| `SummarizeCode` | Produces code summaries for context compression |
| `PrepareDocuments` | Initializes workspace, Git repo, writes requirements |
| `ActionNode` | Structured prompting with schema-validated output |

#### LLM Providers (`metagpt/provider/`)

| Provider | Class | Module |
|----------|-------|--------|
| OpenAI | `OpenAILLM` | `openai_api.py` |
| Azure OpenAI | `AzureOpenAILLM` | `azure_openai_api.py` |
| Anthropic | `AnthropicLLM` | `anthropic_api.py` |
| Google Gemini | `GeminiLLM` | `google_gemini_api.py` |
| Ollama | `OllamaLLM` | `ollama_api.py` |
| AWS Bedrock | `BedrockLLM` | `bedrock_api.py` |
| DashScope | `DashScopeLLM` | `dashscope_api.py` |
| ZhipuAI | `ZhiPuAILLM` | `zhipuai_api.py` |
| Qianfan | `QianFanLLM` | `qianfan_api.py` |
| Spark | `SparkLLM` | `spark_api.py` |
| Volcengine Ark | `ArkLLM` | `ark_api.py` |
| OpenRouter | `OpenrouterReasoningLLM` | `openrouter_reasoning.py` |
| MetaGPT API | `MetaGPTLLM` | `metagpt_api.py` |
| Human Provider | `HumanProvider` | `human_provider.py` |

All providers inherit from `BaseLLM` (`metagpt/provider/base_llm.py`) and are registered via `LLMProviderRegistry`. The registry maps `LLMType` enum values to provider classes.

#### Memory System (`metagpt/memory/`)

| Class | Purpose | Persistence |
|-------|---------|-------------|
| `Memory` | Short-term message buffer | In-process only |
| `LongTermMemory` | Vector-indexed persistent memory | FAISS via `MemoryStorage` |
| `BrainMemory` | Conversational memory with summarization | Redis |
| `RoleZeroLongTermMemory` | RAG-backed memory for RoleZero agents | ChromaDB/BM25 |
| `MemoryStorage` | FAISS-based vector store wrapper | Local filesystem |

#### RAG Subsystem (`metagpt/rag/`)

Built on llama-index, the RAG subsystem uses a factory pattern:

```
RAGEmbeddingFactory  → Creates embedding models
RAGIndexFactory      → Creates vector indices (FAISS, Chroma, Elasticsearch, BM25)
RetrieverFactory     → Creates retrievers with config
RankerFactory        → Creates rerankers (LLM, Colbert, Cohere, BGE, Object)
```

Supported vector stores:

| Store | Config Class | Notes |
|-------|-------------|-------|
| FAISS | `FAISSRetrieverConfig` | Default, local filesystem |
| ChromaDB | `ChromaRetrieverConfig` | Persistent client |
| Elasticsearch | `ElasticsearchRetrieverConfig` | Remote, keyword + vector |
| BM25 | `BM25RetrieverConfig` | No embedding required |

Supported rerankers:

| Ranker | Config Class | Extra Package Required |
|--------|-------------|----------------------|
| LLM Reranker | `LLMRankerConfig` | None |
| Colbert | `ColbertRerankConfig` | `llama-index-postprocessor-colbert-rerank` |
| Cohere | `CohereRerankConfig` | `llama-index-postprocessor-cohere-rerank` |
| BGE | `BGERerankConfig` | `llama-index-postprocessor-flag-embedding-reranker` |
| Object Ranker | `ObjectRankerConfig` | None |

#### Experience Pool (`metagpt/exp_pool/`)

Stores and retrieves past execution experiences:

| Component | Class | Purpose |
|-----------|-------|---------|
| `ExperienceManager` | `BaseModel` | CRUD interface for experiences |
| `ExpCacheHandler` | `BaseModel` | Decorator-based experience caching |
| `Experience` | `BaseModel` | Data model with `rag_key` for retrieval |

Retrieval types: `bm25` (text-based, no embeddings) or `chroma` (vector-based, requires embeddings).

#### Document Stores (`metagpt/document_store/`)

| Store | Class | Backend |
|-------|-------|---------|
| FAISS | `FaissStore` | faiss_cpu |
| ChromaDB | `ChromaStore` | chromadb |
| LanceDB | `LanceStore` | lancedb |
| Milvus | `MilvusStore` | pymilvus |
| Qdrant | `QdrantStore` | qdrant-client |

### Extension Architecture

#### SELA (`metagpt/ext/sela/`)

Automated machine learning via Monte Carlo Tree Search. Uses Data Interpreter internally to run experiments, evaluate models, and iterate on ML pipeline designs.

Requirements: `pip install openml xgboost catboost lightgbm`

#### AFlow (`metagpt/ext/aflow/`)

Automated workflow optimization. Iteratively evolves agent workflows to maximize benchmark performance.

CLI:
```bash
python examples/aflow/optimize.py \
  --dataset <name> \
  --opt_model_name claude-3-5-sonnet-20240620 \
  --exec_model_name gpt-4o-mini \
  --max_rounds 20
```

#### SPO (`metagpt/ext/spo/`)

Self-supervised prompt optimization. Includes both CLI and Streamlit UI:

```bash
# CLI
python examples/spo/optimize.py \
  --opt-model claude-3-5-sonnet-20240620 \
  --template Poem.yaml \
  --max-rounds 10

# Streamlit UI
streamlit run metagpt/ext/spo/app.py
```

#### Stanford Town (`metagpt/ext/stanford_town/`)

Generative agents simulation based on the Stanford/Google research paper. Simulates a virtual town with agents that form memories, reflect, and plan daily activities.

#### Werewolf Game (`metagpt/ext/werewolf/`)

Multi-agent social deduction game implementation. Demonstrates adversarial multi-agent interaction with hidden roles and deception.

#### Android Assistant (`metagpt/ext/android_assistant/`)

Automated Android device interaction using screen analysis, accessibility trees, and touch/swipe actions.

Requirements: `pip install metagpt[android_assistant]`

#### Minecraft Environment (`metagpt/environment/minecraft/`)

Integration with Minecraft via Mineflayer (Node.js). Provides an Express.js server (port 3000) that accepts bot commands via HTTP POST.

Requirements: Node.js, `npm install` in the mineflayer directory.

### Code Patterns

#### Pydantic Throughout

All data models, configuration classes, roles, actions, and schemas use Pydantic v2 `BaseModel`. Key patterns:

- `model_config = ConfigDict(arbitrary_types_allowed=True)` for classes that hold non-serializable objects
- `Field(default_factory=...)` for mutable defaults
- `model_validator(mode="after")` for cross-field validation
- `@field_validator` for individual field constraints

#### ContextMixin Pattern

`ContextMixin` is the dependency injection mechanism. It provides `config`, `context`, and `llm` properties with fallback chains:

```
private_config → context.config (fallback)
private_context → new Context() (fallback)
private_llm → context.llm_with_cost_manager_from_llm_config() (fallback)
```

Any class inheriting `ContextMixin` can override its config/LLM at any level without affecting siblings.

#### SerializationMixin Pattern

Provides JSON serialization with class type metadata (`__module_class_name`). During deserialization, it dynamically resolves the class and reconstructs the object. Used by `Role`, `Action`, and other polymorphic types.

#### Async Throughout

All LLM calls, action executions, and role workflows are `async`. The main entry points use `asyncio.run()` or Typer's async support. On Windows, the `_compat.py` module patches the event loop policy.

#### Factory Pattern in RAG

The RAG subsystem uses `ConfigBasedFactory` where configuration dataclass types serve as factory keys:

```python
factory = RAGIndexFactory()
index = factory.get_index(FAISSIndexConfig(persist_path="./data"))
```

### Testing

#### Test Structure

Tests mirror the source structure under `tests/`:

```
tests/
├── metagpt/
│   ├── actions/
│   ├── roles/
│   ├── provider/
│   ├── utils/
│   ├── rag/
│   ├── exp_pool/
│   ├── environment/
│   ├── ext/
│   │   ├── stanford_town/
│   │   └── werewolf/
│   ├── strategy/
│   └── ...
├── mock/
│   ├── mock_llm.py
│   ├── mock_aiohttp.py
│   └── ...
├── data/
│   └── rsp_cache.json    # Cached LLM responses
└── scripts/
```

#### Mock Strategy

`MockLLM` (`tests/mock/mock_llm.py`) replaces real LLM calls in tests. It:

1. Checks `tests/data/rsp_cache.json` for pre-recorded responses
2. Falls back to the original LLM if allowed by the test configuration
3. Raises `ValueError` with a clear message if an unexpected API call is attempted:
   ```
   In current test setting, api call is not allowed, you should properly mock
   your tests, or add expected api response in tests/data/rsp_cache.json.
   ```

#### Running Tests

```bash
# Core tests (no API calls)
pytest tests/ -x --timeout=300

# With specific extras
pip install metagpt[test]
pytest tests/ -x -v

# Single test file
pytest tests/metagpt/test_role.py -v
```

### Strategy Module (`metagpt/strategy/`)

Implements search and reasoning strategies:

| Class | Strategy | Purpose |
|-------|----------|---------|
| `BFSSolver` | Breadth-first search | Exhaustive thought exploration |
| `DFSSolver` | Depth-first search | Deep thought chains |
| `MCTSSolver` | Monte Carlo Tree Search | Balanced exploration/exploitation |
| `TreeofThought` | Tree of Thought | LLM reasoning tree with backtracking |
| `Planner` | Task planning | Decomposes problems into task sequences |

### Utility Modules (`metagpt/utils/`)

| Module | Purpose |
|--------|---------|
| `common.py` | `OutputParser`, `CodeParser`, `NoMoneyException` |
| `cost_manager.py` | Token/cost tracking per provider |
| `file.py` | File I/O with encoding detection |
| `file_repository.py` | Change-tracked file collections |
| `git_repository.py` | GitPython wrapper with change detection |
| `graph_repository.py` | Code dependency graph (SPO triples) |
| `redis.py` | Redis client wrapper |
| `s3.py` | S3 client wrapper |
| `repair_llm_raw_output.py` | JSON repair heuristics |
| `yaml_model.py` | `YamlModel` base class for YAML-backed configs |
| `singleton.py` | Thread-safe singleton metaclass |
| `pycst.py` | CST-based docstring manipulation |
| `report.py` | Progress reporting framework |
| `human_interaction.py` | Interactive input handling |
| `omniparse_client.py` | Document/PDF/video/audio parsing client |
| `sanitize.py` | Code sanitization utilities |

---

## Troubleshooting

### Configuration Errors

**"Please set your API key in config2.yaml"**
No LLM API key found in any config path. Create `~/.metagpt/config2.yaml` with at minimum:
```yaml
llm:
  api_type: "openai"
  api_key: "sk-..."
  model: "gpt-4-turbo"
```

**Config conflict warning (user vs project)**
Both `~/.metagpt/config2.yaml` and `{project}/config/config2.yaml` contain LLM settings. The user-level file takes precedence. Remove one to avoid confusion.

### Provider Errors

**`BlockedPromptException` (Gemini)**
Google's content filtering blocked the prompt. Rephrase or switch to a model without content restrictions.

**"Set the `access_key`&`secret_key` or `api_key`&`secret_key` first" (Qianfan)**
Qianfan requires either `access_key`+`secret_key` or `api_key`+`secret_key` in the LLM config.

**AWS Bedrock authentication failures**
Verify `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables are set.

### Runtime Errors

**`NoMoneyException`**
Budget exhausted. Increase `team.invest(investment=<higher_amount>)`.

**`FileNotFoundError: recover storage meta file 'team.json' not exist`**
Attempted to resume a project that has no saved state. Start a new project instead.

**`ImportError: To use the experience pool, you need to install the rag module`**
Install RAG dependencies: `pip install metagpt[rag]`

**`TypeError: To use RAG, please set your embedding in config2.yaml`**
RAG features require an embedding model. Add the `embedding` section to your config.

> [!NOTE]
> Check `{METAGPT_ROOT}/logs/` for detailed DEBUG-level logs when troubleshooting. Log files are named by date (`YYYYMMDD.txt`).

---

## Quick Reference

### Essential Files

| File | Purpose |
|------|---------|
| `~/.metagpt/config2.yaml` | User-level configuration (highest priority) |
| `config/config2.yaml` | Project-level configuration |
| `config/config2.example.yaml` | Full configuration template with all options |
| `config/vault.example.yaml` | Vault configuration template |
| `config/puppeteer-config.json` | Chromium path for Puppeteer |
| `metagpt/const.py` | All path constants and defaults |
| `metagpt/config2.py` | Config class definition and loading logic |
| `logs/{YYYYMMDD}.txt` | Daily log files |

### Common Operations

| Task | Command/Code |
|------|-------------|
| Initialize config | `metagpt --init-config` |
| New project | `metagpt "your requirement"` |
| Resume project | `metagpt --project-path ./workspace/myproject` |
| Install RAG support | `pip install metagpt[rag]` |
| Install all extras | `pip install metagpt[test]` |
| Run with Docker | See Docker Deployment section |
| Check version | `python -c "import metagpt; print('1.0.0')"` |

### Class Hierarchy (Core)

```
BaseModel (pydantic)
├── BaseSerialization
│   ├── BaseRole
│   │   └── Role
│   │       ├── Engineer
│   │       ├── QaEngineer
│   │       ├── Researcher
│   │       ├── Assistant
│   │       └── RoleZero
│   │           ├── ProductManager
│   │           ├── Architect
│   │           └── ProjectManager
│   ├── SerializationMixin
│   │   └── Action
│   │       ├── WritePRD
│   │       ├── WriteDesign
│   │       ├── WriteCode
│   │       └── ... (44 total)
│   └── BaseEnvironment
│       └── ExtEnv
│           └── Environment
├── ContextMixin
│   ├── Role (via multiple inheritance)
│   └── Action (via multiple inheritance)
├── Config (CLIParams, YamlModel)
├── Context
├── Message
├── Plan / Task / TaskResult
├── Memory
│   ├── LongTermMemory
│   └── RoleZeroLongTermMemory
└── CostManager
    ├── TokenCostManager
    └── FireworksCostManager
```

---

_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._