Agentes

Agentes são assistentes de IA especializados que podem ser configurados para tarefas e fluxos de trabalho específicos. Eles permitem que você crie ferramentas focadas com prompts personalizados, modelos e acesso a ferramentas.

Você pode alternar entre agentes durante uma sessão ou invocá-los com a menção @.

Tipos

Existem dois tipos de agentes no Dropstone: agentes primários e subagentes.

Agentes primários

Agentes primários são os assistentes principais com os quais você interage diretamente. Você pode alternar entre eles usando a tecla Tab ou seu keybind switch_agent configurado. Esses agentes lidam com sua conversa principal. O acesso às ferramentas é configurado via permissões: por exemplo, Build tem todas as ferramentas ativadas enquanto Plan é restrito.

Dropstone vem com dois agentes primários integrados, Build e Plan. Vamos analisá-los abaixo.

Subagentes

Subagentes são assistentes especializados que agentes primários podem invocar para tarefas específicas. Você também pode invocá-los manualmente @ mencionando -os em suas mensagens.

Dropstone vem com dois subagentes integrados, General e Explore. Vamos analisá-los abaixo.

Integrados

Dropstone vem com dois agentes primários integrados e dois subagentes integrados.

Usar build

Modo: primary

Build é o agente primário padrão com todas as ferramentas ativadas. Este é o agente padrão para trabalho de desenvolvimento onde você precisa de acesso total a operações de arquivo e comandos do sistema.

Usar plan

Modo: primary

Um agente restrito projetado para planejamento e análise. Usamos um sistema de permissões para lhe dar mais controle e evitar alterações não intencionais. Por padrão, todos os seguintes são definidos como ask:

• file edits: Todas as gravações, patches e edições
• bash: Todos os comandos bash

Este agente é útil quando você quer que o LLM analise código, sugira alterações ou crie planos sem fazer modificações reais em sua base de código.

Usar general

Modo: subagent

Um agente de propósito geral para pesquisar perguntas complexas e executar tarefas com múltiplas etapas. Tem acesso total a ferramentas (exceto todo), então pode fazer alterações de arquivo quando necessário. Use isso para executar múltiplas unidades de trabalho em paralelo.

Usar explore

Modo: subagent

Um agente rápido e somente leitura para explorar bases de código. Não pode modificar arquivos. Use isso quando você precisa encontrar rapidamente arquivos por padrões, pesquisar código por palavras-chave ou responder perguntas sobre a base de código.

Usar compaction

Modo: primary

Agente do sistema oculto que compacta contexto longo em um resumo menor. Ele é executado automaticamente quando necessário e não é selecionável na interface.

Usar title

Modo: primary

Agente do sistema oculto que gera títulos curtos de sessão. Ele é executado automaticamente e não é selecionável na interface.

Usar summary

Modo: primary

Agente do sistema oculto que cria resumos de sessão. Ele é executado automaticamente e não é selecionável na interface.

Uso

1. Para agentes primários, use a tecla Tab para alternar entre eles durante uma sessão. Você também pode usar seu keybind switch_agent configurado.

2. Subagentes podem ser invocados:

   • Automaticamente por agentes primários para tarefas especializadas com base em suas descrições.

   • Manualmente @ mencionando um subagente em sua mensagem. Por exemplo.

     @general help me search for this function
     

3. Navegação entre sessões: Quando subagentes criam sessões filhas, use session_child_first (padrão: <Leader>+Down) para entrar na primeira sessão filha da sessão pai.

4. Uma vez que você está em uma sessão filha, use:

   • session_child_cycle (padrão: Right) para alternar para a próxima sessão filha
   • session_child_cycle_reverse (padrão: Left) para alternar para a sessão filha anterior
   • session_parent (padrão: Up) para retornar à sessão pai

   Isso permite que você alterne entre a conversa principal e o trabalho especializado do subagente.

Configurar

Você pode personalizar os agentes integrados ou criar os seus próprios através da configuração. Agentes podem ser configurados de duas maneiras:

JSON

Configure agentes em seu arquivo de configuração 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

Você também pode definir agentes usando arquivos markdown. Coloque-os em:

• Global: ~/.config/dropstone/agents/
• Por projeto: .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.

O nome do arquivo markdown se torna o nome do agente. Por exemplo, review.md cria um agente review.

Opções

Vamos analisar essas opções de configuração em detalhes.

Descrição

Use a opção description para fornecer uma breve descrição do que o agente faz e quando usá-lo.

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

Esta é uma opção de configuração obrigatória.

Temperatura

Controle a aleatoriedade e criatividade das respostas do LLM com a configuração temperature.

Valores mais baixos tornam as respostas mais focadas e determinísticas, enquanto valores mais altos aumentam a criatividade e variabilidade.

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

Os valores de temperatura normalmente variam de 0.0 a 1.0:

• 0.0-0.2: Respostas muito focadas e determinísticas, ideais para análise de código e planejamento
• 0.3-0.5: Respostas equilibradas com alguma criatividade, boas para tarefas gerais de desenvolvimento
• 0.6-1.0: Respostas mais criativas e variadas, úteis para brainstorming e exploração

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Se nenhuma temperatura for especificada, Dropstone usa um padrão sensato ajustado para cada tier.

Máximo de passos

Controle o número máximo de iterações agentic que um agente pode executar antes de ser forçado a responder apenas com texto. Isso permite que usuários que desejam controlar custos definam um limite em ações agentic.

