AgenticDev

A multi-LLM agentic framework: a Gemini Orchestrator dynamically dispatches four specialized agents via function calls to transform a free-text request into tested, documented code — including SVG visual assets.

User request
    │
    ▼
LangGraph Pipeline
    ├── Architect  (Gemini) → output/spec.md
    ├── Designer   (Gemini) → output/assets/*.svg + manifest.json
    ├── Developer  (Gemini / Claude) → output/*.py + README.md
    └── Tester     (Gemini) → output/tests/ + pytest/jest execution
                        │
                        ▼ (fix loop up to 3×)
                   Developer ← failing tests

---

Prerequisites

• Python 3.9+
• A Google Gemini API key
• An Anthropic Claude API key (optional — only if using ClaudeAgent for the Developer)

---

Installation

git clone https://github.com/HamdiMechelloukh/AgenticDev.git
cd AgenticDev
python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows
pip install -r requirements.txt

Copy .env.example to .env and fill in your API keys:

cp .env.example .env

---

Usage

CLI

# Pass the request as an argument
python main.py "create a REST API with FastAPI for a todo list"

# Or run interactively
python main.py
# → Enter your development request: ...

Generated files appear in ./output/:

output/
├── spec.md          ← technical specification (Architect)
├── assets/          ← SVG sprites + manifest.json (Designer)
├── *.py             ← source code (Developer)
├── README.md        ← generated project documentation (Developer)
└── tests/
    └── test_*.py    ← pytest / Jest tests (Tester)

From Python

from runner import Runner

runner = Runner(output_dir="./output")
final_state = runner.run("create a function that sorts a list of dictionaries by key")

print(final_state["generated_files"])   # list of created files
print(final_state["test_results"])      # test summary
print(final_state["architecture_spec"]) # content of spec.md

---

Architecture

Agent as Tool pattern

Sub-agents are exposed to the LangGraph pipeline as deterministic graph nodes. The pipeline decides the execution order and automatically retries the Developer when tests fail (up to MAX_FIX_ITERATIONS = 3).

Class hierarchy

BaseAgent (ABC)
├── GeminiAgent          → google-genai, implicit prompt caching
│   ├── ArchitectAgent   → tools: web_search, write_file
│   ├── TesterAgent      → tools: read_file, write_file, execute_code
│   ├── DeveloperAgent   → tools: read_file, write_file
│   └── DesignerAgent    → overrides run() for direct SVG generation
└── ClaudeAgent          → anthropic, explicit cache_control on system/tools/messages
    └── DeveloperAgent   → tools: read_file, write_file

Prompt caching

Agent	Strategy
Gemini agents	Implicit caching — repeated prefixes (system + stable context) are cached automatically by Google. Savings appear in cached_content_token_count.
Claude (Developer)	Explicit caching via cache_control: ephemeral on the system prompt, tool definitions, and first user message.

Cache hit rates are logged on every call:

[Developer] cache write: 312 tokens
[Developer] cache read: 312/680 tokens (45% hit)

Available tools (tools.py)

Function	Description
write_file(path, content)	Write a file, creating parent directories as needed
read_file(path)	Read and return the content of a file
execute_code(command)	Execute a shell command, capture stdout/stderr
web_search(query)	Search via DuckDuckGo Instant Answer API

---

Running tests

python -m pytest tests/ -v

---

Extending the framework

Add a new Gemini agent

from agent import GeminiAgent
from tools import read_file, write_file
from models import TaskContext, AgentResult

class DocumenterAgent(GeminiAgent):
    def __init__(self):
        super().__init__(
            name="Documenter",
            instructions="You generate API documentation from source code...",
            tools=[read_file, write_file],
        )

    def run(self, context: TaskContext) -> AgentResult:
        result = super().run(context)
        # post-processing...
        return result

Add a Claude agent

from agent import ClaudeAgent

class ReviewerAgent(ClaudeAgent):
    def __init__(self):
        super().__init__(
            name="Reviewer",
            instructions="You review code for security issues and best practices...",
            tools=[read_file],
        )

Expose a new agent in the pipeline

Add a new node in graph.py and wire it into the StateGraph.

---

Environment variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Google Gemini API key
ANTHROPIC_API_KEY	No	Anthropic API key (only if Developer = ClaudeAgent)

---

Models

Agent	Default model
Architect	gemini-3.1-pro-preview
Designer	nano-banana-pro-preview
Tester	gemini-3-flash-preview
Developer (Gemini)	gemini-3.1-pro-preview
Developer (Claude)	claude-sonnet-4-6

Pass model_name= to any agent constructor to override.