Agentes e subagentes

Toda sessão do Jarvis Code CLI é conduzida por um agente principal. O agente principal entende a intenção do usuário, planeja etapas, chama ferramentas e, quando necessário, despacha subagentes para tratar subtarefas mais focadas — por exemplo, explorar uma base de código desconhecida, revisar várias implementações em paralelo ou planejar uma refatoração grande sem tocar no contexto principal.

Um subagente recebe uma descrição de tarefa do agente principal, trabalha em seu próprio contexto isolado e então devolve suas conclusões. Ele não se comunica diretamente com o usuário, e seu raciocínio intermediário e seus registros de chamada de ferramenta não se misturam ao histórico do agente principal.

Subagentes embutidos

O Jarvis Code CLI inclui três subagentes embutidos, prontos para uso, cada um voltado a um formato de tarefa diferente:

• coder: o subagente padrão — um assistente de engenharia de software de uso geral que pode ler e escrever arquivos, executar comandos, buscar código e concretizar mudanças.
• explore: dedicado à exploração de base de código; realiza apenas operações de leitura e não modifica arquivo algum. Ideal para buscar, ler e resumir um repositório rapidamente sem tocar em arquivos.
• plan: dedicado a planejamento de implementação e desenho de arquitetura; nem comandos de shell estão disponíveis, mantendo o foco em "descobrir como fazer" em vez de "efetivamente fazer".

Um subagente coder compartilha a maior parte do conjunto de ferramentas do agente principal: pode executar comandos de shell em segundo plano, manter listas de tarefas, entrar no Plan mode (modo de planejamento) e invocar Agent Skills. Subagentes embutidos não podem despachar outros subagentes. Por padrão, um agente personalizado herda a lista de delegação embutida (coder, explore, plan), cujos membros também não podem despachar adiante, então cadeias de delegação sempre terminam — geração recursiva ilimitada é impossível sem uma escolha explícita. Um agente personalizado pode optar por cadeias mais profundas declarando uma lista subagents explícita. Se um subagente termina seu turno enquanto tarefas em segundo plano ainda rodam, a execução dele só reporta conclusão depois que essas tarefas se resolvem, então o chamador recebe o resultado depois de o trabalho subjacente realmente terminar.

Como invocar

Subagentes são agendados automaticamente pelo agente principal — com base na complexidade da tarefa, no consumo de contexto e na independência da subtarefa, eles são despachados no momento certo sem o usuário precisar especificar.

Cada despacho é apresentado no terminal como um pedido de aprovação (a menos que corresponda a uma regra de allow ou o YOLO mode esteja ativo), dando a você a chance de revisar a descrição da tarefa. Você também pode instruir o agente principal diretamente na conversa a usar um subagente específico, por exemplo: "Use o explore para mapear os arquivos relevantes antes de fazer qualquer mudança."

Subagentes podem rodar em segundo plano: os resultados voltam automaticamente ao agente principal na conclusão, sem necessidade de consulta manual. Você também pode retomar uma instância de subagente existente para continuar a mesma tarefa.

Isolamento de contexto e custo de recursos

Cada subagente tem uma janela de contexto totalmente independente. Ele só enxerga a descrição de tarefa passada explicitamente pelo agente principal e não vê o histórico de conversa do agente principal. O raciocínio intermediário e os registros de chamada de ferramenta do próprio subagente não retornam; apenas o resultado final aparece no contexto do agente principal.

Esse isolamento traz dois benefícios:

• O contexto do agente principal permanece enxuto e não é preenchido por grandes volumes de logs exploratórios em sessões longas.
• Vários subagentes podem rodar em paralelo sem interferir entre si.

Note que cada subagente consome tokens de modelo de forma independente. Para tarefas simples, não é preciso despachar um subagente — o agente principal as resolve de forma mais econômica.

Herança de permissões

Regras de permissão de subagente são herdadas do agente principal: regras de "sempre permitir" que o agente principal aceitou por /permission ou por um diálogo de aprovação se propagam automaticamente a todos os subagentes que ele despacha, então subagentes não precisam reaprovar os mesmos tipos de chamada de ferramenta. A própria ferramenta Agent é permitida por padrão, permitindo ao agente principal delegar várias vezes sem interromper o usuário.

Se você precisa que um tipo de ferramenta fique permanentemente indisponível dentro de subagentes, restrinja a regra de permissão correspondente no agente principal.

Agentes personalizados

Além dos três subagentes embutidos, você pode definir seus próprios agentes como arquivos Markdown. Cada arquivo descreve um agente: o frontmatter (metadados YAML no topo do arquivo) declara nome, descrição e acesso a ferramentas, e o corpo do arquivo é o system prompt dele. Agentes personalizados podem receber delegação como subagentes — o agente principal os descobre automaticamente ao lado dos embutidos — ou ser selecionados como agente principal na inicialização.

