File size: 19,124 Bytes

0dbc9de

---
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
```