@neurocode-ai/web 1.18.8

package/src/content/docs/it/agents.mdx

@@ -0,0 +1,753 @@
+---
+title: Agenti
+description: Configura e usa agenti specializzati.
+---
+
+Gli agenti sono assistenti AI specializzati che puoi configurare per task e workflow specifici. Ti permettono di creare strumenti mirati con prompt personalizzati, modelli e accesso agli strumenti.
+
+:::tip
+Usa l'agente plan per analizzare codice e valutare suggerimenti senza apportare modifiche al codice.
+:::
+
+Puoi passare da un agente all'altro durante una sessione oppure invocarli con la menzione `@`.
+
+---
+
+## Tipi
+
+In OpenCode esistono due tipi di agenti: agenti primari e subagenti.
+
+---
+
+### Agenti primari
+
+Gli agenti primari sono gli assistenti principali con cui interagisci direttamente. Puoi scorrerli usando il tasto **Tab** o la scorciatoia `switch_agent` configurata. Questi agenti gestiscono la conversazione principale. L'accesso agli strumenti si configura tramite i permessi: per esempio, Build ha tutti gli strumenti abilitati, mentre Plan è limitato.
+
+:::tip
+Puoi usare **Tab** per passare tra gli agenti primari durante una sessione.
+:::
+
+OpenCode include due agenti primari integrati: **Build** e **Plan**. Li vediamo sotto.
+
+---
+
+### Subagenti
+
+I subagenti sono assistenti specializzati che gli agenti primari possono invocare per task specifici. Puoi anche invocarli manualmente **menzionandoli con @** nei tuoi messaggi.
+
+OpenCode include tre subagenti integrati: **General**, **Explore** e **Scout**. Li vediamo sotto.
+
+---
+
+## Integrati
+
+OpenCode include due agenti primari integrati e tre subagenti integrati.
+
+---
+
+### Build
+
+_Mode_: `primary`
+
+Build è l'agente primario **predefinito** con tutti gli strumenti abilitati. È l'agente standard per lavoro di sviluppo quando ti serve pieno accesso a operazioni sui file e comandi di sistema.
+
+---
+
+### Plan
+
+_Mode_: `primary`
+
+Un agente limitato pensato per pianificazione e analisi. Usiamo un sistema di permessi per darti più controllo e prevenire modifiche non intenzionali.
+Di default, tutte le seguenti sono impostate a `ask`:
+
+- `file edits`: tutte le scritture, patch ed edit
+- `bash`: tutti i comandi bash
+
+Questo agente è utile quando vuoi che l'LLM analizzi il codice, suggerisca modifiche o crei piani senza effettuare alcuna modifica reale al codebase.
+
+---
+
+### General
+
+_Mode_: `subagent`
+
+Un agente general-purpose per ricercare domande complesse ed eseguire task multi-step. Ha accesso completo agli strumenti (tranne todo), quindi può modificare file quando serve. Usalo per eseguire più unità di lavoro in parallelo.
+
+---
+
+### Explore
+
+_Mode_: `subagent`
+
+Un agente rapido in sola lettura per esplorare codebase. Non può modificare file. Usalo quando devi trovare rapidamente file tramite pattern, cercare nel codice per keyword o rispondere a domande sul codebase.
+
+---
+
+### Scout
+
+_Mode_: `subagent`
+
+Un agente in sola lettura per la ricerca su documentazione esterna e dipendenze. Usalo quando devi clonare il repository di una dipendenza nella cache gestita di OpenCode, ispezionare il codice sorgente di una libreria o confrontare il codice locale con implementazioni upstream senza modificare il tuo workspace.
+
+---
+
+### Compaction
+
+_Mode_: `primary`
+
+Agente di sistema nascosto che compatta contesti lunghi in un riassunto più piccolo. Viene eseguito automaticamente quando serve e non è selezionabile nella UI.
+
+---
+
+### Title
+
+_Mode_: `primary`
+
+Agente di sistema nascosto che genera titoli brevi per le sessioni. Viene eseguito automaticamente quando serve e non è selezionabile nella UI.
+
+---
+
+### Summary
+
+_Mode_: `primary`
+
+Agente di sistema nascosto che crea riassunti di sessione. Viene eseguito automaticamente quando serve e non è selezionabile nella UI.
+
+---
+
+## Utilizzo
+
+1. Per gli agenti primari, usa il tasto **Tab** per scorrerli durante una sessione. Puoi anche usare la scorciatoia `switch_agent` configurata.
+
+2. I subagenti possono essere invocati:
+   - **Automaticamente** dagli agenti primari per task specializzati in base alle loro descrizioni.
+   - Manualmente **menzionando con @** un subagente nel tuo messaggio. Per esempio:
+
+     ```txt frame="none"
+     @general help me search for this function
+     ```
+   3. **Navigazione tra sessioni**: quando i subagenti creano le loro child session, puoi navigare tra la sessione padre e tutte le sessioni figlie usando:
+   - **\<Leader>+Right** (o la scorciatoia `session_child_cycle` configurata) per ciclare in avanti tra parent → child1 → child2 → ... → parent
+   - **\<Leader>+Left** (o la scorciatoia `session_child_cycle_reverse` configurata) per ciclare indietro tra parent ← child1 ← child2 ← ... ← parent
+
+   Questo ti permette di passare senza soluzione di continuità tra la conversazione principale e il lavoro specializzato dei subagenti.
+
+---
+
+## Configurazione
+
+Puoi personalizzare gli agenti integrati o crearne di tuoi tramite configurazione. Gli agenti possono essere configurati in due modi:
+
+---
+
+### JSON
+
+Configura gli agenti nel file `opencode.json`:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "{file:./prompts/build.txt}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      }
+    },
+    "plan": {
+      "mode": "primary",
+      "model": "anthropic/claude-haiku-4-20250514",
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false
+      }
+    },
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+---
+
+### Markdown
+
+Puoi anche definire agenti usando file markdown. Mettili in:
+
+- Globale: `~/.config/opencode/agents/`
+- Per progetto: `.opencode/agents/`
+
+```markdown title="~/.config/opencode/agents/review.md"
+---
+description: Reviews code for quality and best practices
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.
+```
+
+Il nome del file markdown diventa il nome dell'agente. Per esempio, `review.md` crea un agente `review`.
+
+---
+
+## Opzioni
+
+Vediamo nel dettaglio queste opzioni di configurazione.
+
+---
+
+### Descrizione
+
+Usa l'opzione `description` per fornire una breve descrizione di cosa fa l'agente e quando usarlo.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "description": "Reviews code for best practices and potential issues"
+    }
+  }
+}
+```
+
+Questa è un'opzione di configurazione **obbligatoria**.
+
+---
+
+### Temperatura
+
+Controlla casualità e creatività delle risposte dell'LLM con la config `temperature`.
+
+Valori bassi rendono le risposte più focalizzate e deterministiche, mentre valori alti aumentano creatività e variabilità.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "plan": {
+      "temperature": 0.1
+    },
+    "creative": {
+      "temperature": 0.8
+    }
+  }
+}
+```
+
+I valori di temperature tipicamente vanno da 0.0 a 1.0:
+
+- **0.0-0.2**: risposte molto focalizzate e deterministiche, ideali per analisi del codice e pianificazione
+- **0.3-0.5**: risposte bilanciate con un po' di creatività, adatte a task generali di sviluppo
+- **0.6-1.0**: risposte più creative e varie, utili per brainstorming ed esplorazione
+
+```json title="opencode.json"
+{
+  "agent": {
+    "analyze": {
+      "temperature": 0.1,
+      "prompt": "{file:./prompts/analysis.txt}"
+    },
+    "build": {
+      "temperature": 0.3
+    },
+    "brainstorm": {
+      "temperature": 0.7,
+      "prompt": "{file:./prompts/creative.txt}"
+    }
+  }
+}
+```
+
+Se non specifichi una temperature, OpenCode usa i default specifici del modello; tipicamente 0 per la maggior parte dei modelli e 0.55 per i modelli Qwen.
+
+---
+
+### Passi massimi
+
+Controlla il numero massimo di iterazioni agentiche che un agente può eseguire prima di essere forzato a rispondere solo con testo. Questo permette a chi vuole controllare i costi di impostare un limite alle azioni agentiche.
+
+Se non è impostato, l'agente continuerà a iterare finché il modello sceglie di fermarsi o l'utente interrompe la sessione.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "quick-thinker": {
+      "description": "Fast reasoning with limited iterations",
+      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
+      "steps": 5
+    }
+  }
+}
+```
+
+Quando viene raggiunto il limite, l'agente riceve un system prompt speciale che lo istruisce a rispondere con un riassunto del lavoro svolto e con i task rimanenti consigliati.
+
+:::caution
+Il campo legacy `maxSteps` è deprecato. Usa `steps`.
+:::
+
+---
+
+### Disabilitazione
+
+Imposta a `true` per disabilitare l'agente.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "disable": true
+    }
+  }
+}
+```
+
+---
+
+### Prompt
+
+Specifica un file di system prompt personalizzato per questo agente tramite la config `prompt`. Il file deve contenere istruzioni specifiche per lo scopo dell'agente.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "prompt": "{file:./prompts/code-review.txt}"
+    }
+  }
+}
+```
+
+Questo path è relativo alla posizione del file di configurazione. Quindi funziona sia per la config globale di OpenCode sia per la config specifica del progetto.
+
+---
+
+### Modello
+
+Usa la config `model` per sovrascrivere il modello per questo agente. Utile per usare modelli diversi ottimizzati per task diversi. Per esempio, un modello più veloce per la pianificazione e uno più capace per l'implementazione.
+
+:::tip
+Se non specifichi un modello, gli agenti primari usano il [modello configurato globalmente](/docs/config#models), mentre i subagenti useranno il modello dell'agente primario che li ha invocati.
+:::
+
+```json title="opencode.json"
+{
+  "agent": {
+    "plan": {
+      "model": "anthropic/claude-haiku-4-20250514"
+    }
+  }
+}
+```
+
+L'ID modello nella configurazione OpenCode usa il formato `provider/model-id`. Per esempio, se stai usando [OpenCode Zen](/docs/zen), useresti `opencode/gpt-5.1-codex` per GPT 5.1 Codex.
+
+---
+
+### Strumenti
+
+Controlla quali strumenti sono disponibili per questo agente tramite la config `tools`. Puoi abilitare o disabilitare strumenti specifici impostandoli a `true` o `false`.
+
+```json title="opencode.json" {3-6,9-12}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "tools": {
+    "write": true,
+    "bash": true
+  },
+  "agent": {
+    "plan": {
+      "tools": {
+        "write": false,
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+:::note
+La configurazione specifica dell'agente sovrascrive la configurazione globale.
+:::
+
+Puoi anche usare wildcard per controllare più strumenti in una volta. Per esempio, per disabilitare tutti gli strumenti di un server MCP:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "readonly": {
+      "tools": {
+        "mymcp_*": false,
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+[Scopri di più sugli strumenti](/docs/tools).
+
+---
+
+### Permessi
+
+Puoi configurare i permessi per gestire quali azioni un agente può eseguire. Attualmente, i permessi per gli strumenti `edit`, `bash` e `webfetch` possono essere configurati come:
+
+- `"ask"` — chiede approvazione prima di eseguire lo strumento
+- `"allow"` — consente tutte le operazioni senza approvazione
+- `"deny"` — disabilita lo strumento
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  }
+}
+```
+
+Puoi sovrascrivere questi permessi per agente.
+
+```json title="opencode.json" {3-5,8-10}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  },
+  "agent": {
+    "build": {
+      "permission": {
+        "edit": "ask"
+      }
+    }
+  }
+}
+```
+
+Puoi anche impostare permessi negli agenti Markdown.
+
+```markdown title="~/.config/opencode/agents/review.md"
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": ask
+    "git diff": allow
+    "git log*": allow
+    "grep *": allow
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+
+Puoi impostare permessi per comandi bash specifici.
+
+```json title="opencode.json" {7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git push": "ask",
+          "grep *": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+Questo può usare un glob pattern.
+
+```json title="opencode.json" {7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git *": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+E puoi anche usare la wildcard `*` per gestire i permessi per tutti i comandi.
+Dato che l'ultima regola che corrisponde ha la precedenza, metti prima la wildcard `*` e poi le regole specifiche.
+
+```json title="opencode.json" {8}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "*": "ask",
+          "git status *": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+[Scopri di più sui permessi](/docs/permissions).
+
+---
+
+### Modalità
+
+Controlla la modalità dell'agente con la config `mode`. L'opzione `mode` determina come l'agente può essere usato.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "mode": "subagent"
+    }
+  }
+}
+```
+
+`mode` può essere `primary`, `subagent` o `all`. Se `mode` non è specificato, il default è `all`.
+
+---
+
+### Nascosto
+
+Nascondi un subagente dal menu autocomplete di `@` con `hidden: true`. Utile per subagenti interni che dovrebbero essere invocati solo programmaticamente da altri agenti tramite lo strumento Task.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "internal-helper": {
+      "mode": "subagent",
+      "hidden": true
+    }
+  }
+}
+```
+
+Questo influisce solo sulla visibilità per l'utente nel menu autocomplete. Gli agenti nascosti possono comunque essere invocati dal modello tramite lo strumento Task se i permessi lo consentono.
+
+:::note
+Si applica solo ad agenti con `mode: subagent`.
+:::
+
+---
+
+### Permessi Task
+
+Controlla quali subagenti un agente può invocare tramite lo strumento Task con `permission.task`. Usa glob pattern per un matching flessibile.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "orchestrator": {
+      "mode": "primary",
+      "permission": {
+        "task": {
+          "*": "deny",
+          "orchestrator-*": "allow",
+          "code-reviewer": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+Quando è impostato a `deny`, il subagente viene rimosso interamente dalla descrizione dello strumento Task, quindi il modello non proverà a invocarlo.
+
+:::tip
+Le regole vengono valutate in ordine e **vince l'ultima regola che corrisponde**. Nell'esempio sopra, `orchestrator-planner` corrisponde sia a `*` (deny) sia a `orchestrator-*` (allow), ma dato che `orchestrator-*` viene dopo `*`, il risultato è `allow`.
+:::
+
+:::tip
+Gli utenti possono sempre invocare qualunque subagente direttamente dal menu autocomplete `@`, anche se i permessi task dell'agente lo negherebbero.
+:::
+
+---
+
+### Colore
+
+Personalizza l'aspetto visivo dell'agente nella UI con l'opzione `color`. Questo influisce su come l'agente appare nell'interfaccia.
+
+Usa un colore hex valido (ad es. `#FF5733`) o un colore tema: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "creative": {
+      "color": "#ff6b6b"
+    },
+    "code-reviewer": {
+      "color": "accent"
+    }
+  }
+}
+```
+
+---
+
+### Top P
+
+Controlla la diversità delle risposte con l'opzione `top_p`. Alternativa alla temperature per controllare la casualità.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "brainstorm": {
+      "top_p": 0.9
+    }
+  }
+}
+```
+
+I valori vanno da 0.0 a 1.0. Valori più bassi sono più focalizzati, valori più alti più diversi.
+
+---
+
+### Opzioni aggiuntive
+
+Qualsiasi altra opzione che specifichi nella configurazione dell'agente verrà **passata direttamente** al provider come opzione del modello. Questo ti permette di usare feature e parametri specifici del provider.
+
+Per esempio, con i modelli di reasoning di OpenAI, puoi controllare lo sforzo di ragionamento:
+
+```json title="opencode.json" {6,7}
+{
+  "agent": {
+    "deep-thinker": {
+      "description": "Agent that uses high reasoning effort for complex problems",
+      "model": "openai/gpt-5",
+      "reasoningEffort": "high",
+      "textVerbosity": "low"
+    }
+  }
+}
+```
+
+Queste opzioni aggiuntive sono specifiche per modello e provider. Controlla la documentazione del provider per i parametri disponibili.
+
+:::tip
+Esegui `opencode models` per vedere la lista dei modelli disponibili.
+:::
+
+---
+
+## Creazione agenti
+
+Puoi creare nuovi agenti usando il comando seguente:
+
+```bash
+opencode agent create
+```
+
+Questo comando interattivo:
+
+1. Chiede dove salvare l'agente: globale o specifico del progetto.
+2. Chiede una descrizione di cosa dovrebbe fare l'agente.
+3. Genera un system prompt appropriato e un identificatore.
+4. Ti fa selezionare a quali strumenti l'agente può accedere.
+5. Infine, crea un file markdown con la configurazione dell'agente.
+
+---
+
+## Casi d'uso
+
+Ecco alcuni casi d'uso comuni per agenti diversi.
+
+- **Build agent**: sviluppo completo con tutti gli strumenti abilitati
+- **Plan agent**: analisi e pianificazione senza apportare modifiche
+- **Review agent**: code review con accesso in sola lettura più strumenti documentazione
+- **Debug agent**: focalizzato sull'investigazione con strumenti bash e read abilitati
+- **Docs agent**: scrittura documentazione con operazioni sui file ma senza comandi di sistema
+
+---
+
+## Esempi
+
+Ecco alcuni agenti di esempio che potresti trovare utili.
+
+:::tip
+Hai un agente che vorresti condividere? [Invia una PR](https://github.com/anomalyco/opencode).
+:::
+
+---
+
+### Agente documentazione
+
+```markdown title="~/.config/opencode/agents/docs-writer.md"
+---
+description: Writes and maintains project documentation
+mode: subagent
+tools:
+  bash: false
+---
+
+You are a technical writer. Create clear, comprehensive documentation.
+
+Focus on:
+
+- Clear explanations
+- Proper structure
+- Code examples
+- User-friendly language
+```
+
+---
+
+### Auditor di sicurezza
+
+```markdown title="~/.config/opencode/agents/security-auditor.md"
+---
+description: Performs security audits and identifies vulnerabilities
+mode: subagent
+tools:
+  write: false
+  edit: false
+---
+
+You are a security expert. Focus on identifying potential security issues.
+
+Look for:
+
+- Input validation vulnerabilities
+- Authentication and authorization flaws
+- Data exposure risks
+- Dependency vulnerabilities
+- Configuration security issues
+```