Locais de agente

O Jarvis Code CLI descobre arquivos de agente por escopo; escopos mais específicos têm prioridade maior: Explícito (--agent-file) > Projeto > Extra > Usuário > Plugin > Embutido. Quando dois arquivos definem o mesmo name, vence o escopo de prioridade maior. Cada diretório é varrido recursivamente em busca de arquivos .md.

Nível de usuário (vale para todos os projetos):

• $JARVIS_CODE_HOME/agents/ (padrão: ~/.jarvis-code/agents/)
• ~/.agents/agents/

O diretório de agentes de usuário específico do Jarvis Code acompanha JARVIS_CODE_HOME, enquanto o diretório genérico ~/.agents/agents/ permanece no home real do sistema operacional, para ser compartilhado entre ferramentas.

Nível de projeto (raiz do projeto = o diretório mais próximo que contém .git, subindo a partir do diretório de trabalho):

• .jarvis-code/agents/
• .agents/agents/

Diretórios extras: declarados por extra_agent_dirs no nível superior do config.toml:

extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]

Nível de plugin: diretórios declarados no campo agents do manifesto de um plugin habilitado (quando omitido, o diretório agents/ na raiz do plugin é usado automaticamente); veja Agentes de plugin. Agentes de plugin superam apenas os agentes embutidos.

Agentes embutidos são distribuídos com o CLI e têm a prioridade mais baixa. Um arquivo descoberto em diretório não sobrescreve um agente embutido de mesmo nome, a menos que seu frontmatter declare override: true. Um arquivo carregado por --agent-file é tratado como intenção explícita de inicialização, pode sobrescrever um agente embutido de mesmo nome, supera todos os escopos de diretório e vale apenas para a execução atual. Separadamente, $JARVIS_CODE_HOME/SYSTEM.md sobrescreve permanentemente o system prompt do agente principal padrão (ele não faz parte da descoberta de arquivos de agente); suas interações de precedência estão na seção SYSTEM.md abaixo.

Modelo de confiança

Arquivos de agente são configuração de prompt, e arquivos de nível de projeto vêm do próprio repositório — inclusive de repositórios que você acabou de clonar e ainda não conhece. Um arquivo de escopo de projeto pode assumir um agente embutido por inteiro: nomeá-lo agent.md com override: true substitui todo o system prompt do agente principal padrão, e coder.md com override: true substitui o tipo de subagente padrão. Diferente do conteúdo de AGENTS.md — que é injetado no prompt como dado de referência — um arquivo de override é o system prompt, e um arquivo sem lista tools mantém todas as ferramentas. Revise .jarvis-code/agents/ e .agents/agents/ em repositórios desconhecidos com o mesmo cuidado que você aplicaria a scripts, antes de rodar o Jarvis Code dentro deles.

Formato do arquivo de agente

Um arquivo de agente é Markdown puro com um bloco de frontmatter:

---
name: reviewer
description: Revisor de código rigoroso que reporta achados ordenados por severidade
whenToUse: Revisões de código e checagens de PR
override: false
tools:
  - Read
  - Grep
  - Glob
  - mcp__github__*
disallowedTools:
  - Bash
---

Você é um revisor de código rigoroso. Leia o diff e reporte os achados agrupados por severidade…

Campo	Obrigatório	Descrição
name	não	Identificador único em kebab-case. O padrão é o nome do arquivo sem extensão (review.md → review); um arquivo cujo nome resolvido esteja ausente ou não seja kebab-case é ignorado com um aviso
description	sim	O que o agente faz. Mostrado ao agente principal quando ele escolhe um subagente, então escreva pensando em orientar as decisões de delegação
whenToUse	não	Dica extra descrevendo quando o agente deve ser usado
override	não	Se este arquivo pode substituir um agente embutido de mesmo nome. O padrão é false; o --agent-file já é explícito e não exige este campo
tools	não	Lista de nomes de ferramenta permitidos, como Read ou Bash; ferramentas MCP são correspondidas por globs como mcp__github__*. Aceita uma lista YAML ou uma string separada por vírgulas (tools: Read, Grep). Omita para permitir todas as ferramentas; um * sozinho também permite todas; uma lista vazia (tools: []) desabilita todas
disallowedTools	não	Lista de bloqueio com a mesma sintaxe e as mesmas regras de correspondência, aplicada depois de tools
subagents	não	Lista de nomes de subagente a que este agente pode delegar, com a mesma sintaxe de tools (lista YAML ou string separada por vírgulas). Omita para herdar a lista do agente padrão (padrão embutido: coder, explore, plan, cujos membros não podem delegar adiante, então cadeias herdadas sempre terminam); um * sozinho permite todos os tipos. A lista efetiva do agente principal inclui adicionalmente todo agente personalizado descoberto, então agentes personalizados continuam delegáveis por padrão

