Despachar agentes revisores

Este guia mostra como despachar agentes revisores para revisar pull requests.

Na tela da PR

1. Abra a PR e vá até a aba Visão geral
2. Abra o menu de overflow ⋯ e escolha Ask AI

Isso inicia o pipeline pr_review predefinido, que abre o espaço de revisão da PR e despacha os revisores do nível de revisão do espaço de trabalho — três por padrão (os agentes predefinidos qa, architect e engineer) — e então faz o agente líder consolidar. Nesse caminho, você não escolhe os papéis. Para ter controle sobre quais papéis são executados e quais arquivos cada um examina, use a ferramenta MCP ou uma etapa de pipeline abaixo.

Pela ferramenta MCP dispatch_reviewers

Chame-a dentro de um espaço de revisão existente:

dispatch_reviewers(
  space_id: "...",
  workspace_id: "...",
  reviewers: [
    {role: "reviewer"},
    {role: "security", scope: "src/auth/**"}
  ]
)

space_id, workspace_id e reviewers são todos obrigatórios. Cada especificação de revisor leva um role mais um scope opcional de glob de arquivos e um prompt_override que substitui as instruções padrão. Um concurrency opcional (1–8) limita o número de despachos paralelos; quando omitido, aplica-se a configuração review_concurrency do espaço de trabalho (padrão 3, definida em Configurações → Espaço de trabalho → Geral).

A ferramenta retorna imediatamente com as listas dispatched e unmatched. Todo revisor despachado é adicionado ao espaço como participante, anunciado com uma mensagem de sistema e despachado com suas instruções. Os achados chegam como mensagens review_node nesse espaço.

A partir de uma etapa de pipeline

Abra Configurações → Espaço de trabalho → Modelos de pipeline, abra um modelo e então:

1. Adicione um nó Reviewer (prompt) da paleta
2. Escolha o agente a despachar e escreva o prompt do revisor, usando placeholders {{key}} para saídas a montante (por exemplo {{repo_local_path}}, {{pr_number}})
3. Defina a chave de saída (padrão reviewer_findings) para que as etapas a jusante possam ler os achados

A etapa despacha o agente e suspende até que essa execução termine. O motor então colhe o payload submit_output da execução no estado do pipeline sob a chave de saída do nó. (A descrição da paleta ainda diz que a etapa aguarda uma chamada complete_task — essa ferramenta não existe; ignore essa string.)

Faça um fan-out conectando vários nós de revisor à mesma etapa a montante e depois consolide as saídas deles com um nó Consolidate (join).

O editor reconecta o terminal oculto a cada destino alcançável, de modo que um nó que você adicionar depois da etapa predefinida ainda é executado. Nós de fan-out conectados à mesma etapa a montante são executados em paralelo.

Despacho automático em uma nova PR

Para que um pipeline de revisão dispare sozinho:

1. Abra o modelo em Configurações → Espaço de trabalho → Modelos de pipeline
2. Arraste PR publicada ou PR externa aberta da seção Gatilhos da biblioteca de nós para o canvas (ou escolha-o no bloco fantasma Adicionar um gatilho)
3. Selecione o novo nó e ligue Ativado no inspetor dele, depois ative o modelo

Dois eventos importam aqui, e eles não são intercambiáveis:

Evento	Dispara quando	Chaves do payload
PullRequestPublished	Uma PR é aberta por meio do Control Center — a superfície de composição, ou um agente chamando pr_lifecycle.publish	pr_id, workspace_id, repo_owner, repo_name
ExternalPrDetected	O serviço de sondagem de PRs encontra uma PR aberta diretamente no GitHub	repo_owner, repo_name, pr_number, pr_title, author

Uma PR aberta no github.com nunca dispara PullRequestPublished, então um modelo conectado apenas a esse evento não a verá. Observe também que PullRequestPublished não carrega pr_number — uma etapa cujo script ou prompt referencia {{pr_number}} precisa ser alimentada por ExternalPrDetected, ou por uma execução manual que o forneça.

Ponto de verificação: depois de ativar, abra Pipelines e confirme que uma execução aparece para a próxima PR correspondente. Um modelo deixado como desativado faz seu gatilho disparar para o vazio — o motor rejeita um modelo desativado e retorna sem iniciar uma execução.

Como um papel é associado a um agente

dispatch_reviewers pontua cada agente do espaço de trabalho em relação a cada rótulo de papel solicitado, sem diferenciar maiúsculas de minúsculas:

Correspondência	Pontuação
Uma skill que contém o rótulo de papel	+3
Um título que contém o rótulo de papel	+2
Um nome de agente que contém o rótulo de papel	+1

As pontuações se acumulam e o total mais alto vence (em caso de empate, o primeiro candidato encontrado). Se nenhum candidato pontuar acima de zero, a especificação volta na lista unmatched da ferramenta em vez de ser despachada — assim, um papel que ninguém corresponde é relatado, nunca ignorado em silêncio.

O espaço de revisão

Uma PR tem exatamente um espaço de revisão, não um por revisor. Ele é criado de forma idempotente por pr.ensureSpace, ligado à PR por uma ReviewSpaceAssociation e provisionado em relação à ref de head da PR. Todo revisor despachado entra nesse espaço e publica nele seus achados review_node, o que torna os achados comparáveis e permite que o agente líder alcance consenso entre eles.

Monitorar o despacho

Cada revisor despachado recebe seu próprio AgentRunLog. Acompanhe o progresso em:

• O espaço de revisão, onde os achados chegam ao vivo
• A aba Revisão da PR, que mostra a barra de status da revisão e o veredito
• Observabilidade → Ao vivo (/workspaces/:id/observability), a lista de agentes com o status por execução, o tempo decorrido ao vivo, uma gaveta de transcrição e um controle de parada. Não há atalho de teclado para ela — acesse-a pelo rodapé da barra lateral.

Guias relacionados

• Usar revisão com IA
• Revisar e fazer merge de uma PR
• Configurar gatilhos de pipeline

Conceitos relacionados

• Revisão com IA
• Pipelines