Subagentes: Delegar Tarefas Especializadas
Nesta página
Lição atualizada em 2 de novembro de 2026. Os ficheiros de exemplo de agentes utilizam agora as chaves documentadas pela Vibe:
instructions(em vez desystem_prompt),active_model(em vez demodel), blocos[tools.<tool>]para aprovações (a chaveauto_approvenão existe num ficheiro de agente) e nomes reais de ferramentas (edit, e nãoedit_file; sem a ferramentalist_dir). Lembrete da Lição 3:safetyé um indicador visual, não uma permissão. Fonte: Referência de configuração.
O Princípio da Delegação
Em projetos complexos, certas tarefas são independentes umas das outras: analisar a segurança de um ficheiro enquanto outro processo gera testes. Em vez de tratar tudo sequencialmente, o Mistral Vibe permite-lhe delegar tarefas a subagentes. Um subagente é um agente que corre de forma independente, completa a sua missão e devolve um resultado em texto ao agente principal. Não pode fazer perguntas ao utilizador: tem de ser totalmente autónomo.
Esta restrição é a chave de tudo o que se segue e merece detalhe. Um subagente executa no seu próprio contexto, sem acesso à conversa atual — não sabe nada do que explicou ao agente principal há cinco minutos. Não pode usar ask_user_question e deve gerir a ambiguidade por si só. Devolve texto que o agente principal integra depois na sua resposta. Como está isolado da troca, só faz sentido quando desenhado para uma tarefa específica e bem definida.
Configurar um Subagente
Para transformar um agente num subagente, adicione o campo agent_type = "subagent" ao ficheiro .toml. O restante da configuração segue as regras habituais para agentes personalizados.
# ~/.vibe/agents/test-generator.toml
display_name = "Test Generator"
description = "Generates unit tests for given functions."
agent_type = "subagent"
safety = "neutral"
active_model = "codestral" # alias declared in config.toml (Lesson 2)
instructions = """
You receive source code. Generate comprehensive unit tests:
- Nominal case tests
- Edge case tests (null, undefined, empty strings)
- Expected error tests
Framework: Use the project's test framework (Jest, Vitest, Pytest...).
Return only the test code, ready to copy.
"""
enabled_tools = [
"read_file",
"grep",
]
Note a ausência de ask_user_question nas ferramentas: não é um esquecimento. Um subagente não pode pedir esclarecimentos, e o prompt do sistema compensa esta impossibilidade especificando antecipadamente a estrutura de testes a usar e o formato exato da resposta.
Casos de Uso Concretos
O primeiro benefício é o trabalho em paralelo. O agente principal pode atribuir múltiplas tarefas simultaneamente a diferentes subagentes, cada um trabalhando no seu âmbito antes de devolver o seu resultado.
Main Agent
├── Subagent "test-generator" → generates tests
├── Subagent "doc-writer" → generates documentation
└── Subagent "security-checker" → analyzes vulnerabilities
O segundo benefício diz respeito a tarefas altamente especializadas. Algumas exigem um prompt do sistema radicalmente diferente do agente principal; em vez de sobrecarregar um único agente com instruções contraditórias, delega-se. O otimizador de SQL abaixo é um bom exemplo: o seu prompt fala apenas de índices, planos de execução e consultas N+1, o que não faria sentido num agente generalista.
# ~/.vibe/agents/sql-optimizer.toml
display_name = "SQL Optimizer"
description = "Analyzes and optimizes SQL queries."
agent_type = "subagent"
safety = "safe"
active_model = "mistral-medium-3.5" # model built into Vibe
instructions = """
Analyze the provided SQL queries:
1. Identify performance issues (N+1, full scan, missing index)
2. Propose optimized queries
3. Suggest indexes to create
Return a structured report with before/after for each query.
"""
enabled_tools = ["read_file", "grep"]
O terceiro benefício, menos óbvio, é o isolamento de segurança. Um subagente com safety = "safe" não pode modificar ficheiros, mesmo que o agente principal corra em modo destructive: as permissões não se herdam para baixo. Pode, portanto, trabalhar num modo permissivo enquanto confia análises a subagentes restritos que não têm qualquer forma de atuar no repositório.
# Subagent that can ONLY read
agent_type = "subagent"
safety = "safe"
enabled_tools = ["read_file", "grep"]
[tools.read_file]
permission = "always"
[tools.grep]
permission = "always"
A Vibe fornece também um subagente incorporado explore, que utiliza automaticamente quando precisa de percorrer a sua base de código para responder a uma pergunta. Opera em modo só de leitura e devolve um resumo do que encontrou — exatamente o padrão que replica com os seus próprios subagentes.
Desenhar um Bom Subagente
Tudo depende da autonomia do prompt do sistema: deve conter todas as instruções necessárias para o subagente chegar ao fim sem nunca fazer uma pergunta. Isto exige antecipar casos em que as coisas correm mal e escrever exatamente o que o agente deve fazer nessas situações, como no exemplo seguinte.
instructions = """
Analyze ALL TypeScript files in the project.
If a file is not found, move to the next one.
If the test framework is not identifiable, use Vitest by default.
Always return a result, even if partial.
"""
Dois reflexos completam este trabalho. Dê ao subagente estritamente as ferramentas de que precisa — um subagente de análise não precisa de write_file — e especifique o formato de saída esperado no prompt do sistema. O agente principal deve poder explorar o resultado sem ambiguidade: é ele, e não si, que lerá primeiro este texto.
Regras Definidas pela Vibe
A documentação da Vibe especifica várias regras que vale a pena conhecer antes de desenhar os seus subagentes:
- um subagente devolve apenas texto ao agente principal e não pode fazer perguntas ao utilizador;
- só pode usar as ferramentas incorporadas que o seu ficheiro autoriza, nunca ferramentas MCP, conectores ou plugins, e nunca com permissões mais amplas do que o agente pai: os seus blocos
[tools.<tool>]podem restringi-lo ainda mais, não expandi-lo; - a sua
descriptioné obrigatória: isto indica ao agente quando o deve usar; um ficheiro sem descrição é sinalizado em vez de carregado; - corre no seu
active_model, ou no modelo da sessão se nenhum estiver definido; - o agente principal lança-o via delegação, usando a ferramenta
task; não é selecionado com--agent; - por defeito, podem existir e correr simultaneamente até 32 subagentes (
max_subagents,max_concurrent_subagents), eenable_subagents = falseemconfig.tomlproíbe toda a delegação.
Sem um subagente personalizado, o agente pode ainda lançar um subagente genérico equipado com as suas próprias instruções e ferramentas.
Pontos-chave
- Um subagente é um agente independente que não pode interagir com o utilizador
- Configure-o com
agent_type = "subagent"no ficheiro.toml - Os subagentes são ideais para trabalho em paralelo e tarefas especializadas
- Oferecem isolamento de segurança natural
- As
instructionsdevem ser totalmente autónomas: perguntas não permitidas - Especifique sempre um formato de saída claro no prompt