Criar um Agente Personalizado em TOML
Nesta página
Lição reescrita em 2 de novembro de 2026. Os exemplos anteriores utilizavam chaves que não existem nos ficheiros de agentes (
model,system_prompt,auto_approve) e ferramentas inexistentes (list_dir,edit_file). As chaves e os nomes das ferramentas estão agora alinhados com a referência oficial e o código-fonte do Vibe. Fontes: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Para Além dos Agentes Integrados
Os agentes integrados cobrem personas padrão, mas os seus projetos têm necessidades únicas: uma equipa de pagamentos requer salvaguardas diferentes de uma equipa de documentação. O Vibe permite-lhe criar agentes personalizados colocando um ficheiro .toml em ~/.vibe/agents/ (nível de utilizador) ou ./.vibe/agents/ (nível de projeto, carregado apenas se a pasta for confiável). O comportamento definido num ficheiro é legível, versionável e partilhável, ao contrário de instruções repetidas em cada sessão.
O nome do agente corresponde ao nome do ficheiro: redteam.toml é iniciado com vibe --agent redteam. O nome main está reservado.
Chaves do Ficheiro do Agente
| Chave | Função |
|---|---|
agent_type | "agent" (padrão, selecionável pelo utilizador) ou "subagent" (iniciado apenas por delegação) |
display_name, description | Nome de exibição e descrição; a descrição é obrigatória para um subagente |
instructions | Instruções inline adicionadas após o prompt do sistema (para um subagente, substituem-no) |
system_prompt_id | Nome de um ficheiro Markdown em ~/.vibe/prompts/ ou ./.vibe/prompts/, sem a extensão |
active_model | Alias do modelo a utilizar para este agente |
enabled_tools, disabled_tools | Lista de permissões (allowlist) e lista de bloqueio (blocklist) de ferramentas (nomes exatos, padrões glob ou expressões re:) |
[tools.<tool>] | Permissões por ferramenta: permission = "always", "ask" ou "never", além de allowlist e denylist de prefixos de comando para bash |
safety | Indicador visual apenas (cor da borda de entrada): safe, neutral, destructive, smart ou yolo; não impõe permissões (Lição 3) |
Ferramentas Que Pode Nomear
As ferramentas integradas do Vibe utilizam estes nomes: read_file, write_file, edit (anteriormente search_replace), bash, grep, todo, task (delegação para um subagente), skill, ask_user_question, web_fetch e web_search. As ferramentas de um servidor MCP são nomeadas {server}_{tool} e as ferramentas de conetor são connector_{connector}_{tool}. Um nome de ferramenta mal escrito em enabled_tools não corresponde a nada: verifique a ortografia antes de concluir que um agente “recusa” escrever um ficheiro.
Primeiro Agente: O Planeador
O Vibe não possui um agente plan integrado; a documentação fornece este exemplo de apenas leitura para explorar um repositório e propor um plano antes de qualquer modificação:
# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explores the repository and proposes a plan before any modification."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore the repository and propose a step-by-step implementation plan.
Do not modify any files until the user approves the plan.
"""
[tools.bash]
permission = "ask"
Inicie-o com vibe --agent plan. Assim que o plano for aprovado, prima Shift+Tab para mudar para accept-edits e proceder à execução. Note a ordem do ficheiro: em TOML, qualquer chave escrita após um cabeçalho de tabela como [tools.bash] pertence a essa tabela. Coloque as chaves de nível superior primeiro e os blocos [tools.*] no final.
Um Agente de Documentação
# ~/.vibe/agents/doc-writer.toml
display_name = "Technical Writer"
description = "Writes technical documentation based on source code."
safety = "neutral"
enabled_tools = ["read_file", "grep", "write_file", "edit", "ask_user_question"]
instructions = """
Based on the source code:
1. Write a docstring for every public function.
2. Maintain a structured README with examples.
3. Document required environment variables.
Style: professional, concise, supported by code examples.
"""
[tools.write_file]
permission = "ask"
Pode ler, pesquisar e escrever, mas não pode executar comandos: bash não está na sua lista. Cada criação de ficheiro requer a sua aprovação. Experimente-o num módulo pequeno antes de o aplicar a um repositório inteiro.
Escolher um Modelo de Agente
active_model espera o alias de um modelo configurado. O Vibe inclui um modelo integrado, o Mistral Medium 3.5, com o alias mistral-medium-3.5. Para outro modelo, declare primeiro uma predefinição em config.toml e, em seguida, referencie o seu alias:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# no ficheiro do agente
active_model = "codestral"
Sem active_model, o agente utiliza o modelo da sessão.
Escrever Instruções
Existem dois caminhos. instructions contém texto inline adicionado após o prompt do sistema do Vibe: esta é a abordagem mais simples. system_prompt_id aponta para um ficheiro Markdown na pasta prompts/, útil para prompts longos revistos em revisões de código. Um detalhe comportamental é importante: o prompt de um agente personalizado aplica-se apenas se o selecionar antes da sua primeira mensagem (via --agent ou Shift+Tab). Se mudar de agente a meio da sessão, as suas ferramentas, permissões e modelo aplicam-se imediatamente, mas o seu prompt só entra em vigor após /clear.
Melhores Práticas
Privilégio mínimo em primeiro lugar: dê a um agente apenas as ferramentas de que necessita. Um agente de análise não precisa de write_file; um escritor não precisa de bash. Remover cada ferramenta torna impossível toda uma categoria de erros.
Um agente por responsabilidade em seguida: um ficheiro universal produz respostas medíocres em toda a linha. Três ficheiros direcionados valem mais do que um genérico.
Instruções precisas finalmente: defina o papel exato, as convenções do projeto, o formato de saída esperado e os erros a evitar. Quando um agente dececiona, é quase sempre porque falta um destes quatro pontos.
Pontos-chave
- Um agente personalizado é um ficheiro
.tomlem~/.vibe/agents/ou./.vibe/agents/; o seu nome corresponde ao nome do ficheiro - Chaves úteis:
display_name,description,instructionsousystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Nomes das ferramentas:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelespera um alias de predefinição de modelo (oumistral-medium-3.5, integrado)- Coloque os blocos
[tools.*]no final do ficheiro