Quickstart: agents and the API

Ask CognaOne before an agent takes a consequential action. Start in observe mode, read the decisions, then enforce.

1. Connect the facts#

Connect the systems where the facts your agent relies on are created. Each connected source gets a signed intake URL, and its events become governed state that CognaOne versions and checks for conflicts. See Sources and intake.

2. Ask before acting, in observe mode#

Call the gate with the action your agent wants to take. In observe mode the decision is recorded but nothing is blocked, so you can see what would happen.

POST https://api.cognaone.com/api/actions/evaluate
Authorization: Bearer <agent token>
Content-Type: application/json

{
  "threadId": "thr_claims_0142",
  "actionType": "payment.release",
  "clientRequestId": "req_7f3c91",
  "payload": { "amount": 48000, "currency": "AUD" },
  "evaluationMode": "observe"
}

3. Handle the decision, then enforce#

Once the decisions are the ones you expect, switch to enforce and act only on what the gate allows.

const res = await evaluate({ threadId, actionType: 'payment.release', payload, clientRequestId });

switch (res.decision) {
  case 'allow':
    return releasePayment();
  case 'warn':
    log.warn(res.reasonCodes);       // proceed, but surface the warning
    return releasePayment();
  case 'defer':
    return waitForApproval(res);     // an approval or more facts are needed
  default:
    return askForHelp(res);          // block or error: do not act
}

Decisions at a glance: Allow Warn Defer Block See Decisions and verdicts. Keys such as claim.approved_amount are explained in Canonical keys.

What next#

Gate APIDecisions, reasons and receipts in detail.MCP serverUse the gate as a tool from MCP-capable agents.Integration patternsRoll out one agent at a time, safely.

Last reviewed October 2026Suggest a change