Saltar para o conteúdo principal
Quando uma regra de firewall retorna o veredito pending_approval, a chamada de ferramenta do agente é retida em vez de despachada — ela agora está esperando por um humano. Esta página é para o revisor: como aprovar retenções de chamada de ferramenta de agente (ou rejeitá-las) a partir do console, o que a fila lhe mostra, e como o OrcaRouter impede que dois revisores colidam na mesma decisão. É a metade de resolução do human-in-the-loop. Para por que uma chamada é retida e como o agente retido reenvia depois, veja vereditos e a referência de aprovações mais profunda. Para resolver do seu próprio sistema em vez do console, veja webhooks de aprovação.

​
1. O ciclo de vida da chamada retida, do assento de um revisor

Uma chamada retida é um loop curto fora de banda. Seu trabalho é o passo do meio:
1

A chamada é retida

Uma regra resolve para pending_approval. O relay retorna HTTP 400 com o código firewall_approval_pending e um id de aprovação; a chamada nunca chega à ferramenta. O agente começa a consultar nesse id.
2

Você a resolve

Você abre a fila Approvals, lê por que a chamada foi retida, e a aprova ou rejeita — o foco desta página.
3

O agente prossegue (ou para)

Na aprovação, o agente reenvia a chamada original com um header X-OrcaRouter-Firewall-Approval de uso único e o gateway a deixa passar aquela única vez. Na rejeição, a chamada permanece bloqueada.
Resolver uma retenção é restrito a Developer+ — o mesmo controle que o feed de Events do firewall. Papéis inferiores podem ler a política de firewall, as configurações e as ferramentas descobertas, mas apenas papéis Developer-e-acima podem listar a fila de aprovação ou aprovar/rejeitar uma chamada de ferramenta retida. Veja papéis e escopo.

​
2. Liste a fila pendente

