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

Criar um Agente Personalizado em TOML

Aula 2 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Para Além dos Agentes Integrados
  2. Chaves do Ficheiro do Agente
  3. Ferramentas Que Pode Nomear
  4. Primeiro Agente: O Planeador
  5. Um Agente de Documentação
  6. Escolher um Modelo de Agente
  7. Escrever Instruções
  8. Melhores Práticas
  9. Pontos-chave

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

ChaveFunção
agent_type"agent" (padrão, selecionável pelo utilizador) ou "subagent" (iniciado apenas por delegação)
display_name, descriptionNome de exibição e descrição; a descrição é obrigatória para um subagente
instructionsInstruções inline adicionadas após o prompt do sistema (para um subagente, substituem-no)
system_prompt_idNome de um ficheiro Markdown em ~/.vibe/prompts/ ou ./.vibe/prompts/, sem a extensão
active_modelAlias do modelo a utilizar para este agente
enabled_tools, disabled_toolsLista 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
safetyIndicador 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 .toml em ~/.vibe/agents/ ou ./.vibe/agents/; o seu nome corresponde ao nome do ficheiro
  • Chaves úteis: display_name, description, instructions ou system_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_model espera um alias de predefinição de modelo (ou mistral-medium-3.5, integrado)
  • Coloque os blocos [tools.*] no final do ficheiro