Skip to main content
Os agentes personalizados estão em beta. O comportamento e as telas ainda podem mudar.

​
Visão Geral

Um agente personalizado é um revisor que o seu time escreve para um assunto só: fronteiras de arquitetura, código duplicado, uma política de segurança, cobertura de testes end-to-end. Cada agente tem:
  • Instructions: o que procurar, o que ignorar e que prova um apontamento precisa
  • Files: os globs que ele revisa. Ele só roda quando o pull request altera um desses arquivos
  • Skills & docs: guias do repositório que ele segue
  • Tools: plugins somente leitura, CLIs do seu time e regras do ast-grep
  • Comments & model: tag, formato, severidade mínima, limite de comentários, estilo de escrita e modelo
Os agentes rodam ao lado da revisão da própria Kody. Cada um reporta só o seu foco, e os comentários dele levam uma tag com o nome do agente, para o time saber quem está falando. Disponível nos planos Teams e Enterprise, e durante o trial. No plano Free nenhum agente customizado roda: nem nas revisões, nem com @kody -v, nem no Try it. Agentes, skills e docs salvos são mantidos e voltam a rodar depois de um upgrade.

Skills, docs e ferramentas

Vincule guias do repositório, plugins, CLIs do time e regras do ast-grep.

Boas práticas

Escreva agentes que acham problemas reais e ficam quietos no resto.

​
Onde encontrar

Abra Code review → What to review. A seção Custom agents fica abaixo das categorias de revisão, com o botão New agent e um link para Skills & docs. Cada linha mostra o switch do agente, a cor da tag, a primeira linha das instruções, chips com arquivos, skills, docs e ferramentas, e o que ele fez nos últimos dias (por exemplo 9 PRs · 15 posted · 30 days). Clique na linha para abrir a página do agente. O menu ⋯ tem Edit, Try it e Delete.
Agentes personalizados são configurados só no app. As chaves customAgents e knowledge no kodus-config.yml são ignoradas, e a revisão avisa isso no comentário final. Veja as Perguntas frequentes.

​
Níveis

Os agentes seguem o seletor de escopo no topo do grupo Code review, como o resto das suas configurações. Num diretório, um agente herdado abre somente leitura, com o botão Override at this directory. Sobrescrever copia o agente para o diretório com o mesmo id, e a cópia substitui o agente do repositório naquele diretório: mude as instruções ou desligue. Apagar a sobrescrita traz o agente do repositório de volta.
Os agentes de um diretório rodam quando a revisão usa as configurações daquele diretório. Veja em Configurações por Diretório como um pull request escolhe as configurações.

​
Criar um agente

1

Clique em New agent

Em What to review → Custom agents, clique em New agent.
2

Escolha um ponto de partida

Templates começam com instruções já escritas:Import from repository lista as skills encontradas na branch padrão do repositório e transforma uma delas num revisor que a carrega em toda revisão. Não fica disponível no nível global, porque as skills vivem em cada repositório.
3

Ajuste na página do agente

O agente é salvo na hora e a página dele abre. Defina os arquivos, vincule skills e docs, adicione ferramentas.
4

Teste com Try it e depois ligue

Todo agente novo começa desligado. Rode com o Try it num pull request real. Quando os comentários estiverem bons, ligue.
O nome do agente também é o nome do comando: “Data Contracts” responde a @kody -v data-contracts. Dois agentes cujos nomes geram o mesmo nome de comando não podem ser salvos no mesmo nível.

​
A página do agente

A página tem uma linha de status (ligado/desligado, os arquivos em que ele roda e o que postou nos últimos 30 dias), quatro cards e o painel Try it. As alterações na página são mantidas com Save.

​
Instructions

​
Files & knowledge

Os globs são comparados com o caminho a partir da raiz do repositório, em todos os níveis, inclusive num diretório. Arquivos ignorados. Os caminhos ignorados do repositório (em General) continuam valendo, com uma exceção: um glob que nomeia um arquivo chega nele mesmo que o repositório o ignore. Um glob nomeia arquivos quando pelo menos um segmento do caminho é literal e o último segmento é mais que * ou **: Arquivos de segredo (.env*, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, id_rsa* e outras chaves SSH) nunca chegam a um agente pelos caminhos ignorados, nem por um glob que os nomeia. Um pull request em que todos os arquivos alterados são ignorados ainda é revisado pelo agente que nomeia algum deles, e só por ele: a revisão da Kody não tem nada para olhar.

​
Tools

O que o agente pode executar além de ler o código, tudo somente leitura em relação aos seus sistemas: Plugins (MCP), CLIs (até 3) e, em Advanced, Structural search (ast-grep rules). Veja Skills, docs e ferramentas.

​
Comments & model

​
Try it

