MetaGPT in Practice: Build a Small Python Tool with a Team of AI Agents

MetaGPT is often described as a multi-agent framework that turns a one-line prompt into a software project. That description is true, but it hides the part that matters: what do you actually type, what comes back, and how much of it can you trust? This guide skips the theory and walks through a real build. We’ll use MetaGPT to create a command-line habit tracker with SQLite, add, list, and streak commands. It’s small enough to finish in one sitting and fiddly enough to expose where the agents shine and where you still need to be the adult in the room.

What You Need Before the First Prompt

MetaGPT is a Python package that orchestrates several LLM-powered roles. Before you run anything, line up four things:

• Python 3.10 or newer. Older versions tend to break dependencies.
• An API key for an LLM. OpenAI works out of the box, and OpenAI-compatible endpoints like DeepSeek or OpenRouter usually work with a base URL change.
• About 20 minutes and a terminal. The first run is slower than later ones.
• Git, if you want to review what changed between agent runs. You will want to.

Step 1: Install MetaGPT and Pick a Model

Install from PyPI with pip install metagpt. If you want the newest features, install from the repository instead: pip install git+https://github.com/geekan/MetaGPT.git. Then run metagpt --init-config. This creates ~/.metagpt/config2.yaml, where you set your API key, model, and base URL.

For a small CLI tool, a cheaper model like GPT-4o mini is plenty. For architecture decisions or a larger codebase, use a stronger model. Don’t paste a production key into a shared machine. Use an environment variable instead: api_key: ${OPENAI_API_KEY}.

If you want the architectural background first, our MetaGPT explained article covers how the Product Manager, Architect, Project Manager, and Engineer agents hand off work. For this walkthrough, think of them as a tiny software team that writes documents before code.

Step 2: Run a One-Line Requirement

From your terminal, run something like this:

metagpt 'Create a command-line habit tracker in Python with SQLite. It should support add, list, and streak commands. Streak means consecutive days a habit has been logged, ending today. Include tests.'

The first run takes a few minutes. You’ll see agents produce a stack of artifacts:

• A product requirements document, usually in a workspace or docs folder
• User stories and sometimes a competitive analysis, which is overkill for a CLI tool
• An architecture design with data models and function signatures
• A task breakdown and code files
• Tests, if you asked for them

Concrete example: the habit tracker output might include habit_tracker/main.py, habit_tracker/db.py, tests/test_streak.py, plus docs/prd.md and docs/design.md. File names vary by MetaGPT version, but the pattern holds: docs first, then code.

Step 3: Read the Docs Before You Run the Code

This is the step most people skip. Open the PRD. Does ‘streak’ match your definition? The generated version might say ‘consecutive days with any logged activity,’ while your brain meant ‘consecutive days up to today.’ That difference becomes a bug later.

Check the architecture doc for database schema and command syntax. If the agent invented flags you don’t want, fix the prompt or edit the docs and rerun. MetaGPT supports project names and incremental runs in many versions, so you can continue a build instead of starting over. A practical pattern:

• Run the initial build in a named project folder.
• Read the docs and code.
• Add a follow-up request: ‘Revise the streak logic so a missing today does not break the streak; update tests.’
• Rerun incrementally if your version supports --inc or a named project.

If incremental mode fights you, treat the generated docs as a spec and edit the code yourself. MetaGPT is a scaffolder, not a genie.

Step 4: Run the Tests, Then Write One More

Run pytest. Generated tests often pass because they test the happy path. Add one test that catches the streak edge case:

def test_streak_ignores_missing_today(tmp_path):
    db = HabitDB(tmp_path / 'test.db')
    db.add_habit('read')
    db.log('read', date='2025-01-01')
    db.log('read', date='2025-01-02')
    assert db.streak('read', today='2025-01-03') == 2

If that fails, you’ve found a real gap. Fixing it yourself takes five minutes. Asking the agent to fix it may take fifteen and a new API bill. Both are valid. The point is to verify behavior, not just file creation.

General autonomous agents like AutoGPT take a looser approach, chaining actions until a goal is met. Our AutoGPT in practice guide shows what that looks like. MetaGPT’s SOP-driven roles feel more like a project team, which is why the docs exist at all.

Step 5: Customize a Role for Your Domain

Default roles are general software. For a data team, define a Data Engineer, an Analytics Engineer, and a BI Reviewer. In Python, a role pairs a name, profile, goal, and actions. The exact API changes between versions, so check the repository examples. The conceptual move is what matters: give each agent a narrow responsibility and a concrete output format.

Example custom reviewer instructions:

• Role: Security Reviewer
• Goal: Find injection risks, unsafe deserialization, and missing input validation.
• Output: A Markdown table with file, line, risk, and recommended patch.

That kind of role is more useful than a generic ‘critic’ because it produces a format you can act on. You can also add a Test Writer role that only creates pytest cases from the PRD.

Step 6: Harden the Output Before You Ship

Generated code is a first draft. Before deploying the habit tracker, do the boring work:

• Move secrets to environment variables.
• Add argument parsing with argparse or click if the generated CLI is brittle.
• Handle database file paths and missing tables gracefully.
• Run ruff and mypy.
• Commit in small chunks so you can see what the agent changed.

This is where the broader shift in AI programming tools and agents becomes practical. The value isn’t that an agent writes every line. It’s that you start with a structured draft and spend your time on decisions, not boilerplate.

Common Traps and How to Avoid Them

Most disappointing MetaGPT runs come from vague prompts or skipped review. A few fixes:

• Be specific about constraints. ‘Python 3.11, SQLite, no external database, tests with pytest’ beats ‘make a habit tracker.’
• Name your edge cases. Say ‘streak ends today, ignores future logs’ so the Product Manager agent writes it down.
• Budget tokens. A 10-file project can burn more than you expect, especially if you rerun from scratch. Use a cheap model for doc generation and a stronger one for architecture if your config allows it.
• Pin versions. MetaGPT moves fast. Record the version you used with pip show metagpt so a future rerun doesn’t surprise you.
• Keep a human in the loop. Agents are confident even when wrong. Read the diff.

Where MetaGPT Shines and Where It Doesn’t

MetaGPT is strongest when the task looks like a small internal tool: CRUD apps, CLI utilities, data parsers, API wrappers, and prototype dashboards. It’s weaker when you need pixel-perfect UI, deep integration with legacy systems, compliance-grade security, or performance tuning against a real workload. It also struggles when requirements live in your head and you refuse to write them down. The framework’s whole premise is that structured documents lead to better code, so if you feed it mush, you get organized mush.

Pick something small this week. A 200-line tool you’ve been putting off. Give MetaGPT a clear prompt, read the PRD, run the tests, and fix one edge case yourself. You’ll learn more from that hour than from ten overview articles, and you’ll have a working script at the end.