Docs/Configuração e automação/Agentes

Papéis, não
personalidades.

Agentes são configurações de trabalho: prompt, modelo e permissões amarrados a um propósito. O build edita, o plan propõe, o explore só lê — e os seus agentes seguem o mesmo contrato.

Disponível agoraReferência /agents1 min de leitura

01Dois tipos

Primários — conduzem a conversa. Alterne com Tab (keybind switch_agent).
Subagentes — invocados pelos primários para tarefas específicas, ou por você com @nome na mensagem. Cada invocação vira uma sessão filha na árvore.

prompt

@general procure onde esse token é validado

Navegação entre sessões filhas: session_child_first (Leader+↓) entra na primeira; ← → circulam entre irmãs; ↑ volta à mãe.

02Os embarcados

Agente	Modo	Contrato
build	primary	Padrão, todas as ferramentas — o trabalho de verdade.
plan	primary	Edits e bash em `ask` por padrão — analisa e propõe sem tocar no código.
general	subagent	Pesquisa e tarefas multi-passo com acesso amplo (sem todo). Paralelize unidades de trabalho.
explore	subagent	Somente leitura, rápido — achar arquivos, buscar código, responder sobre a base.
scout	subagent	Somente leitura para docs externas e dependências — clona repositórios no cache gerenciado.
compaction · title · summary	ocultos	Agentes de sistema: compactação, títulos e resumos. Rodam sozinhos.
checkpoint-writer · dream Exclusivos	ocultos	Exclusivos do MVCode: checkpoints de sessões longas e consolidação de contexto — a base do checkpoint engine Em rollout.

Plan protege por contrato

O plan carrega uma regra exclusiva do MVCode: negação de task para o subagente general — o modo plano não pode escapar do próprio bloqueio disparando um subagente irrestrito.

03Criando os seus

Em JSON na config, ou como arquivo Markdown — o nome do arquivo vira o nome do agente:

.maxvision-code/agents/review.mdmd

---
description: Revisa código por qualidade e boas práticas
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---

Você está em modo de revisão. Foque em qualidade, bugs em
potencial, performance e segurança. Não faça mudanças diretas.

Ou pela CLI, que guia a criação e nega tudo que você não permitir:

terminal

mvcode agent create

04Opções

descriptionstringobrigatório

O que o agente faz e quando usá-lo — é o que os primários leem para decidir invocar.

modeprimary · subagent · allall

Como o agente pode ser usado. hidden: true esconde subagentes do autocomplete @ (invocáveis só via task).

modelprovider/model

Sem override, primários usam o modelo global; subagentes herdam do primário que os invocou.

promptstring · {file:…}

System prompt do agente — arquivos relativos à config funcionam no escopo global e no do projeto.

permissionobjeto

allow / ask / deny por chave — inclusive padrões por comando bash e por glob. A referência completa está em permissões.

temperature · top_pnumberpor modelo

0.0–0.2 para análise determinística; 0.6+ para brainstorm. top_p é a alternativa por diversidade.

stepsnumberilimitado

Máximo de iterações agênticas antes de forçar resposta em texto — controle de custo. (O legado maxSteps está deprecado.)

colorhex · nome de tema

Cor do agente na UI — o dot que identifica quem está falando.

disableboolean

Desliga o agente sem apagar a definição — os embutidos também aceitam.

Opções extras passam direto ao provedor como opções de modelo — reasoningEffort, textVerbosity e afins.

05Quem pode invocar quem

permission.task controla quais subagentes um agente dispara — a última regra que casa vence:

maxvision-code.jsonjson

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Com deny, o subagente sai da descrição da ferramenta task — o modelo nem tenta. Você, pelo @, sempre pode.

06Especialistas assíncronos Em rollout

Atrás da flag experimentalBackgroundSubagents, subagentes ganham vida longa:

Execução em background — o primário segue trabalhando enquanto o especialista roda; o resultado chega como evento (e como push).
Especialistas nomeados — specialist_name reusa a mesma sessão de especialista entre turnos, preservando o contexto dele.
Mailbox agent-to-agent — mensagens duráveis entre sessões via send-agent-message / wait-agent-message, com mode: any | all e timeouts explícitos. A caixa é consultável pela API.

07Gerenciando pela UI

O diálogo de agentes do app lista os definidos, com set-default (default_agent) e enable/disable — mudanças gravam na config global e valem na hora. Implementado

Papéis, nãopersonalidades.