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.
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.
| Argument | Default | What it does | |
|---|---|---|---|
| kind | required | The kind of step: ActionKind.step_model, ActionKind.step_resource and so on. | |
| verb | none | An HTTP-style verb such as Verb.GET or Verb.POST. | |
| step_name | the function's name | The name policies see. Declared tools are matched on it. | |
| properties | {} | Metadata merged into the step, such as the model or the target system. | |
| capture_input | true | Record the function's arguments as the step's input. | |
| capture_output | true | Record 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.