Agenti: Build e Plan

Guida

Agenti: Build e Plan

In OpenCode V2 «Build» e «Plan» non sono modalità della TUI: sono due agenti. Questo cambia il modo in cui si passa dall'uno all'altro.

Che cos'è un agente

Un agente combina un prompt di sistema, un modello preferito, permessi e dettagli di visualizzazione. È un profilo assistente con un nome: sceglierlo cambia come lavora OpenCode, non solo l'etichetta nell'interfaccia.

Gli agenti inclusi

AgenteIDModalitàA cosa serve
Build build primary Agente di coding predefinito. Può modificare file e usare strumenti fuori dalla workspace; la lettura dei file .env chiede approvazione.
Plan plan primary Esplora e pianifica senza modificare i file normali del progetto. Può scrivere i file di piano di OpenCode; i comandi shell restano soggetti ai permessi.
General general subagent Ricerca e lavoro multi-step con accesso ampio agli strumenti, ma non può lanciare altri subagenti.
Explore explore subagent Cerca e legge codice o fonti web senza modificare file.

Esistono anche tre agenti nascosti (compaction, title, summary) che svolgono manutenzione e non si possono selezionare.

Come cambiare agente

AzioneCome
Agente successivoShift+Tab
Lista agentiCtrl+X, poi A
Lista agenti (comando)/agents
Scorciatoia personalizzataagent.cycle in cli.json
Perché Tab non funziona più? Nella V1 Tab alternava Build e Plan. Nella V2 quella scorciatoia non esiste: il passaggio tra agenti è Shift+Tab (voce agent.cycle). Se Shift+Tab non fa nulla, quasi sempre è il terminale che la intercetta: rimappa il comando su un altro tasto.

Esempio: rimappare il cambio agente

Crea o modifica ~/.config/opencode/cli.json (su Windows %USERPROFILE%\.config\opencode\cli.json):

{
  "keybinds": {
    "agent.cycle": "alt+p"
  }
}

Alt+P è libero nelle impostazioni predefinite della V2 e non collide con le scorciatoie di which-key (Ctrl+Alt+…). Le modifiche a cli.json vengono ricaricate senza riavviare.

Configurare un agente

Puoi definire agenti in Markdown oppure in JSON. I file Markdown stanno in:

~/.config/opencode/agents/<nome>.md
.opencode/agents/<nome>.md

Su Windows la prima cartella è %USERPROFILE%\.config\opencode\agents\.

Markdown

---
description: Revisiona le modifiche senza toccare i file
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Revisiona le modifiche correnti. Elenca i problemi in ordine di gravità,
con file e riga.

JSON

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "reviewer": {
      "description": "Revisiona le modifiche correnti",
      "mode": "subagent",
      "system": "Riporta i problemi in ordine di gravità.",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

Campi principali

CampoSignificato
modeprimary (agente principale), subagent (solo sessione figlia) o all. Default per un nuovo agente: primary.
modelprovider/modello, con variante opzionale #high.
systemPrompt di sistema. In Markdown è il corpo del file.
descriptionSpiega lo scopo, soprattutto per i subagenti.
permissionsRegole ordinate: action, resource, effect (allow, ask, deny). Vince l'ultima regola che corrisponde.
stepsNumero massimo di passi del modello.
hiddenNasconde l'agente dagli elenchi. Non è una misura di sicurezza.
disabledRimuove un agente (anche incluso) in quel punto della configurazione.
colorColore dell'agente, esadecimale a sei cifre.

Agente predefinito

Per scegliere l'agente usato quando una sessione non ne ha già uno:

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan",
  "agents": {
    "plan": { "mode": "primary" }
  }
}

L'agente predefinito deve esistere, essere visibile e supportare l'uso come primario. Altrimenti OpenCode usa build, poi il primo agente primario visibile.

Nota: cambiare agente non cambia il modello della sessione. Modello e agente sono selezioni separate.

Disattivare un agente incluso

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "plan": { "disabled": true }
  }
}

Utile se vuoi che Shift+Tab non passi più da Plan.