A aba Approvals lê GET /api/workspace/firewall/approvals. Sem filtro ela retorna a fila pending, mais antigas primeiro — então a chamada que espera há mais tempo fica no topo e você trabalha o backlog em ordem. 
GET /api/workspace/firewall/approvals?state=pending
state é o único filtro que importa. Os valores mapeiam para o ciclo de vida da aprovação:
stateAprovações retornadas
pending (padrão)Retida, aguardando uma decisão — sua fila de trabalho.
approvedJá deixada passar.
rejectedJá bloqueada.
Esta é uma rota de console na sua sessão — configure-a e revise-a a partir do dashboard, não com uma chave de relay sk-orca-…. As chaves de relay são para chamadas de modelo /v1/*; o gerenciamento de firewall roda sob seu login de console.

​
3. Leia por que a chamada foi retida

Cada linha carrega os inputs de decisão de que um revisor precisa — o nome da ferramenta (tool_name), uma impressão digital de argumentos (args_hash, o SHA-256 dos argumentos canonicalizados da chamada — os valores crus de argumento não são armazenados na aprovação), o request id, e uma linha de proveniência em inglês simples que nomeia a política, a regra e a cláusula que disparou:
A política nomeada à qual a regra correspondida pertence, resolvida com escopo de workspace para que um id obsoleto nunca possa revelar o nome de política de outro tenant.
O label da regra e um descritor “por quê” de uma linha — ex.: command contains rm -rf, ou tool matches "http_fetch" para uma regra só de glob. Isso renderiza a linha “Held because…” na fila.
true quando a regra correspondida foi editada em ou após esta aprovação ter sido criada. O label e a cláusula ao vivo são então suprimidos (eles podem não mais refletir o que de fato reteve a chamada), e a fila mostra uma nota “rule since changed” em vez de proveniência obsoleta. O nome da ferramenta e os argumentos — os inputs de decisão reais — são sempre mostrados.
rule_changed é um sinal de honestidade deliberado, não um erro. Se alguém edita a regra de firewall enquanto uma chamada está parada na fila, o OrcaRouter preferiria esconder um motivo possivelmente-errado a mostrar a você proveniência que não corresponde mais. Decida pelo nome da ferramenta e pelo nome da política (ainda mostrados) nesse caso.

​
4. Aprove ou rejeite

Resolver envia PATCH /api/workspace/firewall/approvals/:id com um decision de approved ou rejected e um reason opcional. O console faz isso por você quando você clica no botão; a forma é: 
PATCH /api/workspace/firewall/approvals/507f1f77bcf86cd799439011
Content-Type: application/json

{ "decision": "approved", "reason": "verified target host with the on-call" }
  • approved → a chamada retida pode prosseguir. O próximo reenvio do agente, carregando o header de aprovação de uso único, é deixado passar uma vez.
  • rejected → a chamada permanece bloqueada. O agente vê a rejeição e pode escolher outro caminho, perguntar ao usuário, ou parar.
decision é validado contra o conjunto fechado {approved, rejected} — qualquer outra coisa é rejeitada. O reason é registrado com a decisão e escrito no log de auditoria do firewall ao lado do ator, do nome da ferramenta e do request id.
Cada resolução escreve uma linha de auditoria de workspace nomeando quem decidiu, a decisão e o motivo. Resoluções de console registram o ator humano; resoluções de webhook registram um ator de sistema. A proveniência de resolução nunca é silenciosamente descartada.

​
5. First-writer-wins: sem dupla resolução

Uma aprovação pendente pode sofrer corrida — dois revisores no console, ou um clique de console e um callback de webhook chegando juntos. O OrcaRouter resolve isso com uma única regra de first-writer-wins:
  • A decisão é um update condicional atômico que só dispara enquanto a aprovação ainda está pending. O primeiro escritor vence e aplica a decisão.
  • Todo escritor posterior observa “já resolvida” e é tratado como um no-op idempotente — ele recebe HTTP 200 com o documento já resolvido, não um erro.
A resposta diz a você de qual lado você estava: 
{
  "resolved": false,
  "already_resolved": true,
  "approval": { "state": "approved", "decision": "approved", "...": "..." }
}
resolved: true significa que sua chamada aplicou a decisão; already_resolved: true significa que alguém (ou algum webhook) chegou primeiro e você está vendo o resultado deles. De qualquer forma a fila reconcilia para um estado consistente.
Porque a resolução é idempotente, uma rede instável ou um duplo-clique não pode corromper uma retenção ou inverter uma decisão. O primeiro approve/reject é o único que conta; tudo depois dele apenas lê o resultado de volta.

​
6. Uma passagem concreta pela fila

Um workspace de autonomia balanced retém a chamada shell.exec de um agente porque uma regra correspondeu a command contains rm -rf. Como o revisor você:
  1. Abre Approvals — o shell.exec retido fica no topo da lista pending mais-antigas-primeiro.
  2. Lê a linha: ferramenta shell.exec, a impressão digital args_hash, o request id, e a linha “Held because… command contains rm -rf” (renderizada a partir da cláusula da regra correspondida). Sem flag rule_changed, então a proveniência é atual.
  3. O alvo é um diretório descartável, então você aprova com um motivo.
  4. Seu PATCH retorna resolved: true; a próxima consulta do agente vê approved, reenvia com seu header de uso único, e o comando roda exatamente uma vez.
Tivesse um colega de equipe aprovado um segundo antes, seu clique teria retornado already_resolved: true com a decisão deles — sem dano, sem dupla execução.

​
Para onde ir a seguir

Referência de aprovações

O loop HITL completo: reter, consultar, reenviar, e o header de uso único.

Webhooks de aprovação

Resolva retenções do seu próprio sistema com um callback assinado por HMAC.

Vereditos

Onde pending_approval fica entre os seis vereditos de firewall.

Log de events

Confirme o resultado downstream de uma chamada resolvida no feed.
Para os riscos que essas retenções pretendem capturar, veja chamadas de ferramenta perigosas e agência excessiva.