agentic-software-engineer

ASE — Agentic Software Engineer

Tu gli dici cosa fare, gli agenti lo fanno.

ASE è un framework che trasforma richieste in linguaggio naturale in codice, test, documentazione e deployment — tramite 11 agenti LLM specializzati che lavorano in autonomia sul tuo progetto. Tu supervisioni, loro eseguono.

Come Funziona

Tu: "Implementa API REST per utenti con JWT"
 │
 ▼
ASE: intake → analyzer → triage → orchestrator
 │
 ├─→ Backend Agent  → scrive codice
 ├─→ Testing Agent  → scrive test
 ├─→ Security Agent → audit JWT
 ├─→ Docs Agent     → documentazione
 │
 ▼
Output: codice, test, docs — tutto tracciato con costi e decision log

Non cloni niente. Installi ASE, lo punti al progetto del cliente, e gli dai istruzioni. Gli agenti fanno il resto.

Installa

pip install agentic-software-engineer

Uso

1. Vai nella root del tuo progetto

cd /path/to/mio-progetto

2. Configura la chiave API

Crea un file .env nella root del progetto:

ANTHROPIC_API_KEY=sk-ant-la-tua-chiave

3. Inizializza ASE

ase init

ASE crea una cartella .ase/ (nascosta e gitignored automaticamente):

• .ase/config.toml — configurazione agenti, modello, limiti
• .ase/ase.db — database SQLite per stato e tracking

4. Onboarding — insegna ad ASE il tuo progetto

ase onboard

ASE scansiona i file del progetto (README, package.json, Dockerfile, CI config…) e impara automaticamente tech stack, architettura, convenzioni. Per quello che non riesce a inferire, ti fa domande mirate.

Puoi anche fare solo auto-discovery senza domande:

ase onboard --auto-only

5. Dai lavoro agli agenti

ase submit "Aggiungi endpoint CRUD per i prodotti con validazione"

Il pipeline parte in automatico:

1. Intake — normalizza la richiesta, crea il ticket
2. Analyzer — capisce intent, complessità, scope
3. Triage — decide quali agenti servono, crea il plan
4. Orchestrator — esegue il plan rispettando le dipendenze
5. Agenti — Backend, Testing, Security, Docs… ognuno fa il suo
6. Review — gate configurabile (PR, manuale, auto-approve)

Tutto tracciato: ogni decisione, ogni tool call, ogni centesimo speso.

6. Monitora

# Stato dei ticket e degli agenti
ase status

# Costi e metriche
ase metrics

# Decision log completo
ase audit

# Audit filtrato per agente o ticket
ase audit --agent backend --last 20
ase audit --ticket T-001

# Segui gli eventi in tempo reale
ase audit --follow

7. Runtime persistente (opzionale)

Se vuoi tenere ASE in ascolto continuo per ricevere ticket:

ase start

Lancia i server MCP, connette il bridge, e resta in attesa. Utile quando integri ASE con altri sistemi di intake (webhook, bot, etc.).

CLI — Comandi Disponibili

Tutti i comandi lavorano dalla directory corrente. Basta essere nella root del progetto.

Agenti

Ogni agente ha il suo system prompt specializzato e un set di tool MCP dedicato. Gli agenti comunicano tramite il Bridge che traduce automaticamente le tool call verso il server MCP corretto (Operativo per lo stato runtime, Statico per il contesto progetto).

Configurazione — .ase/config.toml

[project]
name = "my-api"
description = "REST API per gestione utenti"

[llm]
default_model = "anthropic/claude-sonnet-4-20250514"
cost_limit_per_ticket_usd = 5.00
cost_limit_daily_usd = 100.00

[agents]
enabled = ["analyzer", "triage", "backend", "testing"]

[agents.model_overrides]
triage = "anthropic/claude-sonnet-4-20250514"

[fault_tolerance]
max_self_retries = 3
max_peer_escalations = 2

[hil]
review_method = "pr"   # pr | manual | auto-approve

Fault Tolerance

3 livelli di recovery automatico:

