Understanding the Output

What you'll learn: What a behavioral trace is, what each field means, and the three kinds of "logging" in Kyvvu.

---

The behavioral trace

Every step your agent takes produces a structured JSON record — a Behavior. The complete sequence of Behaviors within a task is the behavioral trace. This is the audit trail Kyvvu produces.

A single Behavior looks like:

{
  "agent_id": "ag_abc123",
  "task_id": "task-def456",
  "scope": "step",
  "step_type": "step.model",
  "verb": "POST",
  "step_name": "call_llm",
  "input": {"prompt": "What's the weather?"},
  "output": {"response": "(mocked response)"},
  "properties": {"model": {"name": "gpt-4o"}},
  "meta": null,
  "timestamp": "2026-04-29T10:00:00+00:00"
}

Field reference

Field	Type	Description
agent_id	string	The registered agent's unique identifier.
task_id	string	Identifies this task (one end-to-end agent execution).
scope	"task" or "step"	Whether this is a task lifecycle event or an agent action.
step_type	string	The atomic behaviour type (step.model, step.resource, task.start, etc.).
verb	string or null	HTTP-style verb (GET, POST, PATCH, DELETE) or null.
step_name	string	A human-readable name for the step (function name, tool name).
input	dict or null	The step's input data (function arguments, prompt, query).
output	dict or null	The step's output data (function return value, response).
properties	dict	Structured metadata — target system, auth scope, model info.
meta	dict or null	Framework-specific metadata (parent task ID, chain run ID).
timestamp	ISO 8601	When the step was recorded.

See Atomic Behaviours for the complete vocabulary of step types and valid combinations.

---

Three kinds of "logging"

Kyvvu involves three distinct logging concepts. They are unrelated and should not be confused:

1. Application logging (Python logger)

Standard Python logging output from the Kyvvu engine and SDK. Controlled by KV_LOG_LEVEL. Set to DEBUG for detailed per-evaluation traces:

kyvvu_engine.engine DEBUG evaluate(): agent_id=agent-123 step_type=step.model → action=allow risk_score=0.00

This is diagnostic output for debugging. It goes to stderr.

2. Behavioral trace logging (engine batch flush)

The structured JSON Behaviors described above. By default, these are printed to stdout as JSON lines. On task completion (end_task()), the engine flushes all recorded steps.

To send traces to the Kyvvu platform API instead of stdout:

export KV_LOG_LOCATION=https://platform.kyvvu.com
export KV_LOG_FORMAT=kv

To disable trace output entirely:

export KV_LOG_LOCATION=none

3. Platform event logging (API events module)

Server-side audit trail in the Kyvvu platform. Records platform-level events (policy changes, user logins, agent registrations). Visible in the dashboard under Events. Not something you configure in the SDK.

---

Reading the trace in the dashboard

When KV_LOG_LOCATION points to the platform API, behavioral traces appear in the dashboard:

1. Navigate to Logs in the sidebar.

2. Filter by agent, task ID, or time range.

3. Click a task to see the full ordered sequence of steps.

4. Each step shows its evaluation result (allow/warn/block), applicable policies, and the Behavior data.

The dashboard also validates the hash chain — a tamper-evident chain linking each log entry to the previous one. If any entry has been modified after ingestion, the chain validation will fail.

---

Payload redaction

For GDPR-sensitive environments, you can redact input/output from the trace:

export KV_LOG_PAYLOADS=metadata_only

In this mode, each step's input and output are replaced with:

{"redacted": true, "keys": ["prompt"], "length": 42}

Shape is preserved (you can see which fields were present and their approximate size), but content is stripped.

---

Next steps

• Atomic Behaviours — the 12 behaviour types that form the vocabulary

• Policies and Rules — how policies evaluate against behaviours

• Architecture — the three-package split and data flow