🛠️ Engineering Team — A Multi-Agent Software Team Built with CrewAI

An autonomous engineering crew that takes a plain-English requirement and delivers working, tested software — a design doc, a backend module, a unit-test suite, and a polished Gradio UI — all written and executed inside an isolated sandbox.

<p align="left"> <img alt="Python" src="https://img.shields.io/badge/Python-3.10--3.13-3776AB?logo=python&logoColor=white"> <img alt="CrewAI" src="https://img.shields.io/badge/CrewAI-1.14.4-FF5A5F"> <img alt="uv" src="https://img.shields.io/badge/packaged%20with-uv-DE5FE9"> <img alt="Gradio" src="https://img.shields.io/badge/Gradio-6.x-F97316?logo=gradio&logoColor=white"> <img alt="MCP" src="https://img.shields.io/badge/MCP-Context7-6E56CF"> </p>

This project moves past single-agent demos into a genuinely collaborative crew: four specialised agents, a shared sandbox, task-to-task context passing, live documentation lookups over MCP, and Docker-isolated code execution.

Above: the Gradio front end written entirely by the Frontend Engineer agent — light/dark-aware, brand-themed, with live account summary, holdings, and transaction history.

---

📋 Table of Contents

• What it does
• Architecture
• The crew
• The task pipeline
• What the crew produced
• Technical highlights
• Project structure
• What I learnt

---

🎯 What it does

You give the crew a high-level, natural-language brief. In this project the brief is a trading-simulation account management system:

Create accounts, deposit and withdraw funds, buy and sell shares, value the portfolio, report profit/loss and holdings, list transactions — and never let a user withdraw into a negative balance, over-buy beyond their cash, or sell shares they don't own.

The crew then autonomously:

1. Designs the system (modules, classes, method signatures — no code yet).
2. Writes the backend in pure standard-library Python.
3. Builds a professional Gradio front end to demonstrate it.
4. Tests the backend with unittest, fixing defects until everything is green.

Every file is written into a fresh, isolated sandbox/ project, and every piece of code is actually run — not just generated and hoped over.

---

🏗️ Architecture

flowchart TD
    REQ["📝 Plain-English requirements<br/>(main.py)"] --> LEAD

    subgraph CREW["🤖 CrewAI — sequential process"]
        LEAD["👷 Engineering Lead<br/><i>designs the system</i>"]
        BE["🐍 Backend Engineer<br/><i>writes account_manager.py</i>"]
        FE["🎨 Frontend Engineer<br/><i>writes app.py (Gradio)</i>"]
        TE["🧪 Test Engineer<br/><i>writes &amp; runs unit tests</i>"]

        LEAD -->|design.md as context| BE
        BE -->|code as context| FE
        BE -->|code as context| TE
    end

    LEAD -. "Context7 MCP<br/>latest Gradio 6 docs" .-> MCP[("📚 Context7")]
    FE   -. "Context7 MCP" .-> MCP

    BE & FE & TE ==>|write / read / run| SANDBOX

    subgraph SANDBOX["📦 Isolated sandbox (uv project)"]
        DESIGN["design.md"]
        BACKEND["account_manager.py"]
        APP["app.py"]
        TESTS["test_account_manager.py"]
    end

    APP --> UI["🖥️ Gradio web UI"]
    TESTS --> RESULT["✅ 23 passing tests"]

The core idea: each agent has a narrow role and only the tools it needs. The Lead thinks but doesn't code; the engineers code but work strictly to the design; the sandbox is the single shared surface they all read from and write to. Context flows forward so no agent has to re-derive what an earlier one already decided.

---

🤖 The crew

Four agents, each configured in config/agents.yaml:

| Agent | Role | Tools | Why it's interesting | |-------|------|-------|----------------------| | Engineering Lead | Turns requirements into a detailed markdown design — modules, classes, and method signatures only, no code. | Context7 MCP | Queries live Gradio 6 documentation over MCP so the design hands the frontend engineer correct, current API guidance. | | Backend Engineer | Implements the design in standard-library-only Python. | Sandbox tools | Forbidden from writing any UI code — strict separation of concerns. | | Frontend Engineer | Builds a single-file Gradio app and a validation script that confirms the UI constructs without launching it. | Sandbox tools + Context7 MCP | Works to a fixed brand palette that must read well in both light and dark mode. | | Test Engineer | Writes unittest tests, runs them, fixes backend defects, and repeats until green. | Sandbox tools | Explicitly instructed not to break the frontend while fixing the backend. |

All four run on openai/gpt-5.4-mini.

---

🔄 The task pipeline

Defined in config/tasks.yaml and run as a sequential Process. Each task receives earlier tasks as explicit context:

