pending_approval, la
llamada a herramienta del agente se retiene en vez de despacharse — ahora
está esperando a un humano. Esta página es para el revisor: cómo aprobar las
retenciones de llamadas a herramienta de agentes (o rechazarlas) desde la
consola, qué te muestra la cola, y cómo OrcaRouter evita que dos revisores
colisionen en la misma decisión.
Es la mitad de resolución del humano en el ciclo. Para por qué se retiene
una llamada y cómo el agente retenido reenvía después, ver
veredictos y la
referencia de aprobaciones más profunda.
Para resolver desde tu propio sistema en vez de la consola, ver
webhooks de aprobación.
1. El ciclo de vida de la llamada retenida, desde el asiento de un revisor
Una llamada retenida es un bucle corto fuera de banda. Tu trabajo es el paso del medio:La llamada se retiene
Una regla resuelve a
pending_approval. El relay devuelve HTTP 400 con
el código firewall_approval_pending y un id de aprobación; la llamada
nunca llega a la herramienta. El agente empieza a hacer polling de ese id.La resuelves
Abres la cola Approvals, lees por qué se retuvo la llamada, y la
apruebas o rechazas — el foco de esta página.
Resolver una retención está gobernado a Developer+ — la misma compuerta
que el feed de Events del firewall. Los roles inferiores pueden leer la
política de firewall, la configuración y las herramientas descubiertas, pero
solo los roles Developer y superiores pueden listar la cola de aprobaciones o
aprobar/rechazar una llamada a herramienta retenida. Ver
roles y alcance.
2. Listar la cola pendiente
La pestaña Approvals leeGET /api/workspace/firewall/approvals. Sin filtro
devuelve la cola pending, más antigua primero — así que la llamada que
más tiempo lleva esperando se sitúa arriba y trabajas el backlog en orden.
state es el único filtro que importa. Los valores mapean al ciclo de vida
de la aprobación:
state | Aprobaciones devueltas |
|---|---|
pending (por defecto) | Retenida, esperando una decisión — tu cola de trabajo. |
approved | Ya dejada pasar. |
rejected | Ya bloqueada. |
3. Leer por qué se retuvo la llamada
Cada fila lleva las entradas de decisión que un revisor necesita — el nombre de la herramienta (tool_name), una huella de argumentos
(args_hash, el SHA-256 de los argumentos de llamada canonicalizados — los
valores de argumento en bruto no se almacenan en la aprobación), el id de
solicitud, y una línea de procedencia en lenguaje sencillo que nombra la
política, la regla y la cláusula que se disparó:
policy_name — qué política la retuvo
policy_name — qué política la retuvo
La política nombrada a la que pertenece la regla coincidente, resuelta con
alcance de espacio de trabajo para que un id obsoleto nunca pueda sacar a
la luz el nombre de política de otro inquilino.
rule_label + matched_clause — la razón humana
rule_label + matched_clause — la razón humana
La etiqueta de la regla y un descriptor de “por qué” de una línea — p. ej.
command contains rm -rf, o tool matches "http_fetch" para una regla de
solo glob. Esto renderiza la línea “Held because…” en la cola.rule_changed — procedencia en la que puedes confiar
rule_changed — procedencia en la que puedes confiar
true cuando la regla coincidente fue editada en o después de que se
creó esta aprobación. La etiqueta y cláusula en vivo se suprimen entonces
(pueden ya no reflejar lo que realmente retuvo la llamada), y la cola
muestra una nota “regla cambiada desde entonces” en vez de procedencia
obsoleta. El nombre de la herramienta y los argumentos — las entradas de
decisión reales — siempre se muestran.4. Aprobar o rechazar
Resolver envíaPATCH /api/workspace/firewall/approvals/:id con un decision
de approved o rejected y un reason opcional. La consola lo hace por ti
cuando haces clic en el botón; la forma es:
approved→ la llamada retenida puede proceder. El siguiente reenvío del agente, llevando la cabecera de aprobación de un solo uso, se deja pasar una vez.rejected→ la llamada sigue bloqueada. El agente ve el rechazo y puede elegir otra ruta, preguntar al usuario o detenerse.
decision se valida contra el conjunto cerrado {approved, rejected} —
cualquier otra cosa se rechaza. El reason se registra con la decisión y se
escribe en el registro de auditoría del firewall junto al actor, el nombre de
la herramienta y el id de solicitud.
Cada resolución escribe una fila de auditoría del espacio de trabajo que
nombra quién decidió, la decisión y la razón. Las resoluciones de consola
registran el actor humano; las resoluciones de
webhook registran un actor de
sistema. La procedencia de la resolución nunca se descarta silenciosamente.
5. Gana-el-primer-escritor: sin doble resolución
Una aprobación pendiente puede ser disputada — dos revisores en la consola, o un clic de consola y un callback de webhook llegando juntos. OrcaRouter resuelve esto con una única regla de gana-el-primer-escritor:- La decisión es una actualización condicional atómica que solo se dispara
mientras la aprobación sigue
pending. El primer escritor gana y aplica la decisión. - Cada escritor posterior observa “ya resuelta” y se trata como un no-op idempotente — obtiene HTTP 200 con el documento ya resuelto, no un error.
resolved: true significa que tu llamada aplicó la decisión;
already_resolved: true significa que alguien (o algún webhook) llegó primero
y estás viendo su resultado. De cualquier forma la cola se reconcilia a un
estado consistente.
6. Un pase concreto por la cola
Un espacio de trabajo de autonomía balanced retiene una llamadashell.exec
de un agente porque una regla coincidió con command contains rm -rf. Como
revisor tú:
- Abres Approvals — el
shell.execretenido se sitúa arriba de la listapendingde más-antigua-primero. - Lees la fila: herramienta
shell.exec, la huellaargs_hash, id de solicitud, y la línea “Held because…command contains rm -rf” (renderizada de la cláusula de la regla coincidente). Sin flagrule_changed, así que la procedencia es actual. - El objetivo es un directorio de borrador, así que apruebas con una razón.
- Tu
PATCHdevuelveresolved: true; el siguiente polling del agente veapproved, reenvía con su cabecera de un solo uso, y el comando se ejecuta exactamente una vez.
already_resolved: true con su decisión — sin daño, sin doble
ejecución.
Dónde ir a continuación
Referencia de aprobaciones
El bucle HITL completo: retener, hacer polling, reenviar, y la cabecera de
un solo uso.
Webhooks de aprobación
Resuelve retenciones desde tu propio sistema con un callback firmado con
HMAC.
Veredictos
Dónde se sitúa pending_approval entre los seis veredictos del firewall.
Registro de eventos
Confirma el resultado posterior de una llamada resuelta en el feed.