Despachar agentes revisores

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

A partir da vista da PR

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

Isto inicia o pipeline pr_review predefinido, que abre o espaço de revisão da PR e despacha os revisores correspondentes ao nível de revisão do espaço de trabalho — três por predefinição (os agentes predefinidos qa, architect e engineer) — e faz depois com que o agente líder consolide os resultados. Nesta via não escolhe as funções. Para controlar que funções são executadas e que ficheiros cada uma analisa, use a ferramenta MCP ou um passo de pipeline abaixo.

Através da ferramenta MCP dispatch_reviewers

Chame-a a partir 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 inclui uma role e, opcionalmente, um scope com um glob de ficheiros e um prompt_override que substitui o briefing predefinido. Uma concurrency opcional (1–8) limita os despachos paralelos; quando é omitida, aplica-se a definição review_concurrency do espaço de trabalho (predefinição 3, definida em Definições → Espaço de trabalho → Geral).

A ferramenta devolve imediatamente as listas dispatched e unmatched. Cada revisor despachado é adicionado ao espaço como participante, anunciado com uma mensagem de sistema e despachado com o seu briefing. As constatações chegam como mensagens review_node a esse espaço.

A partir de um passo de pipeline

Abra Definições → Espaço de trabalho → Modelos de pipeline, abra um modelo e depois:

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

O passo despacha o agente e fica suspenso até essa execução terminar. O motor recolhe depois o payload submit_output da execução para o estado do pipeline sob a chave de saída do nó. (A descrição na paleta ainda diz que o passo aguarda uma chamada complete_task — essa ferramenta não existe; ignore o texto.)

Faça fan-out ligando vários nós de revisor ao mesmo passo a montante e consolide depois as respetivas saídas com um nó Consolidate (join).

O editor volta a ligar o terminal oculto a cada destino alcançável, por isso um nó que adicione depois do Step predefinido continua a ser executado. Os nós de fan-out ligados ao mesmo passo a montante são executados em paralelo.

Despacho automático com uma PR nova

Para que um pipeline de revisão seja acionado por si próprio:

1. Abra o modelo em Definições → Espaço de trabalho → Modelos de pipeline
2. Arraste PR publicada ou PR externa aberta da secção Gatilhos da biblioteca de nós para a área de desenho (ou escolha-o no mosaico fantasma Adicionar um gatilho)
3. Selecione o novo nó, ative Ativado no respetivo inspetor e ative depois o modelo

Aqui importam dois eventos, que não são intercambiáveis:

Evento	É acionado quando	Chaves do payload
PullRequestPublished	Uma PR é aberta através do Control Center — a superfície de composição, ou um agente que chama 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 em github.com nunca gera PullRequestPublished, por isso um modelo ligado apenas a esse evento não a verá. Note também que PullRequestPublished não transporta pr_number — um passo cujo script ou prompt faça referência a {{pr_number}} tem de ser alimentado por ExternalPrDetected, ou por uma execução manual que o forneça.

Ponto de verificação: depois de ativar, abra Pipelines e confirme que aparece uma execução para a próxima PR correspondente. Um modelo deixado desativado faz com que o seu gatilho não acione nada — o motor rejeita um modelo desativado e devolve sem iniciar qualquer execução.

Como uma função é associada a um agente

dispatch_reviewers pontua todos os agentes do espaço de trabalho em relação a cada rótulo de função pedido, sem distinguir maiúsculas de minúsculas:

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

As pontuações acumulam-se e vence o total mais elevado (em caso de empate, o primeiro candidato encontrado). Se nenhum candidato pontuar acima de zero, a especificação regressa na lista unmatched da ferramenta em vez de ser despachada — assim, uma função que ninguém corresponde é reportada, nunca ignorada em silêncio.

O espaço de revisão

Uma PR tem exatamente um espaço de revisão, e não um por revisor. É criado de forma idempotente por pr.ensureSpace, associado à PR através de uma ReviewSpaceAssociation e aprovisionado em relação à ref de cabeça da PR. Todos os revisores despachados entram nesse espaço e publicam aí as suas constatações review_node, o que é o que torna as constatações comparáveis e permite ao agente líder chegar a consenso entre elas.

Monitorizar o despacho

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

• O espaço de revisão, onde as constatações chegam em direto
• O separador Revisão da PR, que apresenta a barra de estado da revisão e o veredicto
• Observabilidade → Ao vivo (/workspaces/:id/observability), a lista de agentes com o estado de cada execução, o tempo decorrido em direto, uma gaveta de transcrição e um controlo para terminar o agente. Não existe um atalho de teclado para isto — chegue lá a partir do rodapé da barra lateral.

Guias relacionados

• Usar revisão com IA
• Rever e fazer merge de uma PR
• Configurar disparadores de pipeline

Conceitos relacionados

• Revisão com IA
• Pipelines