Salta ai contenuti
OpenCode
app.header.homeapp.header.docs

Agenti

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.

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.

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.

      @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:

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/
~/.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.

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’.

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

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.

Disabilita

Imposta a true per disabilitare l’agente.

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.

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.

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, 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.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Puoi anche usare wildcard per controllare piu’ strumenti in una volta. Per esempio, per disabilitare tutti gli strumenti di un server MCP:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Scopri di piu’ sugli strumenti.

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
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puoi sovrascrivere questi permessi per agente.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Puoi anche impostare permessi negli agenti Markdown.

~/.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.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Questo puo’ usare un glob pattern.

opencode.json
{
  "$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.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Scopri di piu’ sui permessi.

Modalita’

Controlla la modalita’ dell’agente con la config mode. L’opzione mode determina come l’agente puo’ essere usato.

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.

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.

Permessi Task

Controlla quali subagenti un agente puo’ invocare tramite lo strumento Task con permission.task. Usa glob pattern per un matching flessibile.

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.

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.

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’.

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:

opencode.json
{
  "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.

Crea agenti

Puoi creare nuovi agenti usando il comando seguente:

Terminal window
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.

Agente documentazione

~/.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

~/.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