Open-source · Go 1.23+ · MIT-licensed

KIFF

Trust infrastructure for AI-operated systems.

A governance protocol between agent proposals and execution. The agent proposes; the runtime decides whether the proposal is allowed to execute.

Try the demo View on GitHub Read the docs

propose · curl

curl https://demo.kiff.dev/refund \
  -H 'content-type: application/json' \
  -d '{"order":"ord_001","amount":4900,"reason":"customer request"}'

decide · response

{
  "outcome": "executed",
  "action": "AUTO_REFUND",
  "entity_id": "ord_001",
  "audit_url": "https://demo.kiff.dev/admin/entities/ord_001"
}

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.

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://demo.kiff.dev/refund \
  -H 'content-type: application/json' \
  -d '{"order":"ord_001","amount":4900,"reason":"customer request"}'

decide · response

{
  "outcome": "executed",
  "action": "AUTO_REFUND",
  "entity_id": "ord_001",
  "audit_url": "https://demo.kiff.dev/admin/entities/ord_001"
}

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://demo.kiff.dev/refund \
  -H 'content-type: application/json' \
  -d '{"order":"ord_002","amount":99900,"reason":"customer request"}'

decide · response

{
  "outcome": "approval_required",
  "action": "REFUND_ORDER",
  "approval_id": "appr_xyz",
  "review_url": "https://demo.kiff.dev/admin/approvals/appr_xyz"
}

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 -X POST https://demo.kiff.dev/admin/approvals/appr_xyz/grant \
  -H 'content-type: application/json' \
  -d '{"reviewer":"ops-human","note":"verified with customer"}'

decide · response

{
  "outcome": "approval_granted",
  "approval_id": "appr_xyz",
  "action": "REFUND_ORDER",
  "executed": true,
  "audit_url": "https://demo.kiff.dev/admin/entities/ord_002"
}

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 -X POST https://demo.kiff.dev/admin/approvals/appr_xyz/deny \
  -H 'content-type: application/json' \
  -d '{"reviewer":"ops-human","note":"order disputed"}'

decide · response

{
  "outcome": "blocked",
  "approval_id": "appr_xyz",
  "action": "REFUND_ORDER",
  "executed": false,
  "reason": "approval_denied"
}

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://demo.kiff.dev/refund \
  -H 'content-type: application/json' \
  -d '{"order":"ord_003","amount":4900,"reason":"customer request"}'

decide · response

{
  "outcome": "blocked",
  "action": "AUTO_REFUND",
  "reason": "state_not_allowed",
  "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

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