Connect an existing agent

Already have an agent making tool calls? You don’t need the scaffold or a rewrite. Attach the guard, watch what the agent actually does, let KIFF derive a starter domain from that real traffic, then turn on enforcement so the consequential calls are governed — and the agent keeps doing the work.

This is the on-ramp for the agent you already run. The quickstart starts a governed action from scratch; this page meets you where your agent already is.

1. Install the guard

The guard is an open-source (MIT) Python package, kiff/kiff-guard. Install the core plus the adapter for your framework — here, Agno:

pip install "git+https://github.com/kiff/kiff-guard.git#subdirectory=packages/python/kiff-guard"

The core has zero required dependencies; each framework adapter pulls its own framework in as an optional extra.

The guard isn’t on PyPI yet, so the install is from git for now. A pip install kiff-guard line lands when the package is published — this page updates the moment it does, never before.

2. Attach it in observe mode

One guard, one hook. observe runs every tool, records a receipt, and learns your action catalog. It needs no client, no tenant, no API key — it never calls KIFF and never blocks a tool.

from kiff_guard import Guard
from kiff_guard.adapters.agno import agno_hook

guard = Guard(mode="observe")     # no client, no tenant needed

agent = Agent(
    model=...,
    tools=[refund_order, send_email],
    tool_hooks=[agno_hook(guard)],
)

On a different stack? The hook is the only line that changes. Every framework page shows the same attach with that framework’s one-liner, and How the guard works explains the model behind all of them.

3. Run as usual, and see what it did

Nothing about your agent changes — run it the way you already do. The guard rides along on each tool call and turns each into a receipt.

agent.run("Refund order ord_4821 and email the customer")

for r in guard.receipts:
    print(r.state, r.tool, r.outcome)
# observed refund_order observed
# observed send_email   observed

4. Derive a domain from real traffic

Because the guard learned the catalog while it watched, it hands you a starter KIFF domain drafted from what the agent actually does — so you never face a blank kiff.yaml:

from kiff_guard import export_yaml
print(export_yaml("my-domain", guard.catalog))

# KIFF domain draft for 'my-domain'
# Auto-derived from observed agent traffic (instrument-first).
domain: my-domain
actions:
  - name: refund_order
    parameters: [amount_cents, order_id]
    risk: low            # TODO(human): low | medium | high
    requires_approval: false   # TODO(human)
  - name: send_email
    parameters: [body, to]
    risk: low            # TODO(human): low | medium | high
    requires_approval: false   # TODO(human)

The draft is a starting point — you set the risk, thresholds, and approval rules. KIFF derives the observed action surface; it never invents authority you didn’t declare.

5. Turn on enforcement

When you’re ready, switch the guard to enforce, point it at your tenant, and KIFF decides before each tool runs — allowed proceeds, approval_required holds for a human, blocked refuses. Same one-line attach, same receipts; now the risky calls are governed.

guard = Guard(mode="enforce", client=client)   # client carries the key

Provision a runtime key

Enforcement needs a runtime API key for your tenant. Today you mint it in the dashboard — Keys → create — scoped to a role, and put it in the agent process’s environment:

export KIFF_CLOUD_URL=https://api.kiff.dev
export KIFF_CLOUD_API_KEY='kiff_live_...'

Keep two credential types separate:

• the KIFF runtime key authorizes the agent to ask KIFF for a decision — it can’t grant itself authority; the key’s role governs what’s permitted server-side;
• your provider credentials (the model API, your payments API) stay where they already live. KIFF never holds or proxies them.

A kiff auth login / kiff keys create CLI to mint and write keys in one command is on the way (it isn’t shipped yet — until it is, mint in the dashboard). This page will show it once it lands.

Where to go next

• The model behind observe/enforce → How the guard works.
• Your framework’s one-liner → pick it from the sidebar; ten adapters are shipped and verified.
• Start one from scratch instead → the quickstart scaffolds a governed refund with kiff new.
• No Go, just HTTP? → Govern one action over HTTP, or drop in the five-line proposal call.

The guard, every adapter, and the conformance suite live in the public MIT repo kiff/kiff-guard. docs.kiff.dev owns the guided journey; the repo owns the code.