Quick Start

In about five minutes you will have a running agent, a policy that it violates, and your first incident.

This guide assumes:

• The Kyvvu API is running at http://localhost:8000

• The dashboard is running at http://localhost:3000

• The Python SDK is installed (pip install -e ./sdk or the GitHub install)

If you haven't set up the stack yet, see Installation first.

---

Step 1 — Check your credentials

When the stack starts for the first time, it seeds a root user and an API key from your .env file. Open .env and note these two values:

[email protected]
KV_SEED_ROOT_PASSWORD=CHANGE_ME_SECURE_PASSWORD
KV_SEED_ROOT_API_KEY=KvKey-CHANGE_ME_GENERATE_RANDOM_STRING

You'll use the email and password to log into the dashboard, and the API key in your agent code.

Verify the API is up:

curl http://localhost:8000/health
# → {"status":"healthy", ...}

---

Step 2 — Write a minimal agent

Create a file called hello_agent.py. This agent does exactly four things: starts, makes a (fake) LLM call, waits for human approval, and ends. Each step is logged to Kyvvu via the @kv.log_step decorator.

from kyvvu import Kyvvu
import os

# Initialize the Kyvvu compliance layer
kv = Kyvvu(
    api_key=os.getenv("KV_SEED_ROOT_API_KEY"),
    api_url="http://localhost:8000",
)

# Register the agent
kv.register_agent(
    agent_key="hello-agent",
    name="Hello Agent",
    purpose="Demonstrates Kyvvu compliance logging",
    owner_id="[email protected]",
    risk_classification="limited",
    environment="development",
)


class HelloAgent:

    @kv.log_step("START_NODE")
    def start(self, user_input: str) -> str:
        """Receive input and kick off the task."""
        return f"Processing: {user_input}"

    @kv.log_step("LLM_CALL")
    def generate_response(self, prompt: str) -> str:
        """Call an LLM (mocked here for simplicity)."""
        return f"Here is a helpful response to: {prompt}"

    @kv.log_step("HUMAN_APPROVAL")
    def await_approval(self, draft: str) -> str:
        """Human reviews the draft before it goes out."""
        print(f"\n--- Draft for review ---\n{draft}\n------------------------")
        approved = input("Approve? (y/n): ").strip().lower()
        return "approved" if approved == "y" else "rejected"

    @kv.log_step("END_NODE")
    def finish(self, outcome: str) -> None:
        """Close out the task."""
        print(f"Task complete. Outcome: {outcome}")


if __name__ == "__main__":
    agent = HelloAgent()

    prompt = "What is the capital of France?"

    result = agent.start(prompt)
    draft  = agent.generate_response(result)
    status = agent.await_approval(draft)
    agent.finish(status)

Run it:

export KV_SEED_ROOT_API_KEY=KvKey-your-key-here
python hello_agent.py

You should see the agent run through its steps and prompt you for approval. Behind the scenes, four log entries have been created and chained together in the audit trail.

---

Step 3 — See the agent and its logs in the dashboard

Open http://localhost:3000 and log in with the email and password from your .env.

Navigate to Agents — hello-agent should be listed there. Click it to see its details.

Navigate to Logs — you'll see the four steps (START_NODE, LLM_CALL, HUMAN_APPROVAL, END_NODE) recorded for the task that just ran. Click any step to inspect its input, output, and hash.

Run the agent a few more times if you want to see multiple tasks accumulate.

---

Step 4 — Create a policy

Now let's give Kyvvu something to enforce. You'll create a policy that requires every agent to declare an owner_id. Your agent already has one — so you'll also register a second, non-compliant agent to trigger a violation.

In the dashboard, navigate to Policies → New Policy, and fill in:

Field	Value
Name	Owner ID required
Scope	agent_registration
Rule type	require_field
Field name	owner_id
Severity	high
Enabled	✓

Save the policy.

Alternatively, create it via the API:

# First, get a JWT token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"CHANGE_ME_SECURE_PASSWORD"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Create the policy
curl -X POST http://localhost:8000/api/v1/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Owner ID required",
    "scope": "agent_registration",
    "rule_type": "require_field",
    "params": {"field_name": "owner_id"},
    "severity": "high",
    "enabled": true
  }'

---

Step 5 — Trigger an incident

Register a new agent without an owner_id. Add this to the bottom of hello_agent.py (or a new file):

kv.register_agent(
    agent_key="bad-agent",
    name="Agent Without Owner",
    purpose="Intentionally missing owner_id",
    risk_classification="limited",
    environment="development",
    # owner_id deliberately omitted
)

Run it. The registration will succeed (Kyvvu logs violations, it doesn't block by default), but the policy violation is detected immediately and an incident is created.

---

Step 6 — Review the incident

In the dashboard, navigate to Incidents. You'll see a new high-severity incident:

Owner ID required — Agent bad-agent violated policy at registration.

Click the incident to see its details: which policy was violated, which agent, when, and in which environment.

From here you can mark it as Resolved (you fixed it), Ignored (accepted risk), or leave it Active for someone else to triage. Incidents are permanent audit records — they don't disappear.

---

What just happened

In five steps you:

1. Registered an agent with its compliance metadata

2. Logged a four-step task execution with a tamper-evident hash chain

3. Created a policy that checks agent registrations

4. Triggered a violation and had an incident auto-created

5. Reviewed and triaged the incident in the dashboard

That's the core loop. From here:

• Add more policies — use policy templates for a full governance framework in one click (Policies → Templates)

• Add more step types — instrument your real agent with @kv.log_step on every meaningful operation

• Generate an audit report — Reports → Generate covers any date range in PDF or XML

• Set up automated actions — route critical incidents to Slack or email under Settings → Actions

For a fully worked example with a real LLM and branching logic, see Custom Python Agent.