Tutorial de Custom Agents do Antigravity: crie seus próprios especialistas
Transforme trabalhos recorrentes em sub-agentes salvos: um arquivo markdown com frontmatter YAML sob .agents/agents, uma lista de ferramentas delimitada e rules, workflows e skills por cima — todas as capturas vêm de uma gravação real.
A versão curta
- Um custom agent é um único arquivo markdown: frontmatter YAML (name, description, model, tools) mais o corpo com o prompt de sistema — salve o especialista recorrente uma vez e pare de reexplicá-lo a cada sessão.
- Agentes de workspace vivem em .agents/agents/<nome>.md e vão com o repositório; os pessoais em ~/.gemini/config/agents/ valem para todos os projetos da máquina.
- tools exige nomes exatos das ferramentas do Antigravity — view_file, grep_search, list_dir — e um nome errado derruba o agente na inicialização; subagent: true o torna delegável, mainAgent: true o coloca no seletor de entrada.
- Teste rápido com "What are your tools?" no seletor do IDE, delegue pelo chat principal ou inspecione com /agents e Alt+J na CLI — depois acrescente rules, workflows e skills.
Google Antigravity Livestream: Remote Control and Custom Agents
Canal:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
Canal:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
Docs:antigravity.googleDocs
As capturas são fotogramas da gravação de tela do Code A Program (creditado acima); o passo a passo do arquivo do custom agent é documentado a partir da transmissão oficial do Google e da documentação de subagents do Antigravity — ainda não existe gravação limpa de terceiros sobre esse fluxo.
A checagem de fatos também se apoia nos vídeos sobre custom agents de Use AI with Tech Dad e AI with Surya. Todas as marcas pertencem ao Google; este é um tutorial independente, sem vínculo com o Google.
Da pasta vazia ao especialista de confiança
1 · Delimite o especialista
- 1
Identifique um papel que merece ser salvo
Um custom agent faz jus ao arquivo quando o mesmo trabalho volta sempre: um revisor de código com checklist fixa, um modernizador de dependências, um executor de testes, um mantenedor de docs. Se as instruções são estáveis, diferentes do seu assistente geral, e a caixa de ferramentas pode ser nomeada de antemão, salve o papel. Pedidos pontuais seguem melhor como um prompt simples.
- 2
Diferencie de sub-agentes e skills
Um sub-agente é o posto de trabalho: a sessão para a qual seu agente principal delega. Um custom agent é o perfil salvo que pode ocupar esse posto — ou com quem você conversa diretamente. Skills são outra camada: empacotam conhecimento de tarefa que qualquer agente pode usar, enquanto um custom agent muda as instruções centrais e o acesso a ferramentas. Para uma tarefa pontual, você não precisa de arquivo; o Antigravity pode criar um sub-agente transitório com a ferramenta define_subagent no meio da sessão.
- 3
Escolha o escopo: repositório ou máquina
O Antigravity descobre os .md de custom agents em três lugares. As customizações de workspace ficam em .agents/agents/<nome>.md (ou .agents/agents/<nome>/agent.md) e viajam com o repositório — certas para convenções compartilhadas. As customizações globais ficam em ~/.gemini/config/agents/<nome>.md e valem para todos os projetos da máquina — certas para especialistas pessoais. Plugins podem trazer agentes em plugins/<nome_plugin>/agents/.
A página Rules da documentação do Antigravity: regras globais vivem em ~/.gemini/GEMINI.md e valem para todos os workspaces, as do workspace na pasta .agents — a mesma divisão que os arquivos de custom agents seguem.Vídeo em 0:30
2 · Escreva o arquivo do agente
- 4
Crie o arquivo do agente
Dentro do projeto, crie pasta e arquivo de uma vez — o nome do arquivo ou da pasta vira a identidade do agente, então minúsculas e hífenes: .agents/agents/codereviewer/agent.md. Você também pode pedir ao agente do Antigravity para montá-lo: no walkthrough oficial, um único prompt "I have an idea for a custom agent" devolveu o caminho completo undefined/.agents/agents/codereviewer/agent.md e uma definição pronta para editar.
- 5
Preencha o frontmatter YAML
O frontmatter declara a identidade e os limites do especialista. name deve ser único — é o que você vai @mencionar. description diz ao Antigravity quando chamar o especialista; escreva como um anúncio de vaga. model: inherit mantém o nível de modelo do pai, e tools lista exatamente o que o papel pode usar. Duas flags completam o quadro: subagent assume true (delegável) e mainAgent assume false (mude para true para selecioná-lo direto no seletor de entrada).
- 6
Escreva o corpo do prompt de sistema
Tudo abaixo do delimitador do frontmatter viram as instruções de sistema do agente. O exemplo oficial abre com uma persona ("You are an expert, meticulous Code Reviewer"), lista responsabilidades centrais — correção, segurança, desempenho, estilo — e fecha com um formato de saída estrito: um veredicto em Summary, Critical findings bloqueantes com referências de linha e sugestões não bloqueantes. Um formato de relatório estável é o que torna os resultados confiáveis.
---
name: codereviewer
description: >-
Code review specialist that analyzes diffs, inspects code for bugs,
architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
- view_file
- grep_search
- list_dir
subagent: true
---
# Code Reviewer Persona & Instructions
You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.
## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors3 · Expanda e restrinja
- 7
Limite a caixa de ferramentas com nomes reais
O frontmatter tools recebe uma lista de permissão explícita, e os nomes devem bater com as ferramentas reais do Antigravity. No walkthrough oficial o arquivo gerado listava read — e o agente morreu com "Agent execution terminated due to error" até ser corrigido para view_file. Fique com nomes como view_file, grep_search e list_dir, e dê ao papel só o que o trabalho pede; um revisor raramente precisa de escrita.
Um arquivo de configuração do workspace listando os nomes de ferramentas que um agente pode chamar — view_file, grep_search, read_file — o mesmo vocabulário que a lista tools de um custom agent espera.Vídeo em 4:44 - 8
Decida quando ele atua
Com subagent: true (padrão) seu especialista fica delegável: descreva o trabalho ao agente principal e ele passa a tarefa delimitada ao especialista, cujo relatório volta para a conversa principal. Sub-agentes delegados herdam as fronteiras de permissão do pai — comandos permitidos, escopos de arquivos e ajustes de sandbox — e pedidos que precisam de aprovação aparecem na interface principal. Mude também mainAgent para true e o especialista aparece no seletor, pronto para conversa direta.
- 9
Abra Customizations e nomeie uma regra
Custom agents ficam espertos rapidinho quando você adiciona regras da casa. No IDE, abra o menu "..." no topo do painel do agente e escolha Customizations — o mesmo painel abriga Rules e Workflows. Em Rules, crie uma nova regra: regras globais vivem em ~/.gemini/GEMINI.md e valem para todos os workspaces, enquanto as do workspace vivem na pasta .agents do workspace ou da raiz do git. Um arquivo de regra é limitado a 12.000 caracteres.
O painel Customizations no painel de agente do Antigravity: a aba Rules está ativa e um novo nome de regra é digitado onde o placeholder lê e.g. code-style-guide.Vídeo em 0:56 - 10
Escolha o modo de ativação
Cada regra responde a uma pergunta: quando vale? Always On injeta em toda conversa; Manual espera um @mention na caixa de entrada; Model Decision deixa o agente acioná-la pela descrição em linguagem natural; Glob vale só para arquivos que casem com um padrão como *.test.ts. Escolha o modo mais estreito que funcione — uma regra de revisão que só dispara em diffs permanece focada.
O menu Activation Mode em um editor de regras do Antigravity com as quatro opções visíveis — Always On, Manual, Model Decision e Glob.Vídeo em 1:04 - 11
Escreva o conteúdo da regra
Rules são restrições em Markdown puro: "comentários explicam por que o código existe, não o que ele faz", "use JSDoc nas funções", "nunca deixe TODOs". Cada regra com um único propósito — o agente as lê literalmente em toda conversa afetada. Rules moldam como o especialista trabalha; as duas camadas seguintes dão procedimentos e conhecimento.
Um arquivo de regra chamado comments.md no editor do Antigravity, Activation Mode em Always On, pronto para as instruções Markdown que toda conversa deve seguir.Vídeo em 1:02 - 12
Empacote procedimentos recorrentes como workflows
Quando o especialista precisa repetir um procedimento de vários passos — limpar branches mescladas, cortar uma release, regenerar a documentação da API — salve como workflow em vez de redigitar os passos. Workflows são arquivos markdown com descrição YAML no frontmatter, invocados por comando de barra: digite /cleanup-branches e o agente executa cada passo listado.
A seção Workflows da documentação do Antigravity: arquivos de workflow vivem na pasta workflows do .agent e são invocados no chat com um comando /workflow-name.Vídeo em 5:40 - 13
Crie o arquivo do workflow
Peça ao agente para montar, ou faça você mesmo: mkdir -p .agent/workflows e depois cleanup-branches.md com uma descrição curta no frontmatter e os passos numerados. No exemplo gravado, os passos vão de git fetch --prune a apagar branches mescladas — e como cada passo é explícito, o agente para e pergunta antes dos destrutivos.
Uma conversa do Antigravity em que o agente roda mkdir -p .agent/workflows e nano, e recebe o markdown do workflow — frontmatter de descrição mais uma checklist de git com dez passos.Vídeo em 6:20
4 · Teste, publique e separe as camadas
- 14
Veja a barreira de segurança em ação
A execução gravada termina com o agente reportando o branch obtido, apontando feature/about-page como mesclada e segura para apagar, e perguntando "Would you like me to proceed with deleting these?" antes de tocar em qualquer coisa. Esse hábito de aprovação se estende aos custom agents delegados: ações que exigem autorização aparecem na interface principal — o especialista nunca cruza um limite em silêncio.
O relatório do workflow: feature/about-page está mesclada e é segura para apagar, e o agente pergunta "Would you like me to proceed?" antes de rodar git branch -d e git gc.Vídeo em 7:46 - 15
Ensine uma skill a ele
Rules moldam comportamento; skills adicionam conhecimento. Uma skill é uma pasta com um arquivo SKILL.md — skills do workspace em .agents/skills/<nome-skill>/, pessoais em ~/.gemini/skills. O name e a description do frontmatter dizem ao agente quando a skill é relevante; o corpo traz as instruções completas, scripts e referências. Custom agents e skills se combinam: seu codereviewer pode se apoiar em uma skill nextjs-reviewer para checagens específicas do framework.
A seção Agent Skills da documentação do Antigravity: crie uma pasta em um dos diretórios de skills e adicione um arquivo SKILL.md com frontmatter YAML.Vídeo em 8:42 - 16
Escreva o frontmatter do SKILL.md
Escreva a description como um gatilho: "Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns". Quando um pedido casa, o agente carrega a skill inteira; quando não, ela não atrapalha. Esse carregamento progressivo é exatamente por que o material de referência profundo pertence a uma skill e não ao prompt de sistema do agente.
Um SKILL.md de nextjs-reviewer no editor do Antigravity: o frontmatter YAML traz o nome da skill e a descrição — Reviews Next.js and TypeScript code for critical issues only.Vídeo em 9:16 - 17
Veja a skill disparar numa revisão real
Na sessão gravada, pedir ao agente para revisar o código Next.js fez com que ele carregasse a skill de revisão, analisasse a página e respondesse com uma revisão estruturada: Project Strengths destacou utilitários tipados e a otimização de fontes, e o agente perguntou "Would you like me to apply these fixes for you?" antes de editar. Seu custom agent herda essa disciplina quando o prompt exige o mesmo formato de saída.
O agente revisor em ação: lista os pontos fortes do projeto — utilitários tipados, next/image, padrões de App Router — e pergunta se deve aplicar as correções.Vídeo em 10:15 - 18
Teste pelo IDE e pela CLI
Com mainAgent: true o especialista aparece no seletor de entrada — selecione-o e pergunte "What are your tools?" para verificar a caixa de ferramentas; uma lista tools quebrada falha na hora com erro de execução, o smoke test mais rápido. Na CLI, /agents lista os agentes descobertos e Alt+J abre o painel de sub-agentes para acompanhar o trabalho delegado ao vivo.
- 19
Comite a pasta para o time ter os mesmos especialistas
Tudo o que o especialista precisa agora vive no repositório: .agents/agents/ para as definições dos agentes, mais a pasta .agent com rules, skills e workflows ao lado do código. Faça commit e cada colega — e cada execução de CI — descobre os mesmos especialistas com os mesmos limites. Definições pessoais em ~/.gemini ficam de fora do repositório: são preferências da máquina.
O explorador do Antigravity com a pasta .agent expandida — agent, rules, skills e workflows ao lado do código, prontos para o commit.Vídeo em 9:04 - 20
Saiba qual camada faz o quê
As três camadas de customização complementam o arquivo do agente em vez de substituí-lo: Rules são padrões de código sempre ativos (ou disparados por padrão), Workflows são procedimentos em comando de barra, Skills são conhecimento expert autodescoberto. O custom agent é a identidade que amarra tudo — um arquivo markdown que dá a um trabalho recorrente um nome, uma caixa de ferramentas e uma memória.
Uma tabela comparando Rules, Workflows e Skills: padrões de código valem automaticamente, automação roda por comandos de barra e conhecimento expert é descoberto quando relevante.Vídeo em 10:20