Points de contrôle

A point de contrôle demande l'approbation d'une action d'un seul agent. Vous en créez une avant que l'action ne s'exécute ; Maetra l'évalue contre votre actif politiques et retourne une décision - immédiatement pour des résultats rapides, ou après une réponse humaine.

Cycle de vie#

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

Seulement approuvé les décisions peuvent continuer à faire l'objet d'une autorisation d'exécution à usage unique.

Créer un point de contrôle#

POST /v1/checkpoints — demande une portée govern:checkpoints:write.

Évaluation synchrone : une politique de voie rapide peut renvoyer une décision finale dans la même réponse; sinon vous obtenez une en attente checkpoint pour le scrutin.

Politiques exactes et renseignement décisionnel

/v1/checkpoints utilise les politiques actives configurées dans Govern. Une politique peut utiliser des conditions exactement sauvegardées, ou elle peut utiliser Renseignements sur la décision de l'agent de l'IA évaluer le risque d'exécution.

C'est vrai. pas envoyer un decision_intelligence drapeau sur la demande de contrôle. Permettre l'information décisionnelle sur la politique dans le tableau de bord. L'appel API reste le même ; Maetra applique le mode politique et retourne la même forme de décision de point de contrôle.

Organisme de demande

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

Avec un agent enregistré

L'appel ci-dessus utilise agent_name parce que l'agent n'est pas enregistré — le cas commun. Si l'agent est enregistrés, passez son agent_id à la place (ou à côté agent_name) donc le point de contrôle lui est attribué :

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

Portée de la politique avec identité d'agent optionnelle

agent_id est facultatif pour /v1/checkpointsC'est vrai. Lorsque vous n'envoyez que agent_nameGovern évalue toujours l'action.

Pour l'évaluation automatique des politiques actives:

Utilisation agent_id pour une attribution stable. Utilisation agent_name pour les agents API ou MCP qui n'ont pas encore été enregistrés. Si vous passez policy_ids ou policy_group_ids, Maetra évalue cette sélection explicite. La sélection peut inclure des politiques précises ou des politiques d'intelligence décisionnelle.

Réponse

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

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

Obtenez un point de contrôle (sondage froid)#

GET /v1/checkpoints/{id} — champ d'application govern:checkpoints:readC'est vrai. Retourne l'état actuel sans attendre. Garder ≥ 1 seconde entre les sondages du même point de contrôle; préférer le long-poll ci-dessous.

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

Attendez une décision (long-poll)#

GET /v1/checkpoints/{id}/wait — champ d'application govern:checkpoints:readC'est vrai. Maintient la connexion ouverte jusqu'à ce que le point de contrôle change d'état ou que la cale s'écoule. La façon efficace d'attendre un humain.

• Demande timeout: tenir les secondes, 1–55 (par défaut) 50).
• 200 — changé; le corps est le nouvel état. 202 — pas de changement; reconnecter.

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

Débit recommandé#

1. POST /v1/checkpoints.
2. Si status est déjà terminal, agir dessus (et vérifier le jeton).
3. Si en attente, pollinisation longue /wait jusqu'au terminal.
4. À approuvé, vérifier le jeton de décision, puis la consommer à travers autorisation d'exécution immédiatement avant d'agir. Enregistrez chaque tentative et vérifiez l'effet. Sur quoi que ce soit d'autre, ne joue pas.