Ferramentas embutidas e de usuário são correspondidas por nome exato, diferenciando maiúsculas de minúsculas; entradas que começam com mcp__ correspondem a ferramentas MCP como globs. Três formatos de entrada nunca correspondem a nada e são reportados com um aviso quando o perfil entra em vigor: um curinga fora de um padrão mcp__ (um * sozinho em disallowedTools não desabilita nada), um literal mcp__ que não seja um nome completo mcp__<server>__<tool> (mcp__github não corresponde a nada — use mcp__github__* para o servidor inteiro) e um nome que nenhuma ferramenta registrada ou embutida possui (normalmente um erro de digitação, como read em vez de Read).

O corpo é o system prompt do agente, e é renderizado como template cada vez que o prompt é construído: marcadores ${var} substituem valores do contexto ao vivo — variáveis desconhecidas permanecem literais, um $ isolado nunca é especial, e uma variável sem valor de contexto renderiza como string vazia. O ${base_prompt} incorpora o system prompt padrão efetivo (o padrão embutido, ou a sua sobrescrita SYSTEM.md quando presente), então um arquivo pode envolver o comportamento padrão em vez de substituí-lo. Se o arquivo substitui o prompt padrão mas ainda deve honrar instruções contribuídas por plugins habilitados, coloque ${plugin_sections} onde essas instruções devem aparecer. As variáveis disponíveis estão listadas na seção SYSTEM.md abaixo.

Campos desconhecidos são ignorados, então arquivos mais novos continuam legíveis por versões antigas. Campos de outras ferramentas de agente (como o model do Claude Code ou o mode do OpenCode) são ignorados da mesma forma, a forma de tools separada por vírgulas mantém arquivos de agente no estilo Claude Code carregáveis, e um name ausente recorre ao nome do arquivo, então arquivos no estilo OpenCode também carregam — um arquivo mínimo com description e um corpo funciona entre ferramentas.

Um arquivo com conteúdo inválido descoberto em um diretório é ignorado com um aviso e não afeta os demais. Um arquivo passado explicitamente por --agent-file precisa ser válido — caso contrário o CLI reporta o erro e encerra.

Nota

tools e disallowedTools moldam as ferramentas mostradas ao modelo e são aplicados novamente antes da execução. O subagents funciona do mesmo jeito: a ferramenta Agent lista apenas os tipos de subagente a que o chamador pode delegar, e tanto Agent quanto AgentSwarm reverificam a lista antes de despachar; retomar um subagente existente é isento. Regras de permissão continuam sendo um controle separado para operações que exigem aprovação.

Agentes personalizados usados como subagentes rodam sem o enquadramento embutido de subagente ("sua última mensagem é todo o repasse"). Se você escrever um agente destinado a delegação, declare no corpo que a última mensagem dele deve ser o resultado completo e autocontido para quem chamou.

Selecionar o agente principal

Duas flags de CLI selecionam qual agente conduz uma nova sessão, tanto no modo de prompt (jarvis -p) quanto na TUI interativa:

• --agent <name>: inicia a sessão com o agente informado como agente principal. O nome pode se referir a um agente embutido ou a qualquer arquivo descoberto; um nome desconhecido falha com um erro listando os agentes disponíveis.
• --agent-file <path>: carrega um arquivo de agente com a prioridade mais alta nesta execução e inicia com ele. A flag aceita exatamente um arquivo: não pode ser repetida nem combinada com --agent.

Ambas as flags valem apenas ao iniciar uma nova sessão — nenhuma delas pode ser combinada com --session ou --continue. O agente é vinculado na criação da sessão, e retomar restaura o agente vinculado automaticamente, então nenhuma flag é necessária (nem permitida) na retomada.

Por exemplo:

jarvis --agent reviewer
jarvis -p --agent reviewer "Revise as mudanças deste branch"

O agente vinculado é a identidade da sessão: ele é fixado no primeiro vínculo da sessão e não pode ser trocado depois. Na TUI, as flags vinculam apenas a sessão de inicialização; uma sessão criada depois no mesmo processo (por exemplo, por /new) começa com o agente padrão.

Para personalizar o agente principal, referencie ${base_prompt} no corpo para que as injeções de ambiente, de instruções de workspace, de skills e de plugins já presentes no prompt padrão efetivo continuem valendo. Quando quiser substituir o prompt padrão mas manter apenas as instruções contribuídas por plugins, use ${plugin_sections}. Um corpo sem ${base_prompt} nem ${plugin_sections} é dono do prompt inteiro e exclui instruções de plugin, o que combina com subagentes autocontidos.

Sobrescrever o system prompt do agente principal com SYSTEM.md

