Salta ai contenuti
OpenCode
HomeDocs

Agents

Configura e usa agenti specializzati.

Gli agenti sono assistenti IA specializzati che possono essere configurati per attivita e flussi di lavoro specifici. Ti consentono di creare strumenti focalizzati con prompt personalizzati, modelli e accesso agli strumenti.

Puoi passare da un agente all’altro durante una sessione o invocarli con la menzione @.

Tipi

Ci sono due tipi di agenti in OpenCode; agenti primari e subagenti.

Agenti primari

Gli agenti primari sono gli assistenti principali con cui interagisci direttamente. Puoi cycle attraverso di loro usando il tasto Tab o il tuo keybind switch_agent configurato. Questi agenti gestiscono la tua conversazione principale e possono accedere a tutti gli strumenti configurati.

OpenCode viene fornito con due agenti primari integrati, Build e Plan. Li esamineremo di seguito.

Subagenti

I subagenti sono assistenti specializzati che gli agenti primari possono invocare per attivita specifiche. Puoi anche invocarli manualmente @ menzionandoli nei tuoi messaggi.

OpenCode viene fornito con due subagenti integrati, General e Explore. Lo esamineremo di seguito.

Integrati

OpenCode viene fornito con due agenti primari integrati e due subagenti integrati.

Build

Modo: primary

Build e l’agente primario predefinito con tutti gli strumenti abilitati. Questo e l’agente standard per il lavoro di sviluppo dove hai bisogno di accesso completo alle operazioni sui file e ai comandi di sistema.

Plan

Modo: primary

Un agente limitato progettato per la pianificazione e l’analisi. Utilizziamo un sistema di autorizzazioni per darti piu controllo e prevenire modifiche indesiderate. Per impostazione predefinita, tutto quanto segue e impostato su ask:

  • modifiche ai file: Tutte le scritture, patch e modifiche
  • bash: Tutti i comandi bash

Questo agente e utile quando desideri che l’LLM analizzi il codice, suggerisca modifiche o crei piani senza apportare modifiche effettive alla tua codebase.

General

Modo: subagent

Un agente di proposito generale per ricercare domande complesse, cercare codice ed eseguire attivita a piu fasi. Da usare quando cerchi parole chiave o file e non sei sicuro di trovare la corrispondenza giusta nei primi tentativi.

Explore

Modo: subagent

Un agente veloce specializzato nell’esplorazione delle codebase. Da usare quando devi trovare rapidamente file per pattern, cercare codice per parole chiave o rispondere domande sulla codebase.

Utilizzo

  1. Per gli agenti primari, usa il tasto Tab per cycle attraverso di essi durante una sessione. Puoi anche usare il tuo keybind switch_agent configurato.

  2. I subagenti possono essere invocati:

    • Automaticamente dagli agenti primari per attivita specializzate in base alle loro descrizioni.

    • Manualmente @ menzionando un subagente nel tuo messaggio. Per esempio.

      @general aiutami a cercare questa funzione

  3. Navigazione tra le sessioni: Quando i subagenti creano le proprie sessioni figlie, puoi navigare tra la sessione principale e tutte le sessioni figlie usando:

    • <Leader>+Right (o il tuo keybind session_child_cycle configurato) per cycle in avanti attraverso parent -> child1 -> child2 -> … -> parent
    • <Leader>+Left (o il tuo keybind session_child_cycle_reverse configurato) per cycle all’indietro attraverso parent <- child1 <- child2 <- … <- parent

    Ciò ti consente di passare senza problemi tra la conversazione principale e il lavoro specializzato dei subagenti.

Configurare

Puoi personalizzare gli agenti integrati o crearne di tuoi attraverso la configurazione. Gli agenti possono essere configurati in due modi:

JSON

Configura gli agenti nel tuo file di configurazione 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": "Revisiona il codice per le migliori pratiche e problemi potenziali",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "Sei un revisore di codice. Concentrati sulla sicurezza, prestazioni e manutenibilita.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Puoi anche definire gli agenti usando file markdown. Collocali in:

  • Globale: ~/.config/opencode/agent/
  • Per progetto: .opencode/agent/
