# Introduction

**The Behavioral Firewall for AI Agents.**

Kyvvu is a governance platform that evaluates policies against the full execution path of your AI agent — before each step runs. It decides **allow**, **warn**, or **block** in sub-millisecond time, directly inside your agent process. No proxy. No gateway. No perceptible latency.

***

## The first 5 minutes

```bash
pip install kyvvu

kyvvu register
# → creates your account, returns an API key

kyvvu init my-agent
# → scaffolds a demo agent project

cd my-agent
pip install -r requirements.txt
export KV_API_KEY=KvKey-...
python agent.py
```

The demo agent runs three decorated steps (a model call, a resource read, and a code execution). Without policies assigned, all steps pass. To see enforcement in action:

```bash
kyvvu list-manifests
kyvvu assign-manifest --agent-id <id> --repo-id 1 --manifest owasp_agentic_default.yaml
python agent.py
```

Now the OWASP policy "Code execution requires a preceding gate" blocks the `step.exec`:

```
Policy blocked this step: ...
   Risk score: 1.00
   Action:     block
   * Code execution requires a preceding gate (critical)
```

That's runtime policy enforcement — policies defined in a YAML manifest, assigned to your agent, evaluated against the full task history.

For why this architecture matters, see the blog post: [The Hot Path Tax](https://kyvvu.com/blog/2026/04/29/hot-path-tax/).

***

## Architecture

```
Your Agent Code
  |  @kv.step / LangChain handler / REST API
  v
kyvvu SDK (translates events -> Behaviors)
  |  template.match() -> deep_merge -> Behavior
  v
kyvvu-engine (in-process, sub-ms policy evaluation)
  |  evaluate() -> allow / warn / block
  |  record() -> append to task history
  |  end_task() -> flush behavioral trace
  v
Kyvvu Platform API (platform.kyvvu.com)
  |  policy storage, incident management, audit trail
  v
Dashboard (platform.kyvvu.com)
  |  policy config, incident triage, reports
```

The engine runs **in your process**. Policy evaluation is pure CPU — no network calls, no database queries, no I/O. Policies are fetched in the background and cached. Log flushing happens asynchronously on task completion.

***

## What Kyvvu does

1. **Registration enforcement** — agents must declare their purpose, tools, and risk classification before they can start. Policies validate these declarations at startup.
2. **Runtime policy evaluation** — every atomic step your agent takes is evaluated against loaded policies *before* execution. Decisions depend on the full ordered history of the current task ("policies on paths").
3. **Behavioral trace logging** — completed steps are recorded into an audit trail, flushed to the platform API on task completion. The trace is a structured JSON record of everything the agent did.
4. **Incident management** — policy violations generate incidents that surface in the dashboard for triage, acknowledgment, and resolution.

***

## Quick links

| Resource      | URL                                                                                     |
| ------------- | --------------------------------------------------------------------------------------- |
| Documentation | [docs.kyvvu.com](https://docs.kyvvu.com)                                                |
| Platform      | [platform.kyvvu.com](https://platform.kyvvu.com)                                        |
| GitHub        | [github.com/Kyvvu/platform](https://github.com/Kyvvu/platform)                          |
| PyPI          | [pypi.org/project/kyvvu](https://pypi.org/project/kyvvu)                                |
| Paper         | [Runtime Governance for AI Agents: Policies on Paths](https://arxiv.org/abs/2603.16586) |
| Jobs          | [kyvvu.com/join](https://kyvvu.com/join/)                                               |

***

## Next steps

* [Installation](/getting-started/installation.md) — install the SDK and set up your account
* [Your First Agent](/getting-started/first-agent.md) — walk through `kyvvu init` step by step
* [Architecture](/core-concepts/architecture.md) — understand the three-package split and why the engine is in-process
* [Creating Policies](/policy-authoring/creating.md) — author your first custom policy


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyvvu.com/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.