Kyvvu

Integration · SDK

Kyvvu for Python

Put @kv.step on the functions your agent calls. Each call is checked against the task's path before it runs, and recorded after.

Read the docs

Set up

A few lines, then every step is checked.

Blocked means not run
A blocked step raises KyvvuBlockedError and the function doesn't execute. The attempt is recorded.
Tasks
Steps run inside kv.start_task() and kv.end_task(), one task per request your agent handles.
Async too
async def functions work as they are; each thread or asyncio task gets its own task.
from kyvvu import Kyvvu, ActionKind, Verbkv = Kyvvu(api_url="https://platform.kyvvu.com", api_key="KvKey-...", agent_key="my-bot")kv.register_agent(    name="My Bot",    purpose="Customer support triage and response",    declared_tools=["read_ticket"],)@kv.step(ActionKind.step_model)def chat(prompt: str) -> str:    return llm.complete(prompt)@kv.step(ActionKind.step_resource, Verb.GET)def read_ticket(ticket_id: str) -> dict:    return db.get_ticket(ticket_id)

The decorator

One decorator, a few arguments.

@kv.step(kind, verb) runs the evaluate, execute and record cycle for you. The rest is optional.

ArgumentDefaultWhat it does
kindrequiredThe kind of step: ActionKind.step_model, ActionKind.step_resource and so on.
verbnoneAn HTTP-style verb such as Verb.GET or Verb.POST.
step_namethe function's nameThe name policies see. Declared tools are matched on it.
properties{}Metadata merged into the step, such as the model or the target system.
capture_inputtrueRecord the function's arguments as the step's input.
capture_outputtrueRecord the return value as the step's output.

When a policy says no

The function doesn't run.

A blocked step is recorded and KyvvuBlockedError is raised before the function executes. What happens next is up to your code.

The task stays open
A block never ends a task. Close it with kv.error_task(), or get approval and retry.
Approve, then retry
Record a step.gate and call the action again. Gate rules look past the blocked attempt.
Gates pass on a normal return
A gate function denies by raising GateDenied. Returning anything else records a pass.
from kyvvu import KyvvuBlockedErrortry:    result = run_dangerous_action()except KyvvuBlockedError as exc:    print(f"Blocked: {exc}")    print(f"Risk score: {exc.result.risk_score}")    for p in exc.result.policies:        if p.violated:            print(f"  - {p.name} ({p.severity})")

Good to know

  • Python 3.11 or newer.
  • Declare your tools when you register the agent: the bundled baseline blocks resource, exec and credential steps that aren't on the list.
  • Steps run inside a task. kv.end_task() is what sends the steps on, so a short script should finish with kv.flush().
  • In a web server each thread or asyncio task gets its own task; a new request doesn't inherit one.
  • Where a function can't be decorated, kv.add_step() records a step by hand.

Next

Try it before you install it.

In your browser

The playground

Build an agent's path, pick a policy and watch the engine decide.

On your machine

Five minutes, no account

kyvvu try runs a demo agent against the bundled baseline.

For your team

Request a demo

See it on the agents you actually run.