~/.config/opencode/agent/review.md
---
description: Revisiona il codice per qualita e migliori pratiche
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---


Sei in modalita revisione del codice. Concentrati su:


- Qualita del codice e migliori pratiche
- Bug potenziali e casi limite
- Implicazioni sulle prestazioni
- Considerazioni sulla sicurezza


Fornisci feedback costruttivi senza apportare modifiche dirette.

Il nome del file markdown diventa il nome dell’agente. Ad esempio, review.md crea un agente review.

Opzioni

Esaminiamo queste opzioni di configurazione in dettaglio.

Descrizione

Usa l’opzione description per fornire una breve descrizione di cosa fa l’agente e quando usarlo.

opencode.json
{
  "agent": {
    "review": {
      "description": "Revisiona il codice per le migliori pratiche e problemi potenziali"
    }
  }
}

Questa e un’opzione di configurazione richiesta.

Temperatura

Controlla la casualita e creativita delle risposte dell’LLM con la configurazione temperature.

Valori piu bassi rendono le risposte piu focalizzate e deterministiche, mentre valori piu alti aumentano la creativita e variabilita.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

I valori di temperatura variano tipicamente da 0.0 a 1.0:

  • 0.0-0.2: Risposte molto focalizzate e deterministiche, ideale per l’analisi del codice e la pianificazione
  • 0.3-0.5: Risposte equilibrate con una certa creativita, buono per attivita di sviluppo generale
  • 0.6-1.0: Risposte piu creative e varie, utile per il brainstorming e l’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 viene specificata alcuna temperatura, OpenCode usa valori predefiniti specifici del modello; tipicamente 0 per la maggior parte dei modelli, 0.55 per i modelli Qwen.

Passaggi massimi

Controlla il numero massimo di iterazioni agentiche che un agente può eseguire prima di essere costretto a rispondere solo con testo. Questo permette agli utenti che desiderano controllare i costi di impostare un limite sulle azioni agentiche.

Se questo non e impostato, l’agente continuera a iterare finche il modello non sceglie di fermarsi o l’utente interrompe la sessione.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Ragionamento rapido con iterazioni limitate",
      "prompt": "Sei un pensatore rapido. Risolvi i problemi con passaggi minimi.",
      "maxSteps": 5
    }
  }
}

Quando viene raggiunto il limite, l’agente riceve un prompt di sistema speciale che gli istruisce a rispondere con un riepilogo del suo lavoro e attivita rimanenti consigliate.

Disabilita

Imposta su true per disabilitare l’agente.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Specifica un file di prompt di sistema personalizzato per questo agente con la configurazione prompt. Il file di prompt deve contenere istruzioni specifiche per lo scopo dell’agente.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Questo percorso e relativo a dove si trova il file di configurazione. Quindi funziona sia per la configurazione globale di OpenCode che per la configurazione specifica del progetto.

Modello

Usa la configurazione model per sovrascrivere il modello per questo agente. Utile per usare diversi modelli ottimizzati per diverse attivita. Ad esempio, un modello piu veloce per la pianificazione, un modello piu capace per l’implementazione.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

L’ID del modello nella tua configurazione OpenCode usa il formato fornitore/id-modello. Ad esempio, se stai usando OpenCode Zen, useresti opencode/gpt-5.1-codex per GPT 5.1 Codex.

Strumenti

Controlla quali strumenti sono disponibili in questo agente con la configurazione tools. Puoi abilitare o disabilitare strumenti specifici impostandoli su 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 i caratteri jolly per controllare piu strumenti contemporaneamente. Ad esempio, per disabilitare tutti gli strumenti da un server MCP:

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

Ulteriori informazioni sugli strumenti.

Autorizzazioni

Puoi configurare le autorizzazioni per gestire quali azioni un agente puo intraprendere. Attualmente, le autorizzazioni per gli strumenti edit, bash e webfetch possono essere configurate per:

  • "ask" - Chiedere l’approvazione prima di eseguire lo strumento
  • "allow" - Consentire tutte le operazioni senza approvazione
  • "deny" - Disabilitare lo strumento
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puoi sovrascrivere queste autorizzazioni per agente.

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

