</details>

<details>
<summary><b>Interazione con l'Agente</b> (clicca per espandere)</summary>```mermaid
sequenceDiagram
    participant O as Orchestrator
    participant R as Researcher
    participant D as Developer
    participant E as Executor
    participant VS as Vector Store
    participant KB as Knowledge Base

    Note over O,KB: Flow Initialization
    O->>VS: Query similar tasks
    VS-->>O: Return experiences
    O->>KB: Load relevant knowledge
    KB-->>O: Return context

    Note over O,R: Research Phase
    O->>R: Analyze target
    R->>VS: Search similar cases
    VS-->>R: Return patterns
    R->>KB: Query vulnerabilities
    KB-->>R: Return known issues
    R->>VS: Store findings
    R-->>O: Research results

    Note over O,D: Planning Phase
    O->>D: Plan attack
    D->>VS: Query exploits
    VS-->>D: Return techniques
    D->>KB: Load tools info
    KB-->>D: Return capabilities
    D-->>O: Attack plan

    Note over O,E: Execution Phase
    O->>E: Execute plan
    E->>KB: Load tool guides
    KB-->>E: Return procedures
    E->>VS: Store results
    E-->>O: Execution status

</details>

<a id="advanced-agent-supervision"></a>
<details>
<summary><b>Supervisione Avanzata degli Agenti</b> (clicca per espandere)</summary>

PentAGI include meccanismi sofisticati di supervisione degli agenti su più livelli per garantire un'esecuzione efficiente delle attività, prevenire cicli infiniti e fornire un recupero intelligente da stati bloccati:

### Monitoraggio dell'Esecuzione (Beta)
- **Intervento Automatico del Mentor**: L'agente consulente (mentor) viene invocato automaticamente quando i modelli di esecuzione indicano potenziali problemi
- **Rilevamento di Pattern**: Monitora chiamate a strumenti identiche (soglia: 5, configurabile) e chiamate totali agli strumenti (soglia: 10, configurabile)
- **Analisi del Progresso**: Valuta se l'agente avanza verso l'obiettivo del sotto-compito, rileva loop e inefficienze
- **Strategie Alternative**: Raccomanda approcci diversi quando la strategia corrente fallisce
- **Guida al Recupero delle Informazioni**: Suggerisce di cercare soluzioni consolidate invece di reinventare
- **Formato di Risposta Migliorato**: Le risposte degli strumenti includono sia sezioni `<original_result>` che `<mentor_analysis>`
- **Configurabile**: Abilita tramite `EXECUTION_MONITOR_ENABLED` (default: false), personalizza le soglie con `EXECUTION_MONITOR_SAME_TOOL_LIMIT` e `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT`

**Ideale per**: Modelli più piccoli (< 32B parametri), scenari di attacco complessi che richiedono guida continua, prevenire che gli agenti si blocchino su un singolo approccio

**Impatto sulle Prestazioni**: Aumento di 2-3x nel tempo di esecuzione e nell'uso di token, ma offre un **miglioramento di 2x nella qualità dei risultati** basato su test con Qwen3.5-27B-FP8

### Pianificazione Intelligente delle Attività (Beta)
- **Decomposizione Automatica**: Il pianificatore (consulente in modalità di pianificazione) genera 3-7 passaggi specifici e attuabili prima che gli agenti specializzati inizino il lavoro
- **Piani Contestuali**: Analizza l'intero contesto di esecuzione tramite l'agente arricchitore per creare piani informati
- **Assegnazione Strutturata**: La richiesta originale è racchiusa in una struttura `<task_assignment>` con piano di esecuzione e istruzioni
- **Gestione dell'Ambito**: Previene lo scope creep mantenendo gli agenti focalizzati solo sul sotto-compito corrente
- **Istruzioni Arricchite**: I piani evidenziano azioni critiche, potenziali insidie e punti di verifica
- **Configurabile**: Abilita tramite `AGENT_PLANNING_STEP_ENABLED` (default: false)

**Ideale per**: Modelli < 32B parametri, flussi di lavoro di penetration testing complessi, miglioramento dei tassi di successo in attività sofisticate

**Configurazione Migliorata del Consulente**: Funziona eccezionalmente bene quando l'agente consulente utilizza un modello più potente o impostazioni potenziate. Esempio: utilizzare lo stesso modello base con modalità di ragionamento massima per il consulente (vedi [`vllm-qwen3.5-27b-fp8.provider.yml`](https://github.com/vxcontrol/pentagi/blob/HEAD/examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)) consente un'analisi completa delle attività e una pianificazione strategica dalla stessa architettura del modello.

**Impatto sulle Prestazioni**: Aggiunge overhead di pianificazione ma migliora significativamente i tassi di completamento e riduce il lavoro ridondante

### Limiti delle Chiamate agli Strumenti (Sempre Attivi)
- **Limiti Rigidi**: Prevengono esecuzioni incontrollate indipendentemente dallo stato della modalità di supervisione
- **Differenziati per Tipo di Agente**:
  - Agenti generali (Assistente, Agente Primario, Pentester, Coder, Installer): `MAX_GENERAL_AGENT_TOOL_CALLS` (default: 100)
  - Agenti limitati (Searcher, Enricher, Memorist, Generator, Reporter, Adviser, Reflector, Planner): `MAX_LIMITED_AGENT_TOOL_CALLS` (default: 20)
- **Terminazione Graduale**: Il Reflector guida gli agenti verso un completamento appropriato quando ci si avvicina ai limiti
- **Protezione delle Risorse**: Garantisce la stabilità del sistema e previene l'esaurimento delle risorse

### Integrazione del Reflector (Sempre Attiva)
- **Correzione Automatica**: Invocata quando l'LLM non riesce a generare chiamate a strumenti dopo 3 tentativi
- **Guida Strategica**: Analizza i fallimenti e guida gli agenti verso un uso corretto degli strumenti o strumenti barriera (`done`, `ask`)
- **Meccanismo di Recupero**: Fornisce guida contestuale basata su modelli di fallimento specifici
- **Applicazione dei Limiti**: Coordina la terminazione graduale quando vengono raggiunti i limiti di chiamata agli strumenti

### Raccomandazioni per Modelli Open Source

**Indispensabile per Modelli < 32B Parametri**:
I test con Qwen3.5-27B-FP8 dimostrano che abilitare sia il Monitoraggio dell'Esecuzione che la Pianificazione delle Attività è **essenziale** per i modelli open source più piccoli:
- **Miglioramento della Qualità**: Risultati 2x migliori rispetto all'esecuzione di base senza supervisione
- **Prevenzione dei Loop**: Riduce significativamente cicli infiniti e lavoro ridondante
- **Diversità degli Attacchi**: Incoraggia l'esplorazione di molteplici vettori di attacco invece di fissarsi su un singolo approccio
- **Deploy in Ambienti Isolati**: Consente penetration testing autonomo di livello produttivo in ambienti di rete chiusi con inferenza LLM locale

