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",
  "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 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 queues all recorded steps, and a background worker delivers them; a short script calls kv.flush() before it exits.

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:

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

export KV_LOG_LOCATION=stdout                      # always the terminal

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 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 platform hash-chains each task's entries when it ingests them. The hash input fields are agent_id, task_id, step, input_data (the stored input), and previous_hash (only when a previous entry exists). The chain does not cover step_type, verb, timestamp, output, properties, or meta; changing only those fields does not fail validation. See #630 for the planned hash-format change. The SDK sends plain entries and does not compute the chain, and a trace written to stdout or a file carries no chain. The dashboard validates the covered fields against stored hashes.

---

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