How GreenLightz Works

A deterministic policy evaluation engine. One API call between your AI agent and the customer. Sub-millisecond latency. Zero external runtime dependencies.

For operations leaders

See every commitment your AI agents make before it reaches the customer. Set monetary ceilings and approval thresholds per action type — no code changes needed.

For engineering teams

One API endpoint, any language. JSON Schema contracts for type generation. Sub-millisecond overhead. No SDK lock-in, no agent framework dependency.

For security and compliance

Cryptographically signed evidence for every evaluation. Zero PII stored. Fail-closed by design — system errors never produce false approvals.

AI Agent

"Issue $150 refund"

GreenLightz Engine

Policy evaluation + intervention

Response

AMBER — reduce to $75

Real API contract

JSON Schema (Draft-07) contracts are published for TypeScript, Python, Go, and Java code generation. Additive-only stability guarantee — fields are never removed or renamed.

Request

POST /gateway/evaluate

{
  "action_type": "credit_or_refund.issue",
  "tenant_id": "acme_corp",
  "actor_id": "agent-7b",
  "target_id": "customer-4492",
  "amount_cents": 15000,
  "currency": "USD",
  "reason": "Product arrived damaged",
  "correlation_id": "conv-8812-msg-3",
  "metadata": {
    "original_transaction_id": "txn-9284"
  }
}

Response

200 OK

{
  "verdict": "REQUIRE_APPROVAL",
  "evidence_ref": "ev-8a3f2b91-c7e4-...",
  "evidence_hash": "sha256:b94d1f2a3e5c...",
  "reasons": [
    "Amount $150.00 exceeds pre-authorized limit $75.00",
    "30-day customer aggregate: $420.00"
  ],
  "policy_version": "v1.3.0",
  "evaluated_at": "2026-03-02T14:30:00Z",
  "signed": true,
  "intervention_plan": {
    "action": "modify_and_retry",
    "band": "amber",
    "recommended_client_behavior": "MODIFY_AND_RETRY",
    "safe_degrade_actions": [
      "lower_amount"
    ],
    "retry_guidance": {
      "max_retries": 3,
      "cooldown_seconds": 0,
      "stop_condition": "action_allowed_or_max_retries_exhausted"
    }
  }
}

Three verdicts. Deterministic. No ambiguity.

Same input always produces the same verdict. The decision path is fully traceable through the signed evidence packet.

Green

API value: ALLOW

Action is within all policy bounds. The agent proceeds without modification.

Amber

API value: REQUIRE_APPROVAL

Action exceeds a soft limit. The intervention planner returns a concrete modification — reduce amount, adjust scope, or degrade gracefully — and the agent retries automatically.

Red

API value: BLOCK

Hard policy violation. The action is denied with a signed evidence packet documenting the exact rule that triggered the block.

Integration in 4 steps

Works with any agent framework, any language. The only requirement is an HTTP client.

1. Intercept the action

Before your AI agent executes any commitment, POST the action details to /gateway/evaluate. One HTTP call, sub-millisecond response. No SDK or agent framework required.

2. Receive verdict + intervention plan

The engine returns a deterministic verdict (ALLOW, REQUIRE_APPROVAL, or BLOCK), the policy rules that fired, and — for amber verdicts — a concrete intervention plan telling the agent how to modify and retry.

3. Agent acts on the plan

Your agent follows the intervention plan: proceed as-is, reduce the amount to fit within policy, or stop. The retry loop converges automatically — no human in the loop for routine actions.

4. Immutable evidence trail

Every evaluation produces a cryptographically signed evidence packet with a deterministic content hash. The chain is append-only and tamper-evident. Compliance-ready from day one.

The intervention loop

Amber verdicts don't just say "no." They tell your agent exactly what to change. The agent modifies and retries — automatically, with no human in the loop.

Agent request

$150 refund

AMBER verdict

"Reduce to $75"

Auto-retry

$75 refund

GREEN verdict

Approved

Structured guidance

The intervention_plan field returns machine-readable instructions: reduce amount, adjust scope, switch to draft mode. No free-form parsing needed.

Automatic convergence

The retry_guidance field specifies max retries and stop conditions. The loop converges to an approved action or stops cleanly — never infinite.

Safe degradation

The safe_degrade_actions field lists exactly which modifications are safe: lower amount, reduce scope, require user confirmation. No guesswork.

Beyond single-transaction rules

Simple amount thresholds are easy to game. GreenLightz evaluates across multiple risk dimensions simultaneously — each one is a separate veto gate.

Financial impact

Per-action-type ceilings, pre-authorization limits, and daily caps. Different policies for different action types.

Velocity detection

Per-agent, per-customer frequency tracking across configurable rolling windows. Catches agents making 5 refunds in one hour.

Aggregate exposure

Rolling-window cumulative tracking. A $50 refund alone is fine — but $420 total from the same customer this month triggers escalation.

Behavioral patterns

Stacking detection and precedent analysis. Catches when commitments are split across multiple small transactions to avoid ceilings.

Dimensions are configurable per tenant. Shadow dimensions let you observe new rules without affecting production verdicts.

Policy is data, not code

Each tenant gets a YAML configuration file. Change the file, change the governance. No deployments, no code changes, no downtime.

max_amount_cents

Per-action-type amount ceilings. Set different limits for refunds, discounts, and shipping commitments.

pre_authorized_limit

Auto-approve threshold. Actions below this amount get instant GREEN — no human review needed.

approval_mode

Escalation behavior: manual (human reviews all amber), pre_authorized (auto-approve under limit), or block (deny all).

enabled_dimensions

Which governance dimensions are active: financial impact, policy compliance, behavioral patterns. Add or remove to tune.

webhook_url / webhook_secret

Approval notification endpoint. Secrets use env-ref indirection — never inline in configuration.

policy_version

Semantic version tag for drift detection. The engine tracks which policy version produced each verdict.

Same engine, different behavior

The same refund request can get ALLOW under one tenant's policy and REQUIRE_APPROVAL under another's. Swap the YAML file — no code changes, no deployments, no downtime. Thresholds and operational configuration are tuned together during pilot onboarding.

Ready to govern your AI agents?

30-minute live demo. We'll walk through the API, fire real evaluations, and show the evidence trail.

Book a Demo