**Compromessi**:
- Consumo di token: aumento di 2-3x a causa delle invocazioni del mentor/pianificatore
- Tempo di esecuzione: 2-3x più lungo a causa dei passaggi di analisi e pianificazione
- Qualità dei risultati: miglioramento di 2x in completezza, accuratezza e copertura degli attacchi
- Requisiti del modello: Funziona meglio quando il consulente utilizza una configurazione potenziata (parametri di ragionamento più elevati, variante di modello più forte o modello diverso)

**Strategia di Configurazione**:
Per prestazioni ottimali con modelli più piccoli, configura l'agente consulente con impostazioni potenziate:
- Utilizza lo stesso modello con modalità di ragionamento massima (esempio: [`vllm-qwen3.5-27b-fp8.provider.yml`](https://github.com/vxcontrol/pentagi/blob/HEAD/examples/configs/vllm-qwen3.5-27b-fp8.provider.yml))
- Oppure utilizza un modello più forte per il consulente mantenendo il modello base per gli altri agenti
- Regola le soglie di monitoraggio in base alla complessità delle attività e alle capacità del modello



</details>

L'architettura di PentAGI è progettata per essere modulare, scalabile e sicura. Ecco i componenti chiave:

1. **Servizi Core**
   - Interfaccia utente Frontend: Interfaccia web basata su React con TypeScript per la sicurezza dei tipi
   - Backend API: API REST e GraphQL in Go con autenticazione tramite Bearer token per accesso programmatico
   - Vector Store: PostgreSQL con pgvector per ricerca semantica e archiviazione della memoria
   - Coda di Attività: Sistema di elaborazione asincrono delle attività per un funzionamento affidabile
   - Agente AI: Sistema multi-agente con ruoli specializzati per test efficienti

2. **Grafo della Conoscenza**
   - Graphiti: API del grafo della conoscenza per il tracciamento delle relazioni semantiche e la comprensione contestuale
   - Neo4j: Database a grafo per archiviare e interrogare relazioni tra entità, azioni e risultati
   - Cattura automatica delle risposte degli agenti e delle esecuzioni degli strumenti per costruire una base di conoscenza completa

3. **Stack di Monitoraggio**
   - OpenTelemetry: Raccolta e correlazione unificata dei dati di osservabilità
   - Grafana: Dashboard di visualizzazione e alerting in tempo reale
   - VictoriaMetrics: Archiviazione di metriche time-series ad alte prestazioni
   - Jaeger: Tracciamento distribuito end-to-end per il debug
   - Loki: Aggregazione e analisi dei log scalabile

4. **Piattaforma di Analisi**
   - Langfuse: Osservabilità avanzata degli LLM e analisi delle prestazioni
   - ClickHouse: Data warehouse analitico orientato alle colonne
   - Redis: Caching ad alta velocità e limitazione della frequenza
   - MinIO: Archiviazione di oggetti compatibile con S3 per artefatti

5. **Strumenti di Sicurezza**
   - Web Scraper: Ambiente browser isolato per un'interazione web sicura
   - Strumenti di Penetration Testing: Suite completa di oltre 20 strumenti di sicurezza professionali
   - Esecuzione in Sandbox: Tutte le operazioni vengono eseguite in container isolati

6. **Sistemi di Memoria**
   - Memoria a Lungo Termine: Archiviazione persistente di conoscenze ed esperienze
   - Memoria di Lavoro: Contesto e obiettivi attivi per le operazioni correnti
   - Memoria Episodica: Azioni storiche e pattern di successo
   - Base di Conoscenza: Competenza di dominio strutturata e capacità degli strumenti
   - Gestione del Contesto: Gestisce intelligentemente i contesti crescenti degli LLM utilizzando il riepilogo a catena

Il sistema utilizza container Docker per l'isolamento e la facile distribuzione, con reti separate per servizi core, monitoraggio e analisi per garantire adeguati confini di sicurezza. Ogni componente è progettato per scalare orizzontalmente e può essere configurato per l'alta disponibilità in ambienti di produzione.

## Avvio Rapido

### Requisiti di Sistema

- Docker e Docker Compose (o Podman - vedere [Configurazione Podman](#esecuzione-di-pentagi-con-podman))
- Minimo 2 vCPU
- Minimo 4GB RAM
- 20GB di spazio libero su disco
- Accesso a Internet per scaricare immagini e aggiornamenti

### Utilizzo dell'Installer (Consigliato)

PentAGI fornisce un installer interattivo con un'interfaccia utente basata sul terminale per una configurazione e distribuzione semplificata. L'installer ti guida attraverso controlli di sistema, configurazione del provider LLM, configurazione del motore di ricerca e hardening della sicurezza.

**Piattaforme Supportate:**
- **Linux**: amd64 [download](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [download](https://pentagi.com/downloads/linux/arm64/installer-latest.zip)
- **Windows**: amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip)
- **macOS**: amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (serie M) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip)

**Installazione Rapida (Linux amd64):**```bash
# Create installation directory
mkdir -p pentagi && cd pentagi

# Download installer
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip

# Extract
unzip installer.zip

# Run interactive installer
./installer

mkdir -p /opt/pentagi
cd /opt/pentagi
git clone https://github.com/your-repo/pentagi.git .
``````bash
mkdir pentagi && cd pentagi

3. Toccare i file di esempio (`example.custom.provider.yml`, `example.ollama.provider.yml`) o scaricarli:```bash
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml

5. Cambia tutte le variabili d'ambiente relative alla sicurezza nel file `.env` per migliorare la sicurezza.

<details>
    <summary>Variabili d'ambiente relative alla sicurezza</summary>

### Impostazioni principali di sicurezza
- `COOKIE_SIGNING_SALT` - Sale per la firma dei cookie, cambia con un valore casuale
- `PUBLIC_URL` - URL pubblico del tuo server (es. `https://pentagi.example.com`)
- `SERVER_SSL_CRT` e `SERVER_SSL_KEY` - Percorsi personalizzati per il tuo certificato SSL e chiave esistenti per HTTPS (questi percorsi dovrebbero essere usati nel file docker-compose.yml per essere montati come volumi)

### Accesso allo Scraper
- `SCRAPER_PUBLIC_URL` - URL pubblico per lo scraper se si desidera utilizzare un server scraper diverso per URL pubblici
- `SCRAPER_PRIVATE_URL` - URL privato per lo scraper (server scraper locale nel file docker-compose.yml per accedere a URL locali)

### Credenziali di accesso
- `PENTAGI_POSTGRES_USER` e `PENTAGI_POSTGRES_PASSWORD` - Credenziali PostgreSQL
- `NEO4J_USER` e `NEO4J_PASSWORD` - Credenziali Neo4j (per il grafo della conoscenza Graphiti)

</details>

6. Rimuovi tutti i commenti inline dal file `.env` se desideri usarlo in VSCode o altri IDE come opzione envFile:```bash
perl -i -pe 's/\s+#.*$//' .env

Visita [localhost:8443](https://localhost:8443) per accedere all'interfaccia web di PentAGI (le credenziali predefinite sono `[email protected]` / `admin`)

#### Account dell'interfaccia web

PentAGI non espone una registrazione self-service pubblica dalla pagina di login. Una nuova installazione crea l'account amministratore locale predefinito:

- **Email**: `[email protected]`
- **Password**: `admin`

Al primo accesso, cambia la password predefinita prima di utilizzare l'istanza per lavoro reale. Se la password dell'amministratore viene successivamente persa, utilizza il menu di manutenzione dell'installer per reimpostare la password dell'account predefinito `[email protected]`.

Per configurazioni multiutente, un amministratore autenticato può gestire gli utenti locali tramite l'API REST degli utenti (`/api/v1/users/`). L'interfaccia OpenAPI è disponibile all'indirizzo `https://localhost:8443/api/v1/swagger/index.html` dopo che l'istanza è in esecuzione.

> [!NOTE]
> Se hai riscontrato un errore riguardante `pentagi-network` o `observability-network` o `langfuse-network` devi eseguire prima `docker-compose.yml` per creare queste reti e successivamente eseguire `docker-compose-langfuse.yml`, `docker-compose-graphiti.yml`, e `docker-compose-observability.yml` per utilizzare i servizi Langfuse, Graphiti e Observability.
>
> Devi impostare almeno un provider di Language Model (OpenAI, Anthropic, Gemini, AWS Bedrock o Ollama) per utilizzare PentAGI. AWS Bedrock fornisce accesso di livello enterprise a molteplici modelli fondamentali delle principali aziende di AI, mentre Ollama offre inferenza locale a costo zero se disponi di risorse computazionali sufficienti. Chiavi API aggiuntive per i motori di ricerca sono opzionali ma raccomandate per risultati migliori.
>
> **Per una distribuzione completamente locale con modelli avanzati**: Consulta la nostra guida completa su [Esecuzione di PentAGI con vLLM e Qwen3.5-27B-FP8](https://github.com/vxcontrol/pentagi/blob/HEAD/examples/guides/vllm-qwen35-27b-fp8.md) per una configurazione LLM locale di livello produttivo. Questa configurazione raggiunge ~13.000 TPS per l'elaborazione del prompt e ~650 TPS per il completamento su 4× GPU RTX 5090, supportando 12+ flussi concorrenti con completa indipendenza dai provider cloud.
>
> Le variabili d'ambiente `LLM_SERVER_*` sono una funzionalità sperimentale e verranno modificate in futuro. Al momento puoi usarle per specificare un URL del server LLM personalizzato e un modello per tutti i tipi di agente.
>
> `PROXY_URL` è un URL proxy globale per tutti i provider LLM e i sistemi di ricerca esterni. Puoi usarlo per l'isolamento dalle reti esterne.
>
> Il file `docker-compose.yml` esegue il servizio PentAGI come utente root perché necessita dell'accesso a docker.sock per la gestione dei container. Se utilizzi una connessione di rete TCP/IP a Docker invece del file socket, puoi rimuovere i privilegi di root e utilizzare l'utente predefinito `pentagi` per una maggiore sicurezza.

### Accesso a PentAGI da reti esterne

Per impostazione predefinita, PentAGI si lega a `127.0.0.1` (solo localhost) per sicurezza. Per accedere a PentAGI da altre macchine sulla tua rete, devi configurare l'accesso esterno.

#### Passaggi di configurazione

1. **Aggiorna il file `.env`** con l'indirizzo IP del tuo server:```bash
# Network binding - allow external connections
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443

# Public URL - use your actual server IP or hostname
# Replace 192.168.1.100 with your server's IP address
PUBLIC_URL=https://192.168.1.100:8443

# CORS origins - list all URLs that will access PentAGI
# Include localhost for local access AND your server IP for external access
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443

3. **Verifica il binding della porta:**```bash
docker ps | grep pentagi

Poi ricrea i container di nuovo.

4. **Configura il firewall** per consentire le connessioni in entrata sulla porta 8443:```bash
# Ubuntu/Debian with UFW
sudo ufw allow 8443/tcp
sudo ufw reload

# CentOS/RHEL with firewalld
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

**2. Aggiorna il file `.env`** - modifica l'URL dello scraper per usare HTTP e porta 3000:```bash
# Scraper configuration for Podman rootless
SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/
LOCAL_SCRAPER_USERNAME=someuser
LOCAL_SCRAPER_PASSWORD=somepass

**4. Testa la connettività dello scraper:**```bash
# Test from within the pentagi container
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"

Solo i sistemi di tua proprietà o per i quali hai esplicita autorizzazione devono essere testati. Consulta [EULA.md](https://github.com/vxcontrol/pentagi/blob/HEAD/EULA.md) per i termini di utilizzo accettabili.

### 2. Usa modelli per flussi di lavoro ripetibili

Il nuovo modulo del flusso include un selettore di modelli, che può precompilare la casella di messaggio con un modello di flusso salvato. Ciò è utile quando esegui valutazioni simili ripetutamente.

- Usa un modello esistente se ne hai già uno salvato in **Modelli**
- Inizia dall'esempio di prompt in [`examples/prompts/base_web_pentest.md`](https://github.com/vxcontrol/pentagi/blob/HEAD/examples/prompts/base_web_pentest.md) se hai bisogno di una base pratica per i test web
- Regola il target, l'ambito e i vincoli prima di avviare il flusso

I modelli sono punti di partenza. Non è necessaria una sintassi speciale per usare PentAGI: le istruzioni in linguaggio naturale semplice funzionano bene purché target e obiettivo siano chiari.

### 3. Monitora l'esecuzione e rivedi l'output

Dopo aver inviato il flusso, PentAGI apre automaticamente la pagina del flusso.

- Usa la vista principale del flusso per seguire i messaggi, l'attività degli agenti e l'avanzamento delle attività
- Ispeziona l'attività degli strumenti e l'output del terminale durante l'esecuzione del flusso
- Rivedi le attività e sottoattività generate per capire cosa sta facendo PentAGI

Una volta che il flusso ha risultati sufficienti, usa il menu **Report** nella pagina del flusso per:

- aprire il report in una vista web
- copiare il report generato negli appunti
- scaricare il report come Markdown
- scaricare il report come PDF

### 4. Usa la vista Assistente per guidare un flusso attivo

Ogni flusso include anche una vista **Assistente** per una guida interattiva. Ciò è utile quando l'esecuzione autonoma scopre qualcosa che necessita di direzione umana anziché un riavvio brusco.

- Apri la vista **Assistente** per lo stesso flusso quando vuoi ispezionare lo stato corrente prima di modificare qualcosa.
- Usa l'assistente per controllare lo stato del flusso, interrompere l'attività corrente, inviare istruzioni di follow-up o modificare le sottoattività pianificate rimanenti prima del passaggio successivo.
- Tratta questo come un percorso di controllo esplicito per il flusso corrente, non come una coda di background invisibile. Se vuoi cambiare direzione, dillo chiaramente e mantieni la nuova istruzione legata all'ambito di coinvolgimento corrente.
- Funziona meglio per chiarire l'ambito, reindirizzare le priorità dopo risultati intermedi o rispondere a un checkpoint di automazione senza perdere il resto del contesto del flusso.

### 5. Gestisci i file con ambito del flusso

Ogni flusso ha la propria scheda **File** nella pagina del flusso. I file hanno ambito del flusso padre: risiedono in `{dataDir}/flow-{id}-data/` sull'host e non si propagano mai in altri flussi.

La scheda espone tre origini di file:

- **Caricamenti** (`uploads/`): file che fornisci dall'interfaccia web. Usa l'azione **Carica file** o trascina e rilascia direttamente sulla scheda File. Mentre il contenitore dell'agente è in esecuzione, i file caricati vengono anche spinti al suo interno in `/work/uploads/` in modo che l'agente possa leggerli con normali strumenti shell.
- **Risorse** (`resources/`): file allegati dalla tua libreria di risorse utente salvate tramite **Allega risorse dalla libreria**. Le risorse allegate vengono copiate nel flusso e spinte nel contenitore in esecuzione in `/work/resources/`.
- **Contenitore** (`container/`): snapshot prelevati dal contenitore dell'agente in esecuzione tramite **Preleva file o directory dal contenitore**. Questi sono di sola lettura sul lato flusso e non vengono mai rimandati al contenitore.

Le azioni per singolo file nella scheda File includono **Scarica**, **Copia percorso**, **Salva come risorsa** (promuove un file del flusso nella libreria di risorse riutilizzabili) ed **Elimina**. L'azione di prelievo è disabilitata quando il contenitore non è in esecuzione, con il tooltip "Il contenitore non è in esecuzione".

I file caricati e le risorse allegate vengono elencati automaticamente nei prompt di sistema dell'agente tramite la variabile di template `{{.UserFiles}}`, che renderizza un blocco XML compatto `<task_files>` (con sezioni `<uploads>` e `<resources>` annidate), in modo che l'assistente e gli agenti di automazione possano farvi riferimento per percorso senza che tu incolli i contenuti nella chat. Gli snapshot del contenitore sono visibili solo nell'interfaccia utente e non vengono reiniettati automaticamente nel prompt.

Limiti e limitazioni attuali da tenere presenti:

- La dimensione massima del file caricato è 300 MB; per richiesta di caricamento fino a 1000 file e 2 GB totali. I nomi dei file sono limitati a 255 byte (circa 255 caratteri ASCII; i nomi non ASCII usano più byte per carattere).
- I caricamenti e le risorse vengono rispecchiati nel contenitore in esecuzione nei percorsi fissi `/work/uploads/` e `/work/resources/`; i file scritti in altri percorsi del contenitore non vengono automaticamente rispecchiati nel modello di file del flusso. Gli snapshot del contenitore possono provenire da qualsiasi percorso del contenitore che prelevi (ad esempio `/etc/...`) e vengono memorizzati nella cache sul lato flusso sotto `container/`; non vengono rispediti nel contenitore.
- Gli snapshot del contenitore sono prelievi istantanei. Modificare uno snapshot nell'interfaccia utente non lo riscrive nel contenitore in esecuzione.
- Eliminare un flusso oggi rimuove il record del flusso e le sue voci di memoria a lungo termine, ma non archivia né rimuove ancora la directory `flow-{id}-data/` del flusso sul disco. Ci si aspetta ancora che gli operatori puliscano manualmente la directory dei dati se vogliono recuperare spazio.

Per i test iniziali, inizia con un target ristretto e un singolo obiettivo chiaro. Ciò rende l'output più facile da rivedere e ti aiuta a perfezionare i tuoi prompt prima di eseguire valutazioni più grandi.

## Accesso API

PentAGI fornisce un accesso programmatico completo tramite API REST e GraphQL, consentendoti di integrare i flussi di lavoro di penetration testing nelle tue pipeline di automazione, processi CI/CD e applicazioni personalizzate.

### Generazione di token API

I token API sono gestiti tramite l'interfaccia web di PentAGI:

1. Vai su **Impostazioni** → **Token API** nell'interfaccia web
2. Clicca su **Crea Token** per generare un nuovo token API
3. Configura le proprietà del token:
   - **Nome** (opzionale): Un nome descrittivo per il token
   - **Data di scadenza**: Quando il token scadrà (minimo 1 minuto, massimo 3 anni)
4. Clicca su **Crea** e **copia immediatamente il token** - verrà mostrato una sola volta per motivi di sicurezza
5. Usa il token come token Bearer nelle tue richieste API

Ogni token è associato al tuo account utente e eredita i permessi del tuo ruolo.

### Utilizzo dei token API

Includi il token API nell'intestazione `Authorization` delle tue richieste HTTP:```bash
# GraphQL API example
curl -X POST https://your-pentagi-instance:8443/api/v1/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ flows { id title status } }"}'

# REST API example
curl https://your-pentagi-instance:8443/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_TOKEN"

**Configurazione del livello a pagamento (Multi-modello con configurazione predefinita)**

Per i livelli a pagamento che supportano più modelli concorrenti, utilizzare la configurazione predefinita di Ollama Cloud:```bash
# Using pre-built Ollama Cloud configuration (included in Docker image)
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-cloud.provider.yml

La variabile d'ambiente `PENTAGI_OLLAMA_SERVER_CONFIG_PATH` mappa il file di configurazione dell'host a `/opt/pentagi/conf/ollama.provider.yml` all'interno del container.

**Esempio di configurazione personalizzata** (`my-ollama-config.yml`):```yaml
primary_agent:
  model: "qwen3-coder-next:cloud"
  temperature: 1.0
  top_p: 0.9
  max_tokens: 32768
  reasoning:
    effort: high

coder:
  model: "qwen3-coder:32b"
  temperature: 1.0
  max_tokens: 20480

**Considerazioni sulle Prestazioni:**

- **Scoperta dei Modelli** (`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`): Aggiunge 1-2 secondi di latenza all'avvio per interrogare l'API di Ollama
- **Download Automatico** (`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`): Il primo avvio potrebbe richiedere diversi minuti per scaricare i modelli
- **Timeout di Download** (`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`): 15 minuti in secondi
- **Configurazione Static**: Disabilita entrambi i flag e specifica i modelli nel file di configurazione per un avvio più rapido

#### Creazione di Modelli Ollama Personalizzati con Contesto Esteso

PentAGI richiede modelli con finestre di contesto più ampie rispetto alle configurazioni predefinite di Ollama. Devi creare modelli personalizzati con un parametro `num_ctx` aumentato tramite Modelfiles. Mentre i flussi di lavoro tipici degli agenti consumano circa 64K token, PentAGI utilizza una dimensione di contesto di 110K per un margine di sicurezza e per gestire scenari complessi di test di penetrazione.

**Importante**: Il parametro `num_ctx` può essere impostato solo durante la creazione del modello tramite Modelfile - non può essere modificato dopo la creazione del modello o sovrascritto in fase di esecuzione.

##### Esempio: Qwen3 32B FP16 con Contesto Esteso

Crea un Modelfile denominato `Modelfile_qwen3_32b_fp16_tc`:```dockerfile
FROM qwen3:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.3
PARAMETER top_p 0.8
PARAMETER min_p 0.0
PARAMETER top_k 20
PARAMETER repeat_penalty 1.1

##### Esempio: QwQ 32B FP16 with Extended Context

Crea un Modelfile chiamato `Modelfile_qwq_32b_fp16_tc`:```dockerfile
FROM qwq:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.2
PARAMETER top_p 0.7
PARAMETER min_p 0.0
PARAMETER top_k 40
PARAMETER repeat_penalty 1.2

> **Nota**: Il modello QwQ 32B FP16 richiede circa **71.3 GB VRAM** per l'inferenza. Assicurati che il tuo sistema abbia sufficiente memoria GPU prima di tentare di utilizzare questo modello.

Questi modelli personalizzati sono referenziati nei file di configurazione del provider predefiniti (`ollama-qwen332b-fp16-tc.provider.yml` e `ollama-qwq32b-fp16-tc.provider.yml`) che sono inclusi nell'immagine Docker in `/opt/pentagi/conf/`.

### Configurazione del Provider OpenAI

PentAGI si integra con la lineup completa di modelli di OpenAI, offrendo capacità di ragionamento avanzate con chain-of-thought esteso, modelli agentici con integrazione potenziata degli strumenti e modelli di codice specializzati per l'ingegneria della sicurezza.

#### Variabili di Configurazione

| Variabile             | Predefinito                 | Descrizione                 |
| -------------------- | --------------------------- | --------------------------- |
| `OPEN_AI_KEY`        |                             | Chiave API per i servizi OpenAI |
| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | Endpoint API di OpenAI         |

#### Esempi di Configurazione```bash
# Basic OpenAI setup
OPEN_AI_KEY=your_openai_api_key
OPEN_AI_SERVER_URL=https://api.openai.com/v1

# Using with proxy for enhanced security
OPEN_AI_KEY=your_openai_api_key
PROXY_URL=http://your-proxy:8080

> [!NOTE]
> **Google Vertex AI per i modelli Claude**
>
> PentAGI al momento non espone un percorso di configurazione dedicato per Google Vertex AI per Anthropic Claude in `.env`. Non esiste ancora un campo separato per la chiave API di Vertex AI, e le variabili Anthropic esistenti (`ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL`) puntano all'API Anthropic diretta. Le route supportate per Claude sono:
>
> - **API Anthropic diretta**: `ANTHROPIC_API_KEY` e `ANTHROPIC_SERVER_URL` (vedi sopra).
> - **AWS Bedrock**: variabili `BEDROCK_*` (vedi [Configurazione del provider AWS Bedrock](#aws-bedrock-provider-configuration)).
>
> Se hai bisogno di usare Vertex AI oggi, la soluzione alternativa supportata più sicura è esporre Vertex AI attraverso un proxy o gateway compatibile con OpenAI che traduce le chiamate Vertex AI nel formato Chat Completions preservando il comportamento di chat e tool-call su cui PentAGI si basa, quindi puntare il provider LLM personalizzato a quel gateway tramite `LLM_SERVER_URL`, `LLM_SERVER_KEY` e `LLM_SERVER_MODEL`. Questo percorso è affidabile solo quanto il gateway scelto.

#### Modelli Supportati

PentAGI supporta 10 modelli Claude con chiamata di strumenti, streaming, pensiero esteso, pensiero adattivo e caching dei prompt. I modelli contrassegnati con `*` sono utilizzati nella configurazione predefinita.

**Serie Claude 4 - Modelli più recenti (2025-2026)**

| ID Modello             | Pensiero | Data di rilascio | Prezzo (Input/Output/Cache L/S) | Casi d'uso                                      |
| ---------------------- | -------- | ---------------- | ------------------------------- | ----------------------------------------------- |
| `claude-opus-4-6`*     | ✅        | Maggio 2025      | $5.00/$25.00/$0.50/$6.25        | Modello più intelligente per agenti autonomi e codifica. Pensiero esteso + adattivo per sviluppo di exploit complessi, simulazione di attacchi multi-stadio |
| `claude-sonnet-4-6`*   | ✅        | Agosto 2025      | $3.00/$15.00/$0.30/$3.75        | Miglior equilibrio velocità/intelligenza con pensiero adattivo. Valutazioni di sicurezza multi-fase, analisi intelligente delle vulnerabilità, caccia alle minacce in tempo reale |
| `claude-haiku-4-5`*    | ✅        | Ottobre 2025     | $1.00/$5.00/$0.10/$1.25         | Modello più veloce con intelligenza quasi di frontiera. Scansione ad alta frequenza, monitoraggio in tempo reale, test automatizzati in blocco |

**Modelli Legacy - Ancora Supportati**

| ID Modello             | Pensiero | Data di rilascio | Prezzo (Input/Output/Cache L/S) | Casi d'uso                                      |
| ---------------------- | -------- | ---------------- | ------------------------------- | ----------------------------------------------- |
| `claude-sonnet-4-5`    | ✅        | Settembre 2025   | $3.00/$15.00/$0.30/$3.75        | Ragionamento all'avanguardia (sostituito da 4-6). Penetration testing sofisticato, analisi avanzata delle minacce |
| `claude-opus-4-5`      | ✅        | Novembre 2025    | $5.00/$25.00/$0.50/$6.25        | Ragionamento ultimo (sostituito da opus-4-6). Ricerca critica sulla sicurezza, scoperta di zero-day, operazioni red team |
| `claude-opus-4-1`      | ✅        | Agosto 2025      | $15.00/$75.00/$1.50/$18.75      | Ragionamento avanzato (sostituito). Penetration testing complesso, modellazione sofisticata delle minacce |
| `claude-sonnet-4-0`    | ✅        | Maggio 2025      | $3.00/$15.00/$0.30/$3.75        | Ragionamento ad alte prestazioni (sostituito). Modellazione complessa delle minacce, coordinamento multi-strumento |
| `claude-opus-4-0`      | ✅        | Maggio 2025      | $15.00/$75.00/$1.50/$18.75      | Prima generazione Opus (sostituito). Sviluppo di exploit multi-step, flussi di lavoro di pentesting autonomi |

**Modelli Deprecati - Migrare ai Modelli Correnti**

| ID Modello                   | Pensiero | Data di rilascio | Prezzo (Input/Output/Cache L/S) | Note                                         |
| ---------------------------- | -------- | ---------------- | ------------------------------- | --------------------------------------------- |
| `claude-3-haiku-20240307`    | ❌        | Marzo 2024       | $0.25/$1.25/$0.03/$0.30         | Sarà ritirato il 19 aprile 2026. Migrare a claude-haiku-4-5 |

**Prezzi**: Per 1M token. Il prezzo della cache include sia i costi di Lettura che di Scrittura.

**Configurazione del Pensiero Esteso**:
- **Max Tokens 4096**: Generatore (claude-opus-4-6) per massima profondità di ragionamento su sviluppo di exploit complessi
- **Max Tokens 2048**: Codificatore (claude-sonnet-4-6) per analisi del codice bilanciata e ricerca di vulnerabilità  
- **Max Tokens 1024**: Agente primario, assistente, affinatore, consulente, riflettore, cercatore, installatore, pentester per ragionamento focalizzato su compiti specifici
- **Pensiero Esteso**: Tutti i modelli Claude 4.5+ e 4.6 supportano il pensiero esteso configurabile per compiti di ragionamento profondo

**Caratteristiche Principali**:
- **Pensiero Esteso**: Tutti i modelli Claude 4.5+ e 4.6 con profondità di ragionamento chain-of-thought configurabili per analisi di sicurezza complesse
- **Pensiero Adattivo**: La serie Claude 4.6 (Opus/Sonnet) regola dinamicamente la profondità di ragionamento in base alla complessità del compito per prestazioni ottimali
- **Caching dei Prompt**: Riduzione significativa dei costi con prezzi separati di lettura/scrittura (10% lettura, 125% scrittura dell'input)
- **Finestra di Contesto Estesa**: 200K token standard, fino a 1M token (beta) per Claude Opus/Sonnet 4.6 per analisi completa del codebase
- **Chiamata di Strumenti**: Chiamata di funzioni robusta con eccezionale accuratezza per l'orchestrazione di strumenti di sicurezza
- **Streaming**: Streaming di risposte in tempo reale per flussi di lavoro di penetration testing interattivi
- **Design Safety-First**: Meccanismi di sicurezza integrati che garantiscono pratiche di test di sicurezza responsabili
- **Supporto Multimodale**: Capacità di visione nei modelli più recenti per analisi di screenshot e valutazione della sicurezza dell'interfaccia utente
- **AI Costituzionale**: Formazione sulla sicurezza avanzata che fornisce una guida alla sicurezza affidabile ed etica

### Configurazione del Provider Google AI (Gemini)

PentAGI si integra con i modelli Gemini di Google tramite l'API Google AI, offrendo capacità di ragionamento multimodale all'avanguardia con pensiero esteso e caching del contesto.

#### Variabili di Configurazione

| Variabile           | Default                                     | Descrizione                    |
| ------------------- | ------------------------------------------- | ------------------------------ |
| `GEMINI_API_KEY`    |                                             | Chiave API per i servizi Google AI |
| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Endpoint API Google AI         |

#### Esempi di Configurazione```bash
# Basic Gemini setup
GEMINI_API_KEY=your_gemini_api_key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com

# Using with proxy
GEMINI_API_KEY=your_gemini_api_key
PROXY_URL=http://your-proxy:8080

#### Modelli Supportati

PentAGI supporta 21 modelli AWS Bedrock con capacità di tool calling, streaming e multimodalità. I modelli contrassegnati con `*` sono utilizzati nella configurazione predefinita.

| Model ID                                         | Provider        | Pensiero | Multimodale | Prezzo (Input/Output) | Caso d'Uso                               |
| ------------------------------------------------ | --------------- | -------- | ----------- | -------------------- | --------------------------------------- |
| `us.amazon.nova-2-lite-v1:0`                     | Amazon Nova     | ❌        | ✅          | $0.33/$2.75          | Ragionamento adattivo, pensiero efficiente |
| `us.amazon.nova-premier-v1:0`                    | Amazon Nova     | ❌        | ✅          | $2.50/$12.50         | Ragionamento complesso, analisi avanzata |
| `us.amazon.nova-pro-v1:0`                        | Amazon Nova     | ❌        | ✅          | $0.80/$3.20          | Accuratezza, velocità e costo bilanciati |
| `us.amazon.nova-lite-v1:0`                       | Amazon Nova     | ❌        | ✅          | $0.06/$0.24          | Elaborazione veloce, operazioni ad alto volume |
| `us.amazon.nova-micro-v1:0`                      | Amazon Nova     | ❌        | ❌          | $0.035/$0.14         | Latenza ultra-bassa, monitoraggio in tempo reale |
| `us.anthropic.claude-opus-4-6-v1`*               | Anthropic       | ✅        | ✅          | $5.00/$25.00         | Codifica di livello mondiale, agenti enterprise |
| `us.anthropic.claude-sonnet-4-6`                 | Anthropic       | ✅        | ✅          | $3.00/$15.00         | Intelligenza di frontiera, scala enterprise |
| `us.anthropic.claude-opus-4-5-20251101-v1:0`     | Anthropic       | ✅        | ✅          | $5.00/$25.00         | Sviluppo software multi-giorno          |
| `us.anthropic.claude-haiku-4-5-20251001-v1:0`*   | Anthropic       | ✅        | ✅          | $1.00/$5.00          | Prestazioni quasi di frontiera, alta velocità |
| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`*  | Anthropic       | ✅        | ✅          | $3.00/$15.00         | Agenti per il mondo reale, eccellenza nella codifica |
| `us.anthropic.claude-sonnet-4-20250514-v1:0`     | Anthropic       | ✅        | ✅          | $3.00/$15.00         | Prestazioni bilanciate, pronto per la produzione |
| `us.anthropic.claude-3-5-haiku-20241022-v1:0`    | Anthropic       | ❌        | ❌          | $0.80/$4.00          | Modello più veloce, scansione economica  |
| `cohere.command-r-plus-v1:0`                     | Cohere          | ❌        | ❌          | $3.00/$15.00         | Operazioni su larga scala, RAG superiore |
| `deepseek.v3.2`                                  | DeepSeek        | ❌        | ❌          | $0.58/$1.68          | Ragionamento a contesto lungo, efficienza |
| `openai.gpt-oss-120b-1:0`*                       | OpenAI (OSS)    | ✅        | ❌          | $0.15/$0.60          | Forte ragionamento, analisi scientifica   |
| `openai.gpt-oss-20b-1:0`                         | OpenAI (OSS)    | ✅        | ❌          | $0.07/$0.30          | Codifica efficiente, sviluppo software  |
| `qwen.qwen3-next-80b-a3b`                        | Qwen            | ❌        | ❌          | $0.15/$1.20          | Contesto ultra-lungo, ragionamento di riferimento |
| `qwen.qwen3-32b-v1:0`                            | Qwen            | ❌        | ❌          | $0.15/$0.60          | Ragionamento bilanciato, casi d'uso di ricerca |
| `qwen.qwen3-coder-30b-a3b-v1:0`                  | Qwen            | ❌        | ❌          | $0.15/$0.60          | Codifica su vibe, linguaggio naturale prima di tutto |
| `qwen.qwen3-coder-next`                          | Qwen            | ❌        | ❌          | $0.45/$1.80          | Uso di strumenti, chiamate di funzione ottimizzate |
| `mistral.mistral-large-3-675b-instruct`          | Mistral         | ❌        | ✅          | $4.00/$12.00         | Multimodalità avanzata, contesto lungo       |
| `moonshotai.kimi-k2.5`                           | Moonshot        | ❌        | ✅          | $0.60/$3.00          | Visione, linguaggio, codice in un unico modello |

**Prezzi**: Per 1M token. I modelli con pensiero/ragionamento supportano costi di calcolo aggiuntivi durante la fase di ragionamento.

#### Modelli Testati ma Incompatibili

Alcuni modelli AWS Bedrock sono stati testati ma **non sono supportati** a causa di limitazioni tecniche:

| Famiglia di Modelli          | Motivo dell'Incompatibilità                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| **GLM (Z.AI)**            | Formato di chiamata dello strumento incompatibile con Converse API (prevede stringa invece di JSON) |
| **AI21 Jamba**            | Limiti di velocità severi (1-2 richieste/min) impediscono test affidabili e uso in produzione |
| **Meta Llama 3.3/3.1**    | Elaborazione instabile dei risultati delle chiamate agli strumenti, causa errori imprevisti nei flussi di lavoro multi-turno |
| **Mistral Magistral**     | Chiamata agli strumenti non supportata dal modello |
| **Moonshot K2-Thinking**  | Comportamento di streaming instabile con chiamate agli strumenti, inaffidabile in produzione |
| **Qwen3-VL**              | Streaming instabile con chiamata agli strumenti, la combinazione multimodale + strumenti fallisce a intermittenza |

> [!IMPORTANT]
> **Limiti di Velocità e Gestione delle Quote**
>
> Le quote predefinite di AWS Bedrock per i modelli Claude sono **estremamente restrittive** (2-20 richieste/minuto per i nuovi account). Per il penetration testing in produzione:
>
> 1. **Richiedere aumenti delle quote** tramite la console AWS Service Quotas per i modelli che si intende utilizzare
> 2. **Utilizzare i modelli Amazon Nova** - quote predefinite più elevate e prestazioni eccellenti
> 3. **Abilitare il throughput fornito** per test coerenti ad alto volume
> 4. **Monitorare l'utilizzo** - AWS limita in modo aggressivo ai limiti di quota
>
> Senza aumenti delle quote, sono previsti frequenti ritardi e interruzioni del flusso di lavoro.

> [!WARNING]
> **Requisiti dell'API Converse**
>
> PentAGI utilizza l'**API Converse** di Amazon Bedrock per l'accesso unificato ai modelli. Tutti i modelli supportati richiedono:
>
> - ✅ Supporto dell'API Converse/ConverseStream
> - ✅ Uso degli strumenti (chiamata di funzione) per i flussi di lavoro di penetration testing
> - ✅ Streaming dell'uso degli strumenti per feedback in tempo reale
>
> Verifica le capacità del modello su: [Caratteristiche dei modelli AWS Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html)

**Caratteristiche Principali**:
- **Prompt Caching Automatico**: Riduzione dei costi del 40-70% sul contesto ripetuto (modelli Claude 4.x)
- **Pensiero Esteso**: Ragionamento passo-passo per analisi di sicurezza complesse (Claude, DeepSeek R1, OpenAI GPT)
- **Analisi Multimodale**: Elaborazione di screenshot, diagrammi, video per test completi (Nova, Claude, Mistral, Kimi)
- **Chiamata agli Strumenti**: Integrazione perfetta con oltre 20 strumenti di pentesting tramite chiamata di funzione
- **Streaming**: Streaming delle risposte in tempo reale per flussi di lavoro di valutazione della sicurezza interattivi

### Configurazione del Provider DeepSeek

PentAGI si integra con DeepSeek, fornendo accesso a modelli AI avanzati con forti capacità di ragionamento, codifica e caching del contesto a prezzi competitivi.

#### Variabili di Configurazione

| Variable              | Valore Predefinito           | Descrizione                                        |
| --------------------- | -------------------------- | --------------------------------------------------- |
| `DEEPSEEK_API_KEY`    |                            | Chiave API DeepSeek per l'autenticazione           |
| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | URL dell'endpoint API DeepSeek                     |
| `DEEPSEEK_PROVIDER`   |                            | Prefisso del provider per l'integrazione LiteLLM (opzionale) |

#### Esempi di Configurazione```bash
# Direct API usage
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com

# With LiteLLM proxy
DEEPSEEK_API_KEY=your_litellm_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek  # Adds prefix to model names (deepseek/deepseek-v4-flash) for LiteLLM

#### Modelli Supportati

PentAGI supporta 13 modelli GLM con chiamata a strumenti, streaming, modalità di pensiero ibrido e caching delle richieste. I modelli contrassegnati con `*` vengono utilizzati nella configurazione predefinita. Il pensiero è controllato tramite `extra_body.thinking.type` ("enabled"/"disabled"); a differenza di Kimi, GLM è permissivo riguardo alla temperatura in entrambe le modalità.

**Serie GLM-5.x - Ultima Generazione (contesto 200K, output massimo 128K)**

| ID Modello       | Pensiero | Contesto | Output Max | Prezzo (Input/Output/Cache) | Casi d'Uso                                                          |
| ---------------- | -------- | -------- | ---------- | --------------------------- | ------------------------------------------------------------------- |
| `glm-5.1`*       | ✅ Ibrido | 200K     | 128K       | $1,40/$4,40/$0,26           | Nuovo modello di punta: esecuzione autonoma sostenuta per 8h, allineato con Claude Opus 4.6 (default per generatore/raffinatore/consulente/coder/pentester) |
| `glm-5`          | ✅ Ibrido | 200K     | 128K       | $1,00/$3,20/$0,20           | Fondamenta per Agentic Engineering, MoE 744B/40B attivi, codice a livello Claude Opus 4.5 |
| `glm-5-turbo`*   | ✅ Ibrido | 200K     | 128K       | $1,20/$4,00/$0,24           | Nativo OpenClaw: ottimizzato per invocazione di strumenti, attività persistenti, esecuzione a catena lunga (default per agente primario/assistente) |

**Serie GLM-4.7 - Premium con Pensiero Intervallato**

| ID Modello        | Pensiero | Contesto | Output Max | Prezzo (Input/Output/Cache) | Casi d'Uso                                          |
| ----------------- | -------- | -------- | ---------- | --------------------------- | --------------------------------------------------- |
| `glm-4.7`         | ✅ Ibrido | 200K     | 128K       | $0,60/$2,20/$0,11           | Programmazione potenziata, ragionamento multi-step stabile |
| `glm-4.7-flashx`  | ✅ Ibrido | 200K     | 128K       | $0,07/$0,40/$0,01           | Ultra-economico con GPU prioritaria, ma limiti RPM inferiori (evitare per uso ad alta frequenza) |
| `glm-4.7-flash`   | ✅ Ibrido | 200K     | 128K       | Gratuito/Gratuito/Gratuito  | Modello SOTA ~30B gratuito, 1 richiesta concorrente |

**Serie GLM-4.6 - Bilanciata con Pensiero Automatico**

| ID Modello | Pensiero | Contesto | Output Max | Prezzo (Input/Output/Cache) | Casi d'Uso                                        |
| ---------- | -------- | -------- | ---------- | --------------------------- | ------------------------------------------------- |
| `glm-4.6`  | ✅ Auto   | 200K     | 128K       | $0,60/$2,20/$0,11           | Bilanciato, chiamate a strumenti in streaming, efficiente in termini di token |

**Serie GLM-4.5 - Ragionamento/Codifica/Agenti Unificati**

| ID Modello       | Pensiero | Contesto | Output Max | Prezzo (Input/Output/Cache) | Casi d'Uso                                        |
| ---------------- | -------- | -------- | ---------- | --------------------------- | ------------------------------------------------- |
| `glm-4.5`        | ✅ Auto   | 128K     | 96K        | $0,60/$2,20/$0,11           | Unificato, MoE 355B/32B attivi                    |
| `glm-4.5-x`      | ✅ Auto   | 128K     | 96K        | $2,20/$8,90/$0,45           | Premium ultraveloce, latenza minima               |
| `glm-4.5-air`*   | ✅ Auto   | 128K     | 96K        | $0,20/$1,10/$0,03           | MoE economico 106B/12B (default per semplice/simple_json/riflettore/cercatore/arricchitore/installatore) |
| `glm-4.5-airx`   | ✅ Auto   | 128K     | 96K        | $1,10/$4,50/$0,22           | Air accelerato con GPU prioritaria                |
| `glm-4.5-flash`  | ✅ Auto   | 128K     | 96K        | Gratuito/Gratuito/Gratuito  | Gratuito con supporto a ragionamento/codifica/agenti |

**GLM-4 Legacy - Architettura Densa**

| ID Modello                | Pensiero | Contesto | Output Max | Prezzo (Input/Output) | Casi d'Uso                                    |
| ------------------------- | -------- | -------- | ---------- | --------------------- | --------------------------------------------- |
| `glm-4-32b-0414-128k`     | ❌        | 128K     | 16K        | $0,10/$0,10           | Denso 32B ultra-economico, parsing senza ragionamento |

**Prezzi**: Per 1 milione di token. Il prezzo della cache è per l'hit della cache della richiesta; lo storage della cache è attualmente gratuito come da promozione Z.AI. GLM-4-32B non supporta la cache.

**Configurazione Agente Predefinita**:

Strategia: `glm-5.1` (nuovo modello di punta, $1,40 input) per ragionamento critico, `glm-5-turbo` (nativo OpenClaw, ottimizzato per agenti) per orchestrazione, `glm-4.5-air` (MoE economico con pensiero ibrido e RPM affidabili) per tutti gli agenti di utility/installazione. `glm-4.7-flashx` è evitato come default a causa dei limiti RPM inferiori che causano frequenti errori 429 ad alta frequenza.

| Ruolo Agente                         | Modello Predefinito | Pensiero | Temperatura | Top P | Output Max |
| ------------------------------------ | ------------------- | -------- | ----------- | ----- | ---------- |
| Generatore / Raffinatore             | `glm-5.1`           | Abilitato| 1,0         | 0,95  | 32768      |
| Coder                                | `glm-5.1`           | Abilitato| 1,0         | 0,95  | 20480      |
| Consulente / Pentester               | `glm-5.1`           | Abilitato| 1,0         | 0,95  | 16384      |
| Agente Primario / Assistente         | `glm-5-turbo`       | Abilitato| 1,0         | 0,95  | 16384      |
| Installatore                         | `glm-4.5-air`       | Abilitato| 1,0         | 0,95  | 16384      |
| Semplice / Riflettore                | `glm-4.5-air`       | Disabilitato | 0,6     | 0,9   | 8192       |
| Cercatore / Arricchitore / Simple JSON | `glm-4.5-air`     | Disabilitato | 0,6     | 0,9   | 4096       |

> **Nota sulla temperatura**: GLM accetta sia `1.0` che `0.6` sia in modalità pensiero che non pensiero (secondo la documentazione Z.AI). `IsReasoningModel` di langchaingo corrisponde ai prefissi `glm-4.5*`/`glm-4.6*`/`glm-4.7*` e forza il sovrascrivimento della temperatura a 1.0 in `createChatRequest` — questo è innocuo per GLM (a differenza di Kimi), ma significa che i valori di temperatura per quei modelli in YAML sono indicativi. `glm-5`/`glm-5.1`/`glm-5-turbo` non vengono riconosciuti, quindi i valori espliciti passano invariati.

**Modalità di Pensiero**:
- **Ibrido** (GLM-5.x, GLM-4.7): Attivazione esplicita tramite `extra_body.thinking.type`
- **Auto** (serie GLM-4.6, GLM-4.5): Il modello determina automaticamente quando è necessario ragionare
- **Pensiero Preservato** (capacità di Codifica Z.AI): tutti gli agenti con pensiero abilitato in PentAGI passano anche `extra_body.thinking.clear_thinking: false` in modo che `reasoning_content` dei turni precedenti dell'assistente venga mantenuto attraverso la conversazione. Ciò è richiesto sull'endpoint API standard (`/api/paas/v4`) — sull'endpoint del Piano di Codifica sarebbe abilitato per impostazione predefinita. Migliora la continuità del ragionamento e i tassi di hit della cache in catene di chiamate a strumenti multi-turno.
- Tutti gli agenti con pensiero abilitato passano anche `extra_body.tool_choice: auto` in modo difensivo

**Caratteristiche Chiave**:
- **Attività a Lungo Termine**: GLM-5.1 supporta l'esecuzione autonoma sostenuta per 8 ore, ideale per workflow agentici complessi multi-stadio
- **Orchestrazione Nativa OpenClaw**: GLM-5-Turbo è specificamente ottimizzato per l'invocazione di strumenti, il seguimento di istruzioni e l'esecuzione a catena lunga
- **Caching delle Richieste**: Riduzione significativa dei costi su contesti ripetuti (prezzi di input in cache mostrati)
- **Contesto Ultra-Lungo**: 200K token per le serie GLM-5.x/4.7/4.6
- **Architettura MoE**: Efficiente 744B/40B attivi (GLM-5/5.1), 355B/32B (GLM-4.5), 106B/12B (GLM-4.5-Air)
- **Chiamata a Strumenti**: Integrazione senza soluzione di continuità con oltre 20 strumenti di pentesting tramite chiamata a funzioni
- **Streaming**: Streaming in tempo reale con supporto per chiamate a strumenti in streaming (GLM-4.6+)
- **Multilingue**: Eccezionali capacità NLP in cinese e inglese
- **Opzioni Gratuite**: GLM-4.7-Flash e GLM-4.5-Flash per prototipazione e sperimentazione

**Integrazione LiteLLM**: Imposta `GLM_PROVIDER=zai` per abilitare il prefisso del nome del modello quando si utilizzano le configurazioni PentAGI predefinite con il proxy LiteLLM. Lascia vuoto per l'uso diretto dell'API.

### Configurazione del Provider Kimi

PentAGI si integra con Kimi di Moonshot AI, fornendo modelli con contesto ultra-lungo e capacità multimodali, perfetti per analizzare ampi codebase e documentazione.

#### Variabili di Configurazione

| Variabile           | Valore Predefinito              | Descrizione                                         |
| ------------------- | --------------------------------| --------------------------------------------------- |
| `KIMI_API_KEY`      |                                 | Chiave API Kimi per l'autenticazione                |
| `KIMI_SERVER_URL`   | `https://api.moonshot.ai/v1`    | URL endpoint API Kimi (internazionale)              |
| `KIMI_PROVIDER`     |                                 | Prefisso provider per l'integrazione LiteLLM (opzionale) |

#### Esempi di Configurazione```bash
# Direct API usage (international endpoint)
KIMI_API_KEY=your_kimi_api_key
KIMI_SERVER_URL=https://api.moonshot.ai/v1

# Alternative endpoint
KIMI_SERVER_URL=https://api.moonshot.cn/v1  # China

# With LiteLLM proxy
KIMI_API_KEY=your_litellm_key
KIMI_SERVER_URL=http://litellm-proxy:4000
KIMI_PROVIDER=moonshot  # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM

---

[Read more](https://github.com/vxcontrol/pentagi)