Puoi anche impostare le autorizzazioni negli agenti Markdown.

~/.config/opencode/agent/review.md
---
description: Revisione del codice senza modifiche
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
  webfetch: deny
---


Analizza solo il codice e suggerisci modifiche.

Puoi impostare autorizzazioni per comandi bash specifici.

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

Questo puo accettare un pattern glob.

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

E puoi anche usare il carattere jolly * per gestire le autorizzazioni per tutti i comandi. Dato che l’ultima regola corrispondente ha la precedenza, metti il carattere jolly * prima e le regole specifiche dopo.

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

Ulteriori informazioni sulle autorizzazioni.

Modalita

Controlla la modalita dell’agente con la configurazione mode. L’opzione mode viene utilizzata per determinare come l’agente puo essere utilizzato.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

L’opzione mode puo essere impostata su primary, subagent o all. Se non viene specificata alcuna modalita, il predefinito e all.

Nascosto

Nascondi un subagente dal menu di autocompletamento @ 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 dell’utente nel menu di autocompletamento. Gli agenti nascosti possono comunque essere invocati dal modello tramite lo strumento Task se le autorizzazioni lo consentono.

Autorizzazioni di attivita

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

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Quando impostato su deny, il subagente viene rimosso completamente dalla descrizione dello strumento Task, quindi il modello non tentera di invocarlo.

Addizionale

Qualsiasi altra opzione specifichi nella tua configurazione dell’agente sara passata direttamente al fornitore come opzioni del modello. Questo ti consente di utilizzare funzionalita e parametri specifici del fornitore.

Ad esempio, con i modelli di ragionamento di OpenAI, puoi controllare lo sforzo di ragionamento:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agente che usa alto sforzo di ragionamento per problemi complessi",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Queste opzioni addizionali sono specifiche del modello e del fornitore. Consulta la documentazione del tuo fornitore per i parametri disponibili.

Creare agenti

Puoi creare nuovi agenti usando il seguente comando:

Terminal window
opencode agent create

Questo comando interattivo:

  1. Chiedera dove salvare l’agente; globale o specifico del progetto.
  2. Descrizione di cosa dovrebbe fare l’agente.
  3. Generera un prompt di sistema appropriato e un identificatore.
  4. Ti permettera di selezionare a quali strumenti l’agente puo accedere.
  5. Infine, creera un file markdown con la configurazione dell’agente.

Casi d’uso

Ecco alcuni casi d’uso comuni per diversi agenti.

  • Agente Build: Lavoro di sviluppo completo con tutti gli strumenti abilitati
  • Agente Plan: Analisi e pianificazione senza apportare modifiche
  • Agente Review: Revisione del codice con accesso in sola lettura piu strumenti di documentazione
  • Agente Debug: Concentrato sull’investigazione con strumenti bash e read abilitati
  • Agente Docs: Scrittura di documentazione con operazioni sui file ma nessun comando di sistema

Esempi

Ecco alcuni agenti di esempio che potresti trovare utili.

Agente di documentazione

~/.config/opencode/agent/docs-writer.md
---
description: Scrive e mantiene la documentazione del progetto
mode: subagent
tools:
  bash: false
---


Sei un scrittore tecnico. Crea documentazione chiara e completa.


Concentrati su:


- Spiegazioni chiare
- Struttura appropriata
- Esempi di codice
- Linguaggio intuitivo per l'utente

Auditor di sicurezza

~/.config/opencode/agent/security-auditor.md
---
description: Esegue audit di sicurezza e identifica vulnerabilita
mode: subagent
tools:
  write: false
  edit: false
---


Sei un esperto di sicurezza. Concentrati sull'identificazione di potenziali problemi di sicurezza.


Cerca:


- Vulnerabilita di convalida dell'input
- Difetti di autenticazione e autorizzazione
- Rischi di esposizione dei dati
- Vulnerabilita delle dipendenze
- Problemi di sicurezza della configurazione