Para sobrescrever o system prompt do agente principal de forma permanente — sem passar --agent ou --agent-file a cada execução — escreva um arquivo $JARVIS_CODE_HOME/SYSTEM.md (padrão: ~/.jarvis-code/SYSTEM.md; ele acompanha JARVIS_CODE_HOME). Enquanto o arquivo existir e não estiver vazio, ele substitui integralmente o system prompt do agente principal padrão — e apenas o prompt: descrição, conjunto de ferramentas e lista de delegação a subagentes são herdados dos padrões embutidos. O SYSTEM.md vale em todos os modos de inicialização, inclusive em sessões interativas da TUI.

O SYSTEM.md é um corpo Markdown puro — nenhum frontmatter é exigido nem lido. Um arquivo ausente ou vazio não tem efeito, e uma falha de leitura recorre ao prompt embutido com um aviso. A intenção explícita ainda o supera: um arquivo de agente de escopo de projeto com mesmo nome declarando override: true e qualquer arquivo passado por --agent-file têm precedência, e selecionar outro agente com --agent o ignora por completo. Dentro do próprio escopo de usuário, o SYSTEM.md vence um arquivo de mesmo nome descoberto nos diretórios agents/.

Como o corpo de um arquivo de agente comum, o SYSTEM.md é renderizado como template cada vez que o prompt é construído — marcadores ${var} no corpo são substituídos pelo contexto ao vivo:

Variável	Conteúdo
${product_name}	Nome do produto usado pelo prompt embutido; o padrão é Jarvis Code CLI
${skills}	A injeção combinada de Agent Skills; vazia quando a ferramenta Skill não está disponível
${agents_md}	Conteúdo dos arquivos de instrução do workspace (como AGENTS.md)
${cwd}	Diretório de trabalho atual
${cwd_listing}	Listagem do diretório de trabalho
${os}	Tipo de sistema operacional
${shell}	Nome e caminho do shell, por exemplo bash (\/bin/bash`)`
${now}	Horário atual em formato ISO
${additional_dirs_info}	Diretórios adicionais incluídos no workspace; vazio quando não há nenhum
${base_prompt}	O system prompt padrão. Dentro do próprio SYSTEM.md é o padrão embutido; dentro de um arquivo de agente é o padrão efetivo — o embutido, ou a sua sobrescrita SYSTEM.md quando presente
${plugin_sections}	Um bloco completo de Plugin Instructions contribuído pelos plugins habilitados; vazio quando nenhum plugin habilitado contribui instruções

Variáveis desconhecidas permanecem literais, um $ isolado nunca é especial, e uma variável sem valor de contexto renderiza como string vazia. Quatro blocos pré-compostos — ${windows_notes}, ${additional_dirs_section}, ${skills_section} e ${plugin_sections} — renderizam a seção correspondente do prompt embutido, ou uma string vazia quando não se aplica. O prompt padrão embutido já inclui ${plugin_sections}, então não o adicione de novo quando ${base_prompt} já expandir para esse prompt. As variáveis bastam para reconstruir o esqueleto do prompt embutido, por exemplo:

You are ${product_name}, running at ${cwd} on ${os}.

${agents_md}

${skills}

${plugin_sections}

Arquivos de instrução

Instruções globais específicas do Jarvis Code podem ficar em $JARVIS_CODE_HOME/AGENTS.md (padrão: ~/.jarvis-code/AGENTS.md). Quando você realoca a raiz de dados com JARVIS_CODE_HOME, esse arquivo de instrução global vai junto. Instruções genéricas entre ferramentas ainda podem ficar em ~/.agents/AGENTS.md, no home real do sistema operacional, e instruções de nível de projeto permanecem na árvore do projeto, por exemplo .jarvis-code/AGENTS.md ou AGENTS.md.

Local de armazenamento no diretório da sessão

O estado de execução dos subagentes é persistido no subdiretório agents/ do diretório da sessão atual. Cada instância de subagente tem seu próprio diretório, que contém um arquivo wire.jsonl registrando prompts, histórico de mensagens e estado final em ordem cronológica. Subagentes em segundo plano também expõem seu status de ciclo de vida por um subdiretório tasks/.

Nota

Diretórios de sessão, arquivos wire e registros de tarefa são todos material local de depuração e podem conter prompts do usuário, saída de comandos, caminhos de repositório, valores de retorno de ferramenta ou vestígios de credenciais. Não faça commit desses arquivos diretamente em repositórios públicos, issues ou logs de conversa; remova informações sensíveis antes de compartilhar.

Próximos passos

• Hooks — dispare notificações ou interceptações por script local em pontos-chave, como a conclusão de um subagente
• Agent Skills — injete conhecimento especializado e fluxos de trabalho em subagentes