Agent Integration

This page is the compact contract a coding agent should follow when adding Keel to an application. It does not require access to Keel’s private architecture.

Integration algorithm

1. Inventory consequential actions. Find every path that can spend money, send data, mutate external state, call tools, execute code, or use privileged credentials. Inventory direct SDK calls, raw HTTP, queues, retries, fallbacks, background workers, and tool callbacks—not only the main request handler.
2. Choose an enforcement boundary. Prefer a supported Keel-managed route when Keel should own dispatch. Use permit-first only when a trusted component in the application will enforce the decision before the downstream call.
3. Keep credentials human-owned. Ask the operator to create and place Keel and provider credentials through an approved secrets path. Never request, print, commit, or persist a raw credential in generated code or chat.
4. Use the documented request shape. Validate requests against the generated schema and route reference. Supply a client-controlled idempotency key on retryable operations.
5. Require positive authority. A negative safeguard or unmatched rule is not authorization. For consequential public Permit admission, the exact action must be covered by applicable positive policy authority. An unmatched evaluator result alone is not authority to dispatch.
6. Branch on the public decision vocabulary. Only allow authorizes the exact action. deny, review, and throttle are blocking outcomes. Apply all returned constraints before dispatch.
7. Fail safely. On authentication, validation, timeout, unavailable-service, unknown-decision, or malformed-response failures, do not send the governed downstream request. A fallback that calls the provider directly is a bypass.
8. Preserve evidence identifiers. Record the Keel request ID and Permit UUID without logging secrets or sensitive payloads. Use documented receipt, proof-pack, or export verification for the evidence level required.
9. Test both outcomes. Prove that an allowed test request reaches the intended downstream system and that a denied request produces no downstream effect. Use a provider-side or target-side oracle for the latter; a Keel decision record alone does not prove absence of execution.
10. Re-scan for bypasses. Search for direct provider clients, alternate credentials, retry fallbacks, async workers, and ungoverned tool paths after the integration is complete.

Decision handling

const permit = await createPermit(request)
 
switch (permit.decision) {
  case 'allow':
    return dispatchWithConstraints(permit.constraints)
  case 'throttle':
    return retryLater(permit)
  case 'deny':
  case 'review':
    return holdWithoutDispatch(permit)
  default:
    return failClosed('unknown Keel decision')
}

For Keel-managed SDK wrappers, a non-allow result is normally surfaced before provider dispatch. Use the SDK’s supported governance metadata helper rather than assuming the provider response object exposes raw HTTP headers.

Enforcement boundaries

Always confirm the exact action in Surface Maturity and the Capability Matrix. A route being mounted does not establish that every nested provider tool or operation is governed.

Evidence and verification boundary

Signature and hash verification can establish supported integrity, authenticity, binding, and lineage properties under the selected trust root. It does not by itself prove that every relevant event was captured, that policy was correct, or that an external side effect occurred—or did not occur. Use Verifying Evidence and keep downstream-effect tests separate from Keel evidence validation.

Completion checklist

• Every consequential path is either governed or explicitly documented as out of scope.
• Unknown decisions and Keel unavailability block the downstream action.
• Only allow opens the exact authorized action.
• Constraints are enforced at the final trusted dispatch boundary.
• A denied integration test shows no downstream effect using independent target-side evidence.
• Permit and request IDs are retained; secrets and raw sensitive payloads are not logged.
• The selected route and action are marked public-claim-eligible at the needed maturity level.

Related pages

• Authentication
• Quickstart
• Policy Reference
• Decision Model
• Execution Architecture
• Scope and Limits
• Verifying Evidence