Agentic Engineering Team

This repository contains a proof‑of‑concept for agentic software development: a trading simulation account management system built entirely by a coordinated team of AI agents. It showcases how specialized models can collaborate under human‑defined roles to deliver production‑quality code.

Overview

The project implements the backend logic, a web interface, and comprehensive tests for managing user accounts, transactions, and portfoli o valuation within a simulated trading environment. All components were generated by four autonomous agents orchestrated by CrewAI.

Key features:

• Account creation with deposit/withdraw operations
• Mock stock trading with current asset prices
• Real‑time portfolio valuation and profit/loss computation
• Interactive web UI powered by Gradio
• Automated test suite ensuring correctness

Crew Architecture

Four agents fulfill distinct engineering roles. Their responsibilities and outputs mirror a traditional development team, but each is a GPT‑class model instance with a focused prompt.

| Agent | Responsibility | Deliverable | |-------|----------------|-------------| | Lead Engineer | Analyze requirements, design data structures and algorithms | accounts.py_design.md (design specification) | | Backend Engineer | Implement core business logic following the design | accounts.py | | Frontend Engineer | Construct the Gradio UI and integrate backend | app.py | | Test Engineer | Write and execute unit tests to validate functionality | test_accounts.py |

Agents interact through CrewAI's shared context, allowing the Lead to feed design decisions downstream and enabling QA to request re‑runs if issues are found.

Detailed Workflow Diagrams

High‑level sequence

sequenceDiagram
    participant Lead as Lead Engineer
    participant Backend
    participant Frontend
    participant QA as Test Engineer

    Lead->>Backend: design spec
    Backend->>Frontend: core module
    Backend->>QA: core module
    par parallel_tasks
        Frontend->>App: build UI
        QA->>Backend: execute tests & report
    end
    QA-->>Backend: feedback loop (if failures)

Data and control flow

flowchart TD
    design[Design spec]
    backend[Backend module]
    frontend[Gradio app]
    tests[Test suite]
    user[End user]

    design --> backend
    backend --> frontend
    backend --> tests
    frontend --> user
    tests --> backend

These diagrams illustrate both the sequential hand‑offs and the parallel workstreams enabled once the backend library exists.

Technical Stack & Rationale

The project leverages the following technologies:

| Component | Technology | Purpose | Why chosen | |-----------|------------|---------|------------| | Orchestration | CrewAI | Manages agent lifecycle, prompts, and shared context | Specialization and modularity outperform monolithic prompts. Logs provide auditability for review. | | Language | Python 3.10+ | Implementation language for agents and application | Widely supported, simple syntax, extensive standard library. | | Web UI | Gradio | Build interactive front‑end with minimal code | Quick prototyping, built‑in server, no frontend framework needed. | | Containerization | Docker | Isolate agent code execution | Ensures security, reproducibility, and resource control during generation and testing. | | Dependency management | UV (uvicorn?) / pip | Install required packages | pyproject.toml declares dependencies for repeatable installs. |

Usage Details

• Python / Gradio: The backend module exposes functions that Gradio components call directly; no REST layer is required. This maximizes simplicity and ensures the UI always reflects the latest logic.
• Docker sandboxing: Each agent run mounts the workspace in a container with restricted permissions. The container is discarded after execution, preventing runaway processes or malicious code from persisting.
• CrewAI specialization: Separate prompts for design, implementation, UI, and testing allow each agent to focus on a single concern. CrewAI also handles passing artifacts (code, docs) between agents and re‑invoking agents when feedback is given.

Installation & Usage

Prerequisites

• Python 3.10 or later
• Docker Desktop (running) for secure agent execution
• OpenAI API key (stored in .env)

Setup Steps

# Clone repository
git clone <repository-url>
cd engineering_team

# Create and activate virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate

# Install Python dependencies
pip install crewai gradio
# or: uv install  (if uv is configured)

# Set environment variables
cat <<'EOF' > .env
OPENAI_API_KEY=sk-your-key
EOF

Running the System

1. Run the Crew – the agents generate or update application files:

python -m engineering_team.main

1. Run the generated application:

python output/app.py

• Open a browser to http://127.0.0.1:7860 to access the Gradio UI.

1. Execute tests:

python output/test_accounts.py

Tests execute in the local environment; the Crew also uses Docker to run them when generating artifacts.

Mathematical Foundations

The backend computes portfolio metrics using standard formulas. Given holdings $A_i$ and prices $P_i$:

[ V_{portfolio} = \sum_i A_i \cdot P_i ]

With cash balance $C$ and cost basis $B$, profit/loss is:

[ \text{P/L} = V_{portfolio} + C - B ]

These expressions are encapsulated in the Account class methods in accounts.py and recalculated after each trade.

Directory Structure

engineering_team/
├── src/
│   └── engineering_team/
│       ├── config/
│       │   ├── agents.yaml     # Agent definitions (roles, prompts)
│       │   └── tasks.yaml      # Task templates for CrewAI
│       ├── crew.py             # Agent orchestration logic
│       └── main.py             # Entry point for running the crew
├── output/                     # Generated artifacts (backend, UI, tests)
│   ├── accounts.py
│   ├── accounts.py_design.md
│   ├── app.py
│   └── test_accounts.py
├── .env                        # Environment variables (API key)
├── pyproject.toml              # Dependency manifests
└── README.md                   # Project documentation

Notes

• This project is intended as a demonstration; production use would require additional security, validation, and error handling.
• The agent prompts and configuration files in src/config can be modified to adapt the crew to new domains.

For more operational details, refer to run.md and the individual agent design documents located alongside source code.