> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/getting-started/understanding-output.md). # 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: ```json { "agent_id": "ag_abc123", "task_id": "task-def456", "step": 1, "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": { "kyvvu.eval": { "action": "allow", "risk_score": 0.0, "policies": [] } }, "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). | | `step` | integer | The step number within the task. | | `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 access level, model info. | | `meta` | dict or null | Engine- and framework-reserved metadata. The engine stamps `kyvvu.eval` (the `action`, `risk_score`, and per-policy results from the pre-execution evaluation) on each recorded step; framework adapters add correlation fields (parent task ID, chain run ID). | | `timestamp` | ISO 8601 | When the agent initiated the step. | See [Atomic Behaviours](/core-concepts/behaviours.md) 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. On task completion (`end_task()`), the engine flushes all recorded steps. Where they go is `KV_LOG_LOCATION`, and its default is `auto`: the trace **follows the policy source**. An agent configured with `KV_API_KEY` and `KV_AGENT_KEY` gets its policies from the platform, so it sends its steps there too and they appear on the Logs page. An offline run — one driven by a local manifest (`KV_POLICY_FILE`, or `kyvvu try`) — prints to stdout instead, even in a shell that exports an API key, so a local trial never ships its trace to the network. To pin the destination yourself: ```bash export KV_LOG_LOCATION=https://platform.kyvvu.com # always the platform export KV_LOG_FORMAT=kv ``` ```bash export KV_LOG_LOCATION=stdout # always the terminal ``` To disable trace output entirely: ```bash 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 **Workspace → Platform Events**. Not something you configure in the SDK. *** ## Reading the trace in the dashboard When `KV_LOG_LOCATION` resolves to the platform API — which the default `auto` does for any agent whose policies come from the platform — 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: ```bash export KV_LOG_PAYLOADS=metadata_only ``` In this mode, each step's `input` and `output` are replaced with: ```json {"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](/core-concepts/behaviours.md) — the 12 behaviour types that form the vocabulary * [Policies and Rules](/core-concepts/policies.md) — how policies evaluate against behaviours * [Architecture](/core-concepts/architecture.md) — the three-package split and data flow