Files
opencode/packages/web/src/content/docs/it/agents.mdx
2026-02-09 11:34:35 -06:00

747 lines
18 KiB
Plaintext

---
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 e' 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 due subagenti integrati: **General** e **Explore**. Li vediamo sotto.
---
## Integrati
OpenCode include due agenti primari integrati e due subagenti integrati.
---
### Usa build
_Mode_: `primary`
Build e' l'agente primario **predefinito** con tutti gli strumenti abilitati. E' l'agente standard per lavoro di sviluppo quando ti serve pieno accesso a operazioni sui file e comandi di sistema.
---
### Usa plan
_Mode_: `primary`
Un agente limitato pensato per pianificazione e analisi. Usiamo un sistema di permessi per darti piu' 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 e' utile quando vuoi che l'LLM analizzi il codice, suggerisca modifiche o crei piani senza effettuare alcuna modifica reale al codebase.
---
### Usa general
_Mode_: `subagent`
Un agente general-purpose per ricercare domande complesse ed eseguire task multi-step. Ha accesso completo agli strumenti (tranne todo), quindi puo' modificare file quando serve. Usalo per eseguire piu' unita' di lavoro in parallelo.
---
### Usa explore
_Mode_: `subagent`
Un agente rapido in sola lettura per esplorare codebase. Non puo' modificare file. Usalo quando devi trovare rapidamente file tramite pattern, cercare nel codice per keyword o rispondere a domande sul codebase.
---
### Usa compaction
_Mode_: `primary`
Agente di sistema nascosto che compatta contesti lunghi in un riassunto piu' piccolo. Viene eseguito automaticamente quando serve e non e' selezionabile nella UI.
---
### Usa title
_Mode_: `primary`
Agente di sistema nascosto che genera titoli brevi per le sessioni. Viene eseguito automaticamente quando serve e non e' selezionabile nella UI.
---
### Usa summary
_Mode_: `primary`
Agente di sistema nascosto che crea riassunti di sessione. Viene eseguito automaticamente quando serve e non e' 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 continuita' tra la conversazione principale e il lavoro specializzato dei subagenti.
---
## Configura
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 e' un'opzione di configurazione **obbligatoria**.
---
### Temperatura
Controlla casualita' e creativita' delle risposte dell'LLM con la config `temperature`.
Valori bassi rendono le risposte piu' focalizzate e deterministiche, mentre valori alti aumentano creativita' e variabilita'.
```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 creativita', adatte a task generali di sviluppo
- **0.6-1.0**: risposte piu' 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 puo' 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 e' impostato, l'agente continuera' a iterare finche' 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` e' deprecato. Usa `steps`.
:::
---
### Disabilita
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 e' 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 piu' veloce per la pianificazione e uno piu' 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 piu' 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 piu' sugli strumenti](/docs/tools).
---
### Permessi
Puoi configurare i permessi per gestire quali azioni un agente puo' 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 puo' 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 piu' sui permessi](/docs/permissions).
---
### Modalita'
Controlla la modalita' dell'agente con la config `mode`. L'opzione `mode` determina come l'agente puo' essere usato.
```json title="opencode.json"
{
"agent": {
"review": {
"mode": "subagent"
}
}
}
```
`mode` puo' essere `primary`, `subagent` o `all`. Se `mode` non e' specificato, il default e' `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 visibilita' 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 puo' 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 e' impostato a `deny`, il subagente viene rimosso interamente dalla descrizione dello strumento Task, quindi il modello non provera' 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 e' `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 diversita' delle risposte con l'opzione `top_p`. Alternativa alla temperature per controllare la casualita'.
```json title="opencode.json"
{
"agent": {
"brainstorm": {
"top_p": 0.9
}
}
}
```
I valori vanno da 0.0 a 1.0. Valori piu' bassi sono piu' focalizzati, valori piu' alti piu' diversi.
---
### Opzioni aggiuntive
Qualsiasi altra opzione che specifichi nella configurazione dell'agente verra' **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.
:::
---
## Crea 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 puo' 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 piu' 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
```