1. L1 — Self-retry: l'agente ritenta con exponential backoff
2. L2 — Peer escalation: se l'agente fallisce, un altro prende il task
3. L3 — Human notification: se tutto fallisce, notifica l'umano

Session Resume

Se il processo muore, niente si perde. Tutto lo stato è in SQLite (.ase/ase.db): ticket, assignment, plan, retry count, escalation level.

Al prossimo ase start o ase resume, ASE:

1. Cerca ticket in in_progress o triaged
2. Legge gli assignment dal DB — chi ha finito, chi era in corso
3. Riprende il plan da dove si era fermato (step completati = skip, falliti = retry)

# Resume esplicito (boot, resume, wait, shutdown)
ase resume

# Oppure: ase start fa resume automatico all'avvio
ase start

Memory & Knowledge Base

ASE impara lavorando. Dopo ogni ticket completato, il Memory Consolidator estrae automaticamente:

• Decisioni architetturali prese
• Gotcha e workaround scoperti
• Pattern e convenzioni osservate
• Quirk delle dipendenze

Queste osservazioni vengono deduplicate e salvate nella knowledge base del progetto. Gli agenti le usano nei ticket successivi per non ripetere errori e rispettare le convenzioni.

Architettura

ase submit "Implementa feature X"
        │
        ▼
  ┌─────────────┐
  │   Intake     │  normalize + create ticket via MCP
  │  Normalizer  │
  └──────┬──────┘
         ▼
  ┌─────────────┐
  │  Analyzer   │  capisce intent, complessità, scope
  │   Agent     │
  └──────┬──────┘
         ▼
  ┌─────────────┐     ┌──────────────┐
  │   Triage    │────▶│ Orchestrator │
  │   Agent     │     │ (task graph) │
  └─────────────┘     └──────┬───────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ Backend  │   │ Testing  │   │  Docs    │
        │  Agent   │   │  Agent   │   │  Agent   │
        └────┬─────┘   └────┬─────┘   └────┬─────┘
             │              │              │
             ▼              ▼              ▼
     ┌─────────────────────────────────────────┐
     │    MCPBridge (tool routing by prefix)    │
     └─────────────┬───────────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼                       ▼
 ┌───────────┐          ┌───────────┐
 │ Operativo │          │  Statico  │
 │  (runtime │          │ (project  │
 │   state)  │          │  context) │
 └─────┬─────┘          └─────┬─────┘
       │                      │
       └──────────┬───────────┘
                  ▼
            ┌──────────┐
            │  SQLite  │
            │  (WAL)   │
            └──────────┘

Struttura Progetto

src/ase/
├── runtime.py              # Connettore centrale — wiring di tutti i componenti
├── cli/main.py             # CLI: init, start, submit, status, metrics, audit, guide, onboard
├── config/                 # TOML loader + Pydantic schema
├── db/                     # SQLite schema + connection factory
├── mcp/
│   ├── process.py          # MCP subprocess launcher (env sandboxing)
│   ├── operativo/          # Server MCP operativo (ticket, eventi, assignment, costi)
│   └── statico/            # Server MCP statico (tech stack, arch, convenzioni, KB)
├── agents/
│   ├── base.py             # Think-loop engine (LLM → tool calls → iterate)
│   ├── bridge.py           # LLM↔MCP bridge (tool routing per prefix)
│   ├── lifecycle.py        # Agent spawning, timeout, cancellazione
│   ├── prompts/            # System prompt per agente
│   └── specialized/        # Implementazioni agenti (11)
├── orchestrator/           # Engine + scheduler + fault tolerance (3 livelli)
├── onboarding/             # Context discovery + completeness check + memory consolidator
├── events/                 # Event bus + handler registry
├── intake/                 # Normalizzazione input + ticket factory
├── llm/                    # litellm client + cost tracking
├── audit/                  # Decision log
├── hil/                    # Human-in-the-loop (review, staging, notifiche)
└── scaffold/               # Scaffolding nuovi progetti

Per chi contribuisce

# Clona e installa in dev mode
git clone https://github.com/AG4MA/agentic_software_engineer.git
cd agentic_software_engineer
pip install -e ".[dev]"

# Test
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/ase/

License

MIT