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, modelos e acesso a ferramentas personalizados.

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 principais assistentes com os quais você interage diretamente. Você pode alternar entre eles usando a tecla Tab ou o keybind switch_agent configurado. Esses agentes lidam com sua conversa principal. O acesso às ferramentas é configurado por meio de permissões: por exemplo, o Build tem todas as ferramentas habilitadas, enquanto o Plan é restrito.

O 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 com @ em suas mensagens.

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

Integrados

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

Usar build

Mode: primary

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

Usar plan

Mode: primary

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

• file edits: Todas as escritas, 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 nenhuma modificação real no seu código.

Usar general

Mode: subagent

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

Usar explore

Mode: subagent

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

Usar compaction

Mode: primary

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

Mode: primary

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

Usar summary

Mode: primary

Agente de 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 o 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 com @ um subagente em sua mensagem. Por exemplo.

     @general me ajude a pesquisar por esta função
     

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 a partir da sessão pai.

4. Uma vez 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 por meio da configuração. Os agentes podem ser configurados de duas maneiras:

JSON

Configure agentes no 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": "Revisa código em busca de boas práticas e problemas potenciais",
      "mode": "subagent",
      "model": "dropstone/dropstone-pro",
      "prompt": "Você é um revisor de código. Foque em segurança, desempenho e manutenibilidade.",
      "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: Revisa código em busca de qualidade e boas práticas
mode: subagent
model: dropstone/dropstone-pro
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

Você está no modo de revisão de código. Foque em:

- Qualidade do código e boas práticas
- Bugs potenciais e casos extremos
- Implicações de desempenho
- Considerações de segurança

Forneça feedback construtivo sem fazer alterações diretas.

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": "Revisa código em busca de boas práticas e problemas potenciais"
    }
  }
}

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 a 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, o Dropstone usa um padrão sensato ajustado para cada nível.

Máximo de etapas

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

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

{
  "agent": {
    "quick-thinker": {
      "description": "Raciocínio rápido com iterações limitadas",
      "prompt": "Você é um pensador rápido. Resolva problemas com etapas mínimas.",
      "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 restantes recomendadas.

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 ao local onde o arquivo de configuração está. Portanto, isso 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 deste 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 (obsoleto)

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

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

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

Você também pode usar curingas em entradas tools legadas para controlar várias ferramentas ao mesmo tempo. 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 realizar. 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 refinado. 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: Revisão de código sem edições
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Apenas analise código e sugira alterações.

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 aceitar um padrão glob.

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

E você também pode usar o curinga * para gerenciar permissões para todos os comandos. Como a última regra correspondente tem precedência, coloque o curinga * primeiro e as 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 autocompletar @ com hidden: true. Útil para subagentes internos que devem ser invocados apenas programaticamente por outros agentes por meio da ferramenta Task.

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

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

Permissões de tarefa

Controle quais subagentes um agente pode invocar por meio da 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 completamente da descrição da ferramenta Task, então 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 a 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 são mais diversos.

Adicional

Quaisquer outras opções que você especificar na configuração do seu agente são passadas diretamente como opções de modelo. Para os níveis do Dropstone, as opções de passagem suportadas são profundidade de raciocínio e verbosidade de texto:

{
  "agent": {
    "deep-thinker": {
      "description": "Agente que usa alto esforço de raciocínio para problemas complexos",
      "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 e identificador apropriados.
4. Permitir que você selecione 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 habilitadas
• Agente Plan: Análise e planejamento sem fazer alterações
• Agente Review: Revisão de código com acesso somente leitura e ferramentas de documentação
• Agente Debug: Focado em investigação com ferramentas bash e leitura habilitadas
• Agente Docs: Escrita de documentação com operações de arquivo, mas sem comandos de sistema

Exemplos

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

Agente de documentação

---
description: Escreve e mantém documentação do projeto
mode: subagent
permission:
  bash: deny
---

Você é um redator técnico. Crie documentação clara e abrangente.

Foque em:

- Explicações claras
- Estrutura adequada
- Exemplos de código
- Linguagem amigável ao usuário

Auditor de segurança

---
description: Realiza auditorias de segurança e identifica vulnerabilidades
mode: subagent
permission:
  edit: deny
---

Você é um especialista em segurança. Foque em identificar problemas de segurança potenciais.

Procure por:

- Vulnerabilidades de validação de entrada
- Falhas de autenticação e autorização
- Riscos de exposição de dados
- Vulnerabilidades de dependências
- Problemas de segurança de configuração