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)

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):

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

Core Dependencies

MetaGPT has ~90 direct dependencies. Key ones:

Optional Dependency Groups

Install via pip install metagpt[group]:

System-Level Dependencies

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

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):

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

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:

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

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

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

Mermaid Diagram Rendering

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

Storage: Redis

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

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

Storage: S3

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

Experience Pool

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

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

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:

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:

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

Key Path Constants

Defined in metagpt/const.py:

Deployment

pip Installation

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

Development Installation

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

Docker Deployment

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:

metagpt "Create a 2048 game"

Key CLI parameters (from CLIParams):

Important

Setting --project-path automatically enables incremental mode (--inc) and derives the project name from the path if not explicitly set.

Programmatic Usage

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:

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:

Serialization & Recovery

Roles and Teams support serialization for crash recovery:

# 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

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/)

Roles (metagpt/roles/)

Actions (metagpt/actions/)

44 action classes total. Key ones:

LLM Providers (metagpt/provider/)

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/)

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:

Supported rerankers:

Experience Pool (metagpt/exp_pool/)

Stores and retrieves past execution experiences:

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

Document Stores (metagpt/document_store/)

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:

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:

# 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:

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

# 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:

Utility Modules (metagpt/utils/)

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:

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

Common Operations

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