Se isso não for definido, o agente continuará iterando até que o modelo escolha parar ou o usuário interrompa a sessão.

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

Quando o limite é atingido, o agente recebe um prompt de sistema especial instruindo-o a responder com um resumo de seu trabalho e tarefas recomendadas restantes.

Desabilitar

Defina como true para desabilitar o agente.

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

Prompt

Especifique um arquivo de prompt de sistema personalizado para este agente com a configuração prompt. O arquivo de prompt deve conter instruções específicas para o propósito do agente.

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

Este caminho é relativo a onde o arquivo de configuração está localizado. Portanto, funciona tanto para a configuração global do Dropstone quanto para a configuração específica do projeto.

Modelo

Use a configuração model para substituir o modelo para este agente. Útil para usar diferentes modelos otimizados para diferentes tarefas. Por exemplo, um modelo mais rápido para planejamento, um modelo mais capaz para implementação.

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

O ID do modelo usa o formato dropstone/<tier>. Use dropstone/dropstone-fast, dropstone/dropstone-pro ou dropstone/dropstone-heavy.

Ferramentas (descontinuado)

tools está descontinuado. Prefira o campo permission do agente para novas configurações, atualizações e controle mais granular.

Permite que você controle quais ferramentas estão disponíveis neste agente. Você pode ativar ou desativar ferramentas específicas definindo-as como true ou false. Na configuração tools de um agente, true é equivalente a {"*": "allow"} permissão e false é equivalente a {"*": "deny"} permissão.

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

Você também pode usar wildcards em entradas legadas tools para controlar múltiplas ferramentas de uma vez. Por exemplo, para desabilitar todas as ferramentas de um servidor MCP:

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

Saiba mais sobre ferramentas.

Permissões

Você pode configurar permissões para gerenciar quais ações um agente pode executar. Cada chave de permissão pode ser definida como:

• "ask": Solicitar aprovação antes de executar a ferramenta
• "allow": Permitir todas as operações sem aprovação
• "deny": Desabilitar a ferramenta

As chaves de permissão disponíveis são:

read, edit, glob, grep, list, bash, task, external_directory, lsp e skill aceitam uma ação abreviada ("allow" | "ask" | "deny") ou um objeto de glob/padrão → ação para controle granular. As chaves restantes aceitam apenas a ação abreviada.

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

Você pode substituir essas permissões por agente.

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

Você também pode definir permissões em agentes 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.

Você pode definir permissões para comandos bash específicos.

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

Isso pode usar um padrão glob.

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

E você também pode usar o wildcard * para gerenciar permissões para todos os comandos. Como a última regra correspondente tem precedência, coloque o wildcard * primeiro e regras específicas depois.

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

Saiba mais sobre permissões.

Modo

Controle o modo do agente com a configuração mode. A opção mode é usada para determinar como o agente pode ser usado.

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

A opção mode pode ser definida como primary, subagent ou all. Se nenhum mode for especificado, o padrão é all.

Oculto

Oculte um subagente do menu de autocomplete @ com hidden: true. Útil para subagentes internos que devem ser invocados apenas programaticamente por outros agentes via ferramenta Task.

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

Isso afeta apenas a visibilidade do usuário no menu de autocomplete. Agentes ocultos ainda podem ser invocados pelo modelo via ferramenta Task se as permissões permitirem.

Permissões de tarefa

Controle quais subagentes um agente pode invocar via ferramenta Task com permission.task. Usa padrões glob para correspondência flexível.

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

Quando definido como deny, o subagente é removido da descrição da ferramenta Task inteiramente, portanto o modelo não tentará invocá-lo.

Cor

Personalize a aparência visual do agente na interface com a opção color. Isso afeta como o agente aparece na interface.

Use uma cor hex válida (por exemplo, #FF5733) ou cor de tema: primary, secondary, accent, success, warning, error, info.

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

Top P

Controle a diversidade de resposta com a opção top_p. Alternativa à temperatura para controlar aleatoriedade.

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Os valores variam de 0.0 a 1.0. Valores mais baixos são mais focados, valores mais altos mais diversos.

Adicional

Qualquer outra opção que você especificar em sua configuração de agente é passada diretamente como opções de modelo. Para os tiers do Dropstone, as opções de passagem suportadas são profundidade de raciocínio e verbosidade de texto:

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

Criar agentes

Você pode criar novos agentes usando o seguinte comando:

dropstone agent create

Este comando interativo irá:

1. Perguntar onde salvar o agente; global ou específico do projeto.
2. Descrição do que o agente deve fazer.
3. Gerar um prompt de sistema apropriado e identificador.
4. Deixar você selecionar quais permissões o agente deve ter (qualquer coisa que você não selecionar é negada).
5. Finalmente, criar um arquivo markdown com a configuração do agente.

Casos de uso

Aqui estão alguns casos de uso comuns para diferentes agentes.

• Agente Build: Trabalho de desenvolvimento completo com todas as ferramentas ativadas
• Agente Plan: Análise e planejamento sem fazer alterações
• Agente Review: Revisão de código com acesso somente leitura mais ferramentas de documentação
• Agente Debug: Focado em investigação com ferramentas bash e read ativadas
• Agente Docs: Escrita de documentação com operações de arquivo mas sem comandos do sistema

Exemplos

Aqui estão alguns agentes de exemplo que você pode achar úteis.

Agente de documentação

---
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 de segurança

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