O Try it roda o agente como ele está na tela, salvo ou não, num pull request do repositório. Nada é postado.
1

Cole o link de um pull request

Na página do agente, cole o link de um pull request deste repositório e clique em Run agent. Leva alguns minutos numa mudança grande.
2

Leia o resultado

O cabeçalho conta os apontamentos, quantos foram mantidos e quantos seriam postados. Abaixo dele:
  • Warnings: o que a execução perdeu, como falta de checkout (o agente leu só o diff), uma CLI que não instalou ou uma skill ou doc que não pôde ser usada
  • Skills opened, com os arquivos de referência que o agente leu
  • As chamadas de ferramenta (tool calls), cada uma com entrada e saída, inclusive a saída das CLIs
  • Os apontamentos: cada um kept, dropped ou unverified, com o motivo, a regra citada e o Comment que seria postado
3

Ajuste e rode de novo

Edite as instruções, os globs ou as ferramentas e rode de novo. Se você editar depois de uma execução, a página avisa que o resultado é de uma versão anterior.
O Try it funciona nos níveis de repositório e de diretório e exige permissão para editar as configurações de code review. Se nenhum arquivo alterado bate com os globs do agente, a execução é pulada e diz o motivo.

​
Rodar um agente num pull request

Comente no pull request com o nome de comando do agente na primeira linha:
A Kody roda só esse agente, no pull request inteiro, mesmo que ele esteja desligado, e posta os comentários dele. Os revisores da própria Kody não rodam, e esse comando nunca aprova o pull request. Se nenhum agente responde por esse nome, a Kody responde com os nomes que existem.

​
Como os agentes rodam numa revisão

1

Escolha dos agentes

Roda todo agente ligado cujos globs batem com pelo menos um arquivo alterado. Um agente sem arquivo correspondente não roda.
2

Revisão

Cada agente revisa só os seus arquivos, ao lado da revisão da Kody, e reporta só o que as instruções pedem. Ele lê skills e docs da branch de destino e usa as suas ferramentas.
3

Checagem de cada apontamento

Um apontamento de convenção precisa citar a regra que aplica, de um guia vinculado ou das instruções do agente. Uma citação que não está no guia na branch de destino é descartada. Uma citação encurtada com ”…” passa quando cada parte está lá, na ordem. Depois, um verificador descarta apontamentos fora do foco do agente ou sem respaldo no código. Um match do ast-grep vale como prova sozinho.
4

Configurações do agente

A severidade mínima do agente e, depois, o limite de comentários (ficam os mais graves).
5

Junção com a revisão principal

Quando um agente e a Kody reportam o mesmo problema, fica um comentário só. Para uma regra do time dentro do foco do agente, vence o comentário do agente. Para o resto, fica o comentário da Kody.
6

Publicação

Os comentários levam a tag do agente. Um comentário de convenção cita a regra aplicada (o guia e o texto dela, ou “agent’s instructions”). Um apontamento apoiado numa CLI mostra, em Evidence, as linhas da saída da CLI que citam o arquivo.
Os comentários de cada agente levam a tag dele, então o pull request mostra qual agente disse o quê. A página do agente mostra o que ele fez nos últimos 30 dias: os pull requests que revisou e os comentários que postou.

​
Limites

​
Perguntas frequentes

Confira, nesta ordem:
  • Ele está desligado. Agentes novos começam desligados. @kody -v <nome> roda mesmo assim.
  • Nenhum arquivo alterado bate com os globs de Files, ou todos caem em Except.
  • Os arquivos dele estão nos caminhos ignorados do repositório e os globs não os nomeiam. Nomeie os arquivos explicitamente (veja Files & knowledge).
  • Os arquivos dele foram apagados no pull request.
  • Num repositório com lista própria, um agente criado depois no nível global não chega nele.
  • Num diretório, a revisão usou as configurações do repositório (por exemplo, o pull request tocou dois diretórios configurados).
Rode o agente com o Try it no mesmo pull request: cada apontamento descartado mostra o motivo. Os mais comuns:
  • A citação não está no guia na branch de destino (foi parafraseada, ou o guia só mudou no próprio pull request).
  • O apontamento está fora do que as instruções do agente pedem.
  • O verificador não achou respaldo no código.
  • Ficou abaixo da severidade mínima do agente ou passou do limite de comentários.
  • A revisão da Kody reportou o mesmo problema e manteve o comentário dela.
Não. customAgents e knowledge no kodus-config.yml não são lidos. O comentário final avisa: “kodus-config.yml: customAgents is not read from this file; configure custom agents in the app.”
Não. Skills, docs e arquivos de regras do ast-grep são lidos da branch de destino do pull request. Edições neles dentro do pull request valem depois do merge.
Os apontamentos dele continuam nos pull requests anteriores. As skills e docs continuam cadastradas na página Skills & docs.