Puntos de control

A punto de control pide la aprobación de una acción de un solo agente. Usted crea uno antes de que la acción se ejecuta; Maetra lo evalúa contra su activo políticas y devuelve una decisión - inmediatamente para resultados rápidos, o después de que un humano responda.

Ciclo de vida#

create ─▶ evaluate ─┬─▶ approved / rejected / blocked   (terminal, signed)
                    └─▶ pending ─▶ (human decides) ─▶ approved / rejected
                                └─▶ (timeout)      ─▶ expired

Sólo aprobado las decisiones pueden seguir autorizando la ejecución de un solo uso.

Crear un puesto de control#

POST /v1/checkpoints - Requiere el alcance govern:checkpoints:write.

Evaluado sincrónicamente: una política de ayuno puede devolver una decisión terminal en la misma respuesta; de lo contrario se obtiene una pendientes punto de control a la encuesta.

Exact policies and decision intelligence

/v1/checkpoints utiliza las políticas activas configuradas en Govern. Una política puede usar condiciones exactas salvadas, o puede usar Inteligencia de decisión del agente de inteligencia para evaluar el riesgo de tiempo de ejecución.

Tú sí. no enviar un mensaje decision_intelligence bandera en la solicitud de control. Permitir la inteligencia de decisión sobre la política en el tablero de mando. La llamada API se mantiene igual; Maetra aplica el modo de política y devuelve la misma forma de decisión de control.

Solicitud de cuerpo

curl -X POST "https://api.maetra.io/v1/checkpoints" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "delete_customer",
  "agent_name": "ops-agent",
  "payload": {
    "customer_id": "cus_41ab"
  },
  "reasoning": "GDPR erasure request #8821."
}'

Con un agente registrado

La llamada anterior utiliza agent_name porque el agente no está registrado — el caso común. Si el agente es registrados, pasar su agent_id en su lugar (o al lado) agent_name) por lo que el puesto de control se atribuye a él:

{
  "action": "delete_customer",
  "agent_id": "agt_5Ab2",
  "payload": { "customer_id": "cus_41ab" },
  "reasoning": "GDPR erasure request #8821."
}

Alcance de políticas con identidad de agente opcional

agent_id es opcional para /v1/checkpoints. Cuando envías sólo agent_nameGovern todavía evalúa la acción.

Para la evaluación automática de políticas activas:

Uso agent_id para la atribución estable. Uso agent_name sólo para los agentes de API o MCP que aún no se han registrado. Si pasas policy_ids o policy_group_ids, Maetra evalúa esa selección explícita. La selección puede incluir políticas exactas o políticas de inteligencia de decisiones.

Respuesta

{
  "checkpoint_id": "cp_7Yh2Qa",
  "agent_id": null,
  "agent_name": "ops-agent",
  "status": "pending",
  "reason": null,
  "decision_token": null,
  "expires_at": "2026-07-07T12:05:00.000Z",
  "evals": [
    { "policy_name": "Destructive actions", "status": "pending", "quorum_required": 2, "quorum_met": 0, "pool_size": 4 }
  ]
}

Objeto Eval: policy_id, policy_name, applicability, status, quorum_required, quorum_met, pool_size.

Obtenga un puesto de control (solución fría)#

GET /v1/checkpoints/{id} - alcance govern:checkpoints:read. Devuelve el estado actual sin esperar. Mantenga ≥1 segundo entre las encuestas del mismo punto de control; prefiera el largo-poll abajo.

curl "https://api.maetra.io/v1/checkpoints/cp_7Yh2Qa" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Esperar una decisión (pola larga)#

GET /v1/checkpoints/{id}/wait - alcance govern:checkpoints:read. Mantiene la conexión abierta hasta que el punto de control cambie de estado o el detenimiento salta. La manera eficiente de esperar a un humano.

• Query timeout- Esperen segundos. 1–55 (default) 50).
• 200 - cambiado; el cuerpo es el nuevo estado. 202 - sin cambio; reconectar.

curl "https://api.maetra.io/v1/checkpoints/cp_7Yh2Qa/wait?timeout=50" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Flujo recomendado#

1. POST /v1/checkpoints.
2. Si. status ya es terminal, actuar en él (y verificar el token).
3. Si. pendientes, largo-poll /wait hasta la terminal.
4. Encendida aprobado, verificar la decisión token, entonces consumirlo a través autorización de ejecución inmediatamente antes de actuar. Grabar cada intento y verificar el efecto. En cualquier otra cosa, no actúes.