Kontrollpunkte

A Kontrollpunkt bittet um Genehmigung einer Single Agent Action. Sie erstellen eine, bevor die Aktion ausgeführt wird; Maetra bewertet sie gegen Ihre aktive Politik und gibt eine Entscheidung zurück - sofort für Fast-Path-Ergebnisse oder nachdem ein Mensch reagiert.

Lebenszyklus#

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

Nur genehmigt Entscheidungen können bis zur Einwegausführungsberechtigung fortgesetzt werden.

Erstellen Sie einen Checkpoint#

POST /v1/checkpoints — erfordert Anwendungsbereich govern:checkpoints:write.

Bewertet synchron: Eine Fast-Pfad-Politik kann eine Terminal-Entscheidung in der gleichen Antwort zurückgeben; Andernfalls erhalten Sie eine anhängig Checkpoint zum Pollen.

Exakte Richtlinien und Entscheidungsintelligenz

/v1/checkpoints verwendet die in Govern konfigurierten aktiven Richtlinien. Eine Richtlinie kann exakt gespeicherte Bedingungen verwenden, oder sie kann Entscheidungsfindung von KI-Agenten zur Bewertung des Laufzeitrisikos.

Sie tun dies nicht senden a decision_intelligence Markierung auf der Checkpoint-Anfrage. Aktivieren Sie Decision Intelligence für die Policy im Dashboard. Der API-Aufruf bleibt gleich; Maetra wendet den Richtlinienmodus an und gibt die gleiche Checkpoint-Entscheidungsform zurück.

Anfordernde Stelle

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."
}'

Mit einem registrierten Agenten

Der obige Call verwendet agent_name weil der Agent nicht registriert ist - der gemeinsame Fall. Wenn der Agent ist registriertÜbergeben Sie Ihre agent_id stattdessen (oder nebenbei) agent_name) so wird ihm der Checkpoint zugeschrieben:

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

Richtlinienumfang mit optionaler Agent-Identität

agent_id ist optional für /v1/checkpoints. Wenn Sie nur senden agent_nameGovern bewertet immer noch die aktion.

Für die automatische aktive Politikauswertung:

Verwendung agent_id für stabile Attribution. Verwendung agent_name nur für API-Agenten oder MCP-Agenten, die noch nicht registriert sind. Wenn Sie gehen policy_ids oder policy_group_idsMaetra bewertet diese explizite auswahl. Die Auswahl kann genaue Richtlinien oder Entscheidungsintelligenzrichtlinien umfassen.

Antwort

{
  "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 }
  ]
}

Evales Objekt: policy_id, policy_name, applicability, status, quorum_required, quorum_met, pool_size.

Holen Sie sich einen Checkpoint (kalte Umfrage)#

GET /v1/checkpoints/{id} — Anwendungsbereich govern:checkpoints:read. Gibt den aktuellen Zustand zurück, ohne zu warten. Halten Sie ≥ 1 Sekunde zwischen den Umfragen des gleichen Checkpoints; bevorzugen Sie die Long-Poll unten.

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

Warten auf eine Entscheidung (long-poll)#

GET /v1/checkpoints/{id}/wait — Anwendungsbereich govern:checkpoints:read. Hält die Verbindung offen, bis der Checkpoint den Zustand ändert oder der Haltevorgang abgelaufen ist. Der effiziente Weg, auf einen Menschen zu warten.

• Abfrage timeout: Haltesekunden, 1–55 (Standard) 50).
• 200 - verändert; Körper ist der neue Zustand. 202 Keine Änderung; Reconnect.

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

Empfohlener Fluss#

1. POST /v1/checkpoints.
2. Wenn status ist bereits terminal, handeln Sie darauf (und überprüfen Sie das Token).
3. Wenn anhängig, Long-Poll /wait bis zum Terminal.
4. am genehmigt, Überprüfen Sie das Entscheidungs-Token, Dann konsumieren Sie es durch Ausführungsberechtigung unmittelbar vor dem Handeln. Notieren Sie jeden Versuch und überprüfen Sie den Effekt. Auf irgendetwas anderes, handeln Sie nicht.