Agents

Gli agenti sono assistenti AI specializzati che possono essere configurati per attività e flussi di lavoro specifici. Ti permettono di creare strumenti mirati con prompt, modelli e accesso agli strumenti personalizzati.

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

Tipi

In Dropstone 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 il tuo keybind switch_agent configurato. Questi agenti gestiscono la tua conversazione principale. L'accesso agli strumenti è configurato tramite le autorizzazioni: ad esempio, Build ha tutti gli strumenti abilitati mentre Plan è limitato.

Dropstone include due agenti primari integrati, Build e Plan. Li esamineremo qui di seguito.

Subagenti

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

Dropstone include due subagenti integrati, General e Explore. Li esamineremo qui di seguito.

Integrati

Dropstone include due agenti primari integrati e due subagenti integrati.

Usa build

Mode: primary

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

Usa plan

Mode: primary

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

• file edits: Tutte le scritture, 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 devi trovare rapidamente file tramite pattern, cercare codice per parole chiave o rispondere a domande sul codebase.

Usa compaction

Mode: primary

Agente di sistema nascosto che compatta contesti lunghi in un riepilogo più piccolo. Viene eseguito automaticamente quando necessario e non è selezionabile nell'interfaccia.

Usa title

Mode: primary

Agente di sistema nascosto che genera titoli brevi per le sessioni. Viene eseguito automaticamente e non è selezionabile nell'interfaccia.

Usa summary

Mode: primary

Agente di sistema nascosto che crea riepiloghi delle sessioni. Viene eseguito automaticamente e non è selezionabile nell'interfaccia.

Utilizzo

1. Per gli agenti primari, usa il tasto Tab per scorrerli 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 menzionandoli con @ nel tuo messaggio. Ad esempio.

     @general help me search for this function
     

3. Navigazione tra le 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 in una sessione figlia, usa:

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

   Questo ti permette di passare dalla conversazione principale al lavoro specializzato dei subagenti.

Configurazione

Puoi personalizzare gli agenti integrati o crearne di tuoi tramite 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ù mirate e deterministiche, mentre valori più alti aumentano creatività e 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 mirate e deterministiche, ideali per analisi del codice e pianificazione
• 0.3-0.5: Risposte equilibrate con un po' di creatività, buone per attività di sviluppo generali
• 0.6-1.0: Risposte più creative e variegate, utili per brainstorming ed 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 viene specificata una temperatura, Dropstone usa un valore predefinito sensato ottimizzato per ogni livello.

Passi 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 vogliono controllare i costi di impostare un limite alle azioni agentiche.

Se non è impostato, l'agente continuerà a iterare finché il modello non sceglie di fermarsi o l'utente non 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 ordina di rispondere con un riepilogo del suo lavoro e delle attività rimanenti consigliate.

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 alla posizione del file di configurazione. Quindi funziona sia per la configurazione globale di Dropstone che per quella specifica del progetto.

Modello

Usa la configurazione model per sovrascrivere il modello per questo agente. Utile per usare modelli diversi ottimizzati per attività diverse. 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 usa 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 nuove configurazioni, 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 equivale all'autorizzazione {"*": "allow"} e false equivale a {"*": "deny"}.

{
  "$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 tools legacy per controllare più strumenti contemporaneamente. Ad esempio, per disabilitare tutti gli strumenti di un server MCP:

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

Scopri di più sugli strumenti.

Autorizzazioni

Puoi configurare le autorizzazioni per gestire quali azioni un agente può eseguire. Ogni chiave di autorizzazione 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 autorizzazione disponibili sono:

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

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

Puoi sovrascrivere queste autorizzazioni per ogni agente.

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

Puoi anche impostare le autorizzazioni 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 autorizzazioni 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 le autorizzazioni 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ù sulle autorizzazioni.

Modalità

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

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

L'opzione mode può essere impostata su primary, subagent o all. Se non viene specificata alcuna mode, il valore predefinito è 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.

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

Questo influisce solo sulla visibilità per l'utente nel menu di autocompletamento. Gli agenti nascosti possono comunque essere invocati dal modello tramite lo strumento Task se le autorizzazioni lo consentono.

Autorizzazioni Task

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

{
  "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 tenterà di invocarlo.

Colore

Personalizza l'aspetto visivo dell'agente nell'interfaccia con l'opzione color. Questo influisce su come l'agente appare nell'interfaccia.

Usa un colore hex valido (ad esempio, #FF5733) o un colore del tema: primary, secondary, accent, success, warning, error, info.

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

Top P

Controlla la diversità delle risposte 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ù mirati, valori più alti più diversificati.

Ulteriori

Qualsiasi altra opzione che specifichi nella configurazione dell'agente viene passata direttamente come opzione del modello. Per i livelli di Dropstone, le opzioni pass-through supportate sono la profondità di 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"
    }
  }
}

Creare agenti

Puoi creare nuovi agenti usando il seguente comando:

dropstone agent create

Questo comando interattivo:

1. Chiede dove salvare l'agente; globale o specifico del progetto.
2. La descrizione di cosa dovrebbe fare l'agente.
3. Genera un prompt di sistema e un identificatore appropriati.
4. Ti permette di selezionare quali autorizzazioni dovrebbe avere l'agente (qualsiasi cosa non selezioni viene negata).
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'indagine con strumenti bash e di lettura abilitati
• Agente Docs: Scrittura di documentazione con operazioni sui file ma nessun comando di sistema

Esempi

Ecco alcuni esempi di agenti 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