Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Subagentes: Delegar Tarefas Especializadas

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O Princípio da Delegação
  2. Configurar um Subagente
  3. Casos de Uso Concretos
  4. Desenhar um Bom Subagente
  5. Regras Definidas pela Vibe
  6. Pontos-chave

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 de system_prompt), active_model (em vez de model), blocos [tools.<tool>] para aprovações (a chave auto_approve não existe num ficheiro de agente) e nomes reais de ferramentas (edit, e não edit_file; sem a ferramenta list_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), e enable_subagents = false em config.toml proí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 instructions devem ser totalmente autónomas: perguntas não permitidas
  • Especifique sempre um formato de saída claro no prompt