| # | Task | Agent | Depends on | Output | |---|------|-------|-----------|--------| | 1 | design_task | Engineering Lead | — | sandbox/design.md | | 2 | code_task | Backend Engineer | design | backend written to sandbox | | 3 | frontend_task | Frontend Engineer | code + design | sandbox/app.py + _validate.py | | 4 | test_task | Test Engineer | code + design | sandbox/test_summary.md |

This context wiring is what turns four independent agents into an actual team — the frontend engineer sees both the design and the real backend before writing a single Gradio component.

---

📦 What the crew produced

The crew's own output artefacts live in sandbox/:

• design.md — a detailed design document: domain model, method signatures, per-operation validation rules, and a dedicated "Gradio 6 API Guidance" section for the frontend engineer.
• account_manager.py — the backend: an AccountManager service, Account and Transaction dataclasses, a pluggable price_provider, and a typed exception hierarchy (InsufficientFundsError, InsufficientHoldingsError, InvalidTransactionError, …).
• app.py — a themed, tabbed Gradio 6 front end (Account Setup · Cash Operations · Trading · Reports) with light/dark-aware styling.
• test_account_manager.py — 23 unit tests covering the happy paths and every guard rail, all passing.

The backend enforces exactly the rules from the brief:

# You can't withdraw into the red …
if account.cash_balance < amount:
    raise InsufficientFundsError("Insufficient funds")

# … buy more than you can afford …
if account.cash_balance < total_cost:
    raise InsufficientFundsError("Insufficient funds")

# … or sell shares you don't hold.
if account.holdings.get(symbol, 0) < quantity:
    raise InsufficientHoldingsError("Not enough shares to sell")

---

⭐ Technical highlights

These are the parts that go beyond a standard tutorial crew:

1. Live documentation over MCP (Context7)

The Engineering Lead and Frontend Engineer connect to the Context7 MCP server so their knowledge of the Gradio 6 API is current rather than frozen at the model's training cut-off. The Lead bakes the correct kwargs and method signatures straight into the design, which matters because Gradio 6 changed several APIs.

2. A monkey-patch for a real CrewAI bug

patch.py fixes a genuine bug in CrewAI 1.14.4: over HTTPS, MCP tool names are sanitised on discovery, but the sanitised name is then sent back to the server — so any server-side tool whose name contains a hyphen (e.g. Context7's resolve-library-id) becomes unreachable. The patch preserves the original tool name for the actual call. Importing the module applies the fix as a side effect:

import engineering_team.patch  # noqa: F401 — applies the MCP monkey-patch on import

3. Docker-isolated code execution

sandbox_tools.py gives the agents four tools — list, read, write, and run. Crucially, run executes generated code inside an ephemeral Docker container with the sandbox mounted read/write, so agent-authored code never touches the host directly:

subprocess.run([
    "docker", "run", "--rm",
    "-v", f"{SANDBOX_DIR}:/workspace", "-w", "/workspace",
    "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
    "uv", "run", filename,
], capture_output=True, text=True, timeout=300)

4. Deliberate cache-busting

Because the sandbox changes between calls (files appear, change, and run), the tools opt out of CrewAI's default tool-result caching — otherwise agents would act on stale reads:

for _t in sandbox_tools:
    _t.cache_function = _never_cache  # sandbox state is never safe to cache

5. A fresh sandbox every run

reset_sandbox() wipes and re-initialises the sandbox as a clean uv project with Gradio installed before each kickoff, so runs are reproducible and never contaminated by a previous attempt.

---

🗂️ Project structure

engineering_team/
├── README.md
├── pyproject.toml               # uv workspace; declares the sandbox as a member
├── assets/
│   └── trading-simulation.png   # screenshot of the running Gradio appknowledge/
├── src/engineering_team/
│   ├── main.py                  # entry point + the requirements brief
│   ├── crew.py                  # agent, task & crew wiring (@CrewBase)
│   ├── patch.py                 # CrewAI 1.14.4 MCP hyphen-name fix
│   ├── config/
│   │   ├── agents.yaml          # the 4 agent definitions
│   │   └── tasks.yaml           # the 4 task definitions + context graph
│   └── tools/
│       └── sandbox_tools.py     # list / read / write / run (Docker) + reset
└── sandbox/                     # ← everything below is generated by the crew
    ├── design.md
    ├── account_manager.py
    ├── app.py
    ├── _validate.py
    └── test_account_manager.py

---

🎓 What I learnt

• Designing a role-specialised crew — giving each agent a tight role, backstory, and only the tools it needs, rather than one over-powered generalist.
• Passing context between tasks so a sequential pipeline behaves like a real team handing work down the line.
• Integrating MCP servers (Context7) to give agents live, current knowledge — and debugging the integration when the framework itself misbehaved.
• Sandboxing agent-generated code with Docker so autonomous execution stays safe and reproducible.
• Framework-level debugging — reading CrewAI internals and writing a targeted monkey-patch instead of waiting for an upstream fix.
• The realities of agentic output — from managing API cost across many calls to handling quirks in generated code (see below).