Open-source · Go 1.23+ · MIT-licensed

AI systems start on the wrong layer.

Most teams begin with prompts, then tools, then workflows.

The problem starts when those workflows touch money, people, inventory, customers, or infrastructure. KIFF is a protocol and runtime for governed AI actions. It turns agent proposals into validated, approved, auditable decisions before execution.

See the problem View on GitHub Read the whitepaper

propose · curl

curl https://api.kiff.dev/v1/entities/ord_001/actions/AUTO_REFUND/execute \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "entity_type": "order",
    "actor": {"id": "ops-agent", "type": "agent", "roles": ["operator"]},
    "parameters": {"amount": 49.0, "reason": "customer request"}
  }'

decide · response

{
  "result": {
    "action_name": "AUTO_REFUND",
    "entity_id": "ord_001",
    "status": "succeeded",
    "executed": true,
    "message": "auto-refund of $49.00 issued"
  }
}

The response is not just JSON. It is the record of what KIFF allowed, held, or blocked. Real wire shape against api.kiff.dev/v1. Mint your own tenant key with the integration walkthrough.

Problem · the wrong layer

Where AI operations fail.

Probabilistic systems are being connected to deterministic consequences. The issue is not that the model is useless. The issue is that every new layer adds more authority without adding a shared execution contract.

ambiguous
Prompt
The instruction sounds right, but it is not an enforceable contract.
side effect
Tool call
The agent can now order, refund, send, update, or delete.
drift
Workflow
Steps multiply, retries happen, each path handles risk differently.
fragmented
State machine
Each team invents its own lifecycle, approvals, and exceptions.
unprovable
Audit
Logs say something happened, but not why it was allowed.

Wrong layer. Prompt rules are easy to change and hard to prove.

Missing boundary. The model can propose and execute through the same path.

No common shape. Agents, tools, and workflows do not share one decision record.

The shape · six primitives, one loop

Between proposal and execution.

KIFF puts a runtime between the agent and your real systems. Every action is a contract: allowed states, required parameters, required permissions, risk, approval requirement. The agent proposes; the runtime decides.

Failures return typed errors. Successes append events that drive the next state transition. Everything ends up in the audit trail. Replay produces the same state from the same events.

Why · prompt is the wrong layer

Free-form tool calls vs. action contracts.

Most AI features start at the prompt. They work in development, then break the first time an agent confidently does the wrong thing in production. KIFF is a different layer: the runtime between proposal and execution.

without kiff · python

# the agent calls your real system directly.
# state guards live in the prompt, if they live anywhere.

def refund(order_id: str, amount: int, reason: str) -> dict:
    db.update("orders", id=order_id, status="REFUNDED")
    stripe.refund(order_id, amount=amount)
    return {"ok": True}

# llm chooses inputs. nothing checks the order is paid.
# nothing requires approval at $99,900. no audit trail.

with kiff · go

// the agent records a proposal. the runtime decides.
return action.ActionContract{
    Name:                "REFUND_ORDER",
    AllowedStates:       []string{"PAID"},
    RequiredParameters:  []string{"amount", "reason"},
    RequiredPermissions: []permission.Permission{"orders.refund"},
    Risk:                action.RiskHigh,
    ApprovalRequirement: action.ApprovalRequired,
    Executor:            refundOrderExecutor,
}

The agent does not call refundOrderExecutor directly. It records a proposal. The runtime checks current state, parameters, permissions, and approval before any executor runs. Failures return typed errors. Successes append events that drive the next state transition.

Product surface · the receipt

A receipt your system and your auditors can use.

Kiff Cloud returns a signed, versioned decision receipt before execution. Not because it is another payload — because it reduces the business risk around AI actions.

Customer trust
Show why an AI action was held, blocked, or approved instead of asking customers to trust a black box.
Audit readiness
Keep a consistent record of who proposed, what rule applied, and what happened next.
Dispute defense
When something goes wrong, reconstruct the decision path instead of searching scattered logs.
Operational control
Downstream systems can require a valid KIFF receipt before executing risky actions.

receipt contract · json

{
  "receipt_id": "rcpt_01J8Z9...",
  "trace_id": "trace_01J8Z8...",
  "tenant": "kiff-demo",
  "entity": "order:ord_002",
  "action": "REFUND_ORDER",
  "decision": "approval_required",
  "reason": "amount_above_threshold",
  "domain_version": "refund-ops-v2",
  "policy_version": "inventory-v2",
  "issued_by": "kiff-cloud",
  "signature": "kiff_sig_3f8a...",
  "audit_url": "/v1/entities/order:ord_002/timeline",
  "anchor": "base-sepolia:0x2F5468..."
}

This is the example shape. A real, freshly-signed receipt from a successful action on Kiff Cloud is rendered at /dashboard/receipts/trace-receipt-prod-1. Same JSON; live signature; the audit timeline is one click away.

Scenarios · same domain, different outcomes

One agent. Five honest endings.

Each scenario is a real KIFF run, scripted on this page so you can read the request, the response, the audit trail, and the rationale together. No live backend; the same JSON the framework's worked examples produce locally.

Small refund

executed

Low-risk refund on a paid order. Auto-execute, audit, done.

propose · curl

curl https://api.kiff.dev/v1/entities/ord_001/actions/AUTO_REFUND/execute \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "entity_type": "order",
    "actor": {"id": "ops-agent", "type": "agent", "roles": ["operator"]},
    "parameters": {"amount": 49.0, "reason": "customer request"}
  }'

decide · response

{
  "result": {
    "action_name": "AUTO_REFUND",
    "entity_id": "ord_001",
    "status": "succeeded",
    "executed": true,
    "message": "auto-refund of $49.00 issued"
  }
}

Audit trail · 7 records

time	kind	actor	summary
09:41:02.123	event_ingested	stripe	ORDER_PLACED
09:41:02.124	state_changed	stripe	CREATED → PAID
09:42:11.001	decision_recorded	ops-agent	propose AUTO_REFUND
09:42:11.002	action_validated	ops-agent	AUTO_REFUND ✓
09:42:11.005	action_executed	ops-agent	AUTO_REFUND
09:42:11.006	event_ingested	ops-agent	ORDER_REFUNDED
09:42:11.007	state_changed	ops-agent	PAID → REFUNDED

rebuild: materialized state matches replay ✓

Order is PAID. Amount is below the auto-execute threshold. AUTO_REFUND requires no approval. KIFF runs it.

Large refund

approval required

High-risk refund. KIFF holds execution and asks a human.

propose · curl

curl https://api.kiff.dev/v1/entities/ord_002/actions/REFUND_ORDER/execute \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "entity_type": "order",
    "actor": {"id": "ops-agent", "type": "agent", "roles": ["operator"]},
    "parameters": {"amount": 999.0, "reason": "customer request"}
  }'

decide · response

# 422 Unprocessable Entity
{
  "error": "action requires approval",
  "action": "REFUND_ORDER",
  "approval_id": "appr_xyz"
}

# next: POST /v1/entities/ord_002/actions/REFUND_ORDER/approvals
# (open the approval, then a human reviewer grants or denies it)

Audit trail · 4 records

time	kind	actor	summary
09:48:02.001	event_ingested	stripe	ORDER_PAID
09:48:02.002	state_changed	stripe	PAID
09:50:18.430	decision_recorded	ops-agent	propose REFUND_ORDER (high)
09:50:18.431	approval_required	ops-agent	REFUND_ORDER awaiting human

rebuild: materialized state matches replay ✓

REFUND_ORDER is high-risk. ApprovalRequirement is required. KIFF blocks execution and opens a review record.

Approval granted

approval granted

A reviewer signs off on the held refund. KIFF executes the original proposal.

propose · curl

curl https://api.kiff.dev/v1/approvals/appr_xyz/grant \
  -X POST \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "actor": {"id": "ops-human", "type": "human", "roles": ["ops_operator"]},
    "reason": "verified with customer"
  }'

decide · response

{
  "approval": {
    "id": "appr_xyz",
    "status": "granted",
    "action_name": "REFUND_ORDER",
    "entity_id": "ord_002",
    "reviewed_by": "ops-human",
    "reviewed_at": "2026-05-24T09:53:55.011Z"
  }
}

# Re-issue the original execute call with approval_id=appr_xyz to run it.

Audit trail · 4 records

time	kind	actor	summary
09:53:55.011	approval_granted	ops-human	REFUND_ORDER granted
09:53:55.092	action_executed	ops-agent	REFUND_ORDER
09:53:55.093	event_ingested	ops-agent	ORDER_REFUNDED
09:53:55.094	state_changed	ops-agent	PAID → REFUNDED

rebuild: materialized state matches replay ✓

Approval was granted by a human reviewer. KIFF marks the context approved and runs the original proposal.

Approval denied

blocked

A reviewer rejects the held refund. The action never runs.

propose · curl

curl https://api.kiff.dev/v1/approvals/appr_xyz/deny \
  -X POST \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "actor": {"id": "ops-human", "type": "human", "roles": ["ops_operator"]},
    "reason": "order disputed"
  }'

decide · response

{
  "approval": {
    "id": "appr_xyz",
    "status": "denied",
    "action_name": "REFUND_ORDER",
    "entity_id": "ord_002",
    "reviewed_by": "ops-human",
    "reviewed_at": "2026-05-24T10:01:20.004Z"
  }
}

# A denied approval is terminal. Subsequent execute calls
# under the same context return state_not_allowed.

Audit trail · 2 records

time	kind	actor	summary
10:01:20.004	approval_denied	ops-human	REFUND_ORDER denied
10:01:20.005	action_blocked	ops-agent	REFUND_ORDER not executed

rebuild: materialized state matches replay ✓

A denied approval is terminal. KIFF will not run the action even if the same proposal is retried under the same context.

Unpaid order

blocked

Refund attempted on an unpaid order. State guard blocks before any executor runs.

propose · curl

curl https://api.kiff.dev/v1/entities/ord_003/actions/AUTO_REFUND/execute \
  -H 'authorization: Bearer kiff_live_<tenant>_<random>' \
  -H 'content-type: application/json' \
  -d '{
    "entity_type": "order",
    "actor": {"id": "ops-agent", "type": "agent", "roles": ["operator"]},
    "parameters": {"amount": 49.0, "reason": "customer request"}
  }'

decide · response

# 422 Unprocessable Entity
{
  "error": "state not allowed",
  "action": "AUTO_REFUND",
  "current_state": "CREATED",
  "allowed_states": ["PAID"]
}

Audit trail · 4 records

time	kind	actor	summary
10:14:09.220	event_ingested	stripe	ORDER_PLACED
10:14:09.221	state_changed	stripe	CREATED
10:15:30.118	decision_recorded	ops-agent	propose AUTO_REFUND
10:15:30.119	action_blocked	ops-agent	state_not_allowed

rebuild: materialized state matches replay ✓

AUTO_REFUND requires PAID. Order is CREATED. KIFF refuses to call the executor; the LLM's confident proposal does not become a state change.

Cloud audit records are tamper-evident: anyone can verify them independent of the cloud's database.

Examples · two operational stories

Two examples, two proofs.

Pick an example. Each one is a concrete situation; the runtime is the difference between confident proposals and honest endings.

Same refund agent. Different authority.

An agent confidently proposes a refund. KIFF decides whether it can actually happen.

without kiff agent calls your system directly

agent calls refund() directly
refund executes — no questions asked

with kiff agent records a proposal

auto-execute on small refunds
approval_required on large refunds
blocked on unpaid orders

View outcome table · 3 rows

input	outcome	note
small refund · PAID	executed	auto-execute
large refund · PAID	approval_required	human review
refund · CREATED	blocked	state guard

Vision · not the product yet

The operational view for AI systems.

The receipt and the timeline are the data layer. The operational view is what teams will see: entities, proposals, decisions, receipts, and audit timelines in one canvas. Read the trajectory, not a roadmap commitment.

The pattern is familiar from cluster ops — single canvas, time-travel diff, root-cause traversal. KIFF's version is bounded to AI-operated systems: every cell carries a policy version, every state change carries a verifiable anchor, every approval carries the reviewer's identity.

Out of scope today. The receipt and audit timeline ship now; the canvas is the next surface.

What KIFF is not

Not a replacement for what you already use.

KIFF is a different layer: the governance protocol between agent proposals and execution. It composes with whatever you already use.

not an agent framework — keep using LangGraph, Agno, OpenAI Agents SDK
not a workflow engine — keep using Temporal, Inngest
not a managed agent platform — keep using Modal, Lambda, your own runtime
not a model gateway — keep talking to your model provider directly
not an app builder

Run it locally · about five minutes

Three commands to a governed loop.

One Go install, one template, one make target. You get a Go domain, an HTTP server, a deterministic stub agent (Bedrock with one flag), and a make demo that runs the governed loop end to end.

1 · install

go install github.com/kiffhq/kiff/cmd/kiff@latest

2 · scaffold

kiff new -template=agentic-ops github.com/your/project
cd project

3 · run the demo

make demo
# auto-execute, approve-then-execute, block-on-missing-consent
# escalate, close — five outcomes, one governance loop

AI systems start on the wrong layer.

Prompt

Tool call

Workflow

State machine

Audit

Customer trust

Audit readiness

Dispute defense

Operational control