Agenti

Gli agenti sono assistenti AI specializzati che possono essere configurati per attività e flussi di lavoro specifici. Ti permettono 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 Dropstone: agenti primari e subagenti.

Agenti primari

Gli agenti primari sono gli assistenti principali con cui interagisci direttamente. Puoi ciclarli usando il tasto Tab o il tuo keybind switch_agent configurato. Questi agenti gestiscono la tua conversazione principale. L'accesso agli strumenti è configurato tramite permessi: ad esempio, Build ha tutti gli strumenti abilitati mentre Plan è limitato.

Dropstone 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 attività specifiche. Puoi anche invocarli manualmente @ menzionandoli nei tuoi messaggi.

Dropstone viene fornito con due subagenti integrati, General e Explore. Li esamineremo di seguito.

Integrati

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

Usa build

Mode: primary

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

Usa plan

Mode: primary

Un agente limitato progettato per la pianificazione e l'analisi. Utilizziamo un sistema di permessi per darti più controllo e prevenire modifiche indesiderate. Per impostazione predefinita, tutti i seguenti sono impostati su ask:

• file edits: Tutti gli scritti, patch e modifiche
• bash: Tutti i comandi bash

Questo agente è utile quando vuoi che l'LLM analizzi il codice, suggerisca modifiche o crei piani senza apportare modifiche effettive al tuo codebase.

Usa general

Mode: subagent

Un agente generico per ricercare domande complesse ed eseguire attività multi-step. Ha accesso completo agli strumenti (tranne todo), quindi può apportare modifiche ai file quando necessario. Usalo per eseguire più unità di lavoro in parallelo.

Usa explore

Mode: subagent

Un agente veloce e di sola lettura per esplorare i codebase. Non può modificare i file. Usalo quando hai bisogno di trovare rapidamente file per pattern, cercare codice per parole chiave o rispondere a domande sul codebase.

Usa compaction

Mode: primary

Agente di sistema nascosto che compatta il contesto lungo in un riassunto più piccolo. Viene eseguito automaticamente quando necessario e non è selezionabile nell'interfaccia utente.

Usa title

Mode: primary

Agente di sistema nascosto che genera brevi titoli di sessione. Viene eseguito automaticamente e non è selezionabile nell'interfaccia utente.

Usa summary

Mode: primary

Agente di sistema nascosto che crea riassunti di sessione. Viene eseguito automaticamente e non è selezionabile nell'interfaccia utente.

Utilizzo

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

2. I subagenti possono essere invocati:

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

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

     @general help me search for this function
     

3. Navigazione tra sessioni: Quando i subagenti creano sessioni figlie, usa session_child_first (predefinito: <Leader>+Down) per entrare nella prima sessione figlia dal genitore.

4. Una volta che sei in una sessione figlia, usa:

   • session_child_cycle (predefinito: Right) per ciclarsi alla prossima sessione figlia
   • session_child_cycle_reverse (predefinito: Left) per ciclarsi alla sessione figlia precedente
   • session_parent (predefinito: Up) per tornare alla sessione genitore

   Questo ti permette di passare tra la conversazione principale e il lavoro specializzato del subagente.

Configura

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 dropstone.json:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "dropstone/dropstone-pro",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "dropstone/dropstone-fast",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Markdown

Puoi anche definire agenti usando file markdown. Posizionali in:

• Globale: ~/.config/dropstone/agents/
• Per progetto: .dropstone/agents/

---
description: Reviews code for quality and best practices
mode: subagent
model: dropstone/dropstone-pro
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

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

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Questa è un'opzione di configurazione obbligatoria.

Temperatura

Controlla la casualità e la creatività delle risposte dell'LLM con la configurazione temperature.

Valori più bassi rendono le risposte più focalizzate e deterministiche, mentre valori più alti aumentano la creatività e la variabilità.

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

I valori di temperatura vanno tipicamente da 0.0 a 1.0:

• 0.0-0.2: Risposte molto focalizzate e deterministiche, ideali per l'analisi del codice e la pianificazione
• 0.3-0.5: Risposte bilanciate con una certa creatività, buone per i compiti di sviluppo generale
• 0.6-1.0: Risposte più creative e variate, utili per il brainstorming e l'esplorazione

{
  "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 è specificata alcuna temperatura, Dropstone utilizza un valore predefinito sensato sintonizzato per ogni tier.

Max steps

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

Se non è impostato, l'agente continuerà a iterare fino a quando il modello sceglie di fermarsi o l'utente interrompe la sessione.

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Quando il limite viene raggiunto, l'agente riceve un prompt di sistema speciale che gli istruisce di rispondere con un riassunto del suo lavoro e dei compiti rimanenti consigliati.

Disabilita

Imposta su true per disabilitare l'agente.

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

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

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

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

Modello

Usa la configurazione model per sovrascrivere il modello per questo agente. Utile per usare modelli diversi ottimizzati per compiti diversi. Ad esempio, un modello più veloce per la pianificazione, un modello più capace per l'implementazione.

{
  "agent": {
    "plan": {
      "model": "dropstone/dropstone-fast"
    }
  }
}

L'ID del modello utilizza il formato dropstone/<tier>. Usa dropstone/dropstone-fast, dropstone/dropstone-pro o dropstone/dropstone-heavy.

Strumenti (deprecato)

tools è deprecato. Preferisci il campo permission dell'agente per le nuove configurazioni, gli aggiornamenti e un controllo più granulare.

Ti permette di controllare quali strumenti sono disponibili in questo agente. Puoi abilitare o disabilitare strumenti specifici impostandoli su true o false. Nella configurazione tools di un agente, true è equivalente a {"*": "allow"} permission e false è equivalente a {"*": "deny"} permission.

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

Puoi anche usare i caratteri jolly nelle voci legacy tools per controllare più strumenti contemporaneamente. Ad esempio, per disabilitare tutti gli strumenti da un server MCP:

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

Scopri di più su strumenti.

Permessi

Puoi configurare i permessi per gestire quali azioni un agente può intraprendere. Ogni chiave di permesso può essere impostata su:

• "ask": Chiedi approvazione prima di eseguire lo strumento
• "allow": Consenti tutte le operazioni senza approvazione
• "deny": Disabilita lo strumento

Le chiavi di permesso disponibili sono:

read, edit, glob, grep, list, bash, task, external_directory, lsp e skill accettano un'azione abbreviata ("allow" | "ask" | "deny") o un oggetto di glob/pattern → azione per il controllo granulare. Le chiavi rimanenti accettano solo l'azione abbreviata.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puoi sovrascrivere questi permessi per agente.

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

Puoi anche impostare i permessi negli agenti Markdown.

---
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 i permessi per comandi bash specifici.

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

Questo può accettare un pattern glob.

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

E puoi anche usare il carattere jolly * per gestire i permessi per tutti i comandi. Poiché l'ultima regola corrispondente ha la precedenza, metti il carattere jolly * per primo e le regole specifiche dopo.

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

Scopri di più su permessi.

Modalità

Controlla la modalità dell'agente con la configurazione mode. L'opzione mode viene utilizzata per determinare come l'agente può essere utilizzato.

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

L'opzione mode può essere impostata su primary, subagent o all. Se non è specificata alcuna mode, il valore predefinito è all.

Nascosto

Nascondi un subagente dal menu di autocomplete @ con hidden: true. Utile per subagenti interni che dovrebbero essere invocati solo programmaticamente da altri agenti tramite lo strumento Task.

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Questo influisce solo sulla visibilità dell'utente nel menu di autocomplete. Gli agenti nascosti possono comunque essere invocati dal modello tramite lo strumento Task se i permessi lo consentono.

Permessi di attività

Controlla quali subagenti un agente può invocare tramite lo strumento Task con permission.task. Utilizza pattern glob per la corrispondenza flessibile.

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

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

Colore

Personalizza l'aspetto visivo dell'agente nell'interfaccia utente 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.

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Controlla la diversità della risposta con l'opzione top_p. Alternativa alla temperatura per controllare la casualità.

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

Aggiuntivo

Qualsiasi altra opzione che specifichi nella configurazione dell'agente viene passata direttamente come opzione del modello. Per i tier di Dropstone, le opzioni pass-through supportate sono la profondità del ragionamento e la verbosità del testo:

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "dropstone/dropstone-heavy",
      "variant": "xhigh",
      "textVerbosity": "low"
    }
  }
}

Crea agenti

Puoi creare nuovi agenti usando il seguente comando:

dropstone agent create

Questo comando interattivo:

1. Chiederà dove salvare l'agente; globale o specifico del progetto.
2. Descrizione di cosa dovrebbe fare l'agente.
3. Genera un prompt di sistema appropriato e un identificatore.
4. Ti permette di selezionare quali permessi l'agente dovrebbe avere (tutto ciò che non selezioni viene negato).
5. Infine, crea 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 di sola lettura più strumenti di documentazione
• Agente Debug: Focalizzato sull'investigazione con bash e strumenti di lettura abilitati
• Agente Docs: Scrittura di documentazione con operazioni su file ma nessun comando di sistema

Esempi

Ecco alcuni agenti di esempio che potresti trovare utili.

Agente di documentazione

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Auditor di sicurezza

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

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