# 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",
  "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](/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. 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:

```bash
export KV_LOG_ENDPOINT=https://platform.kyvvu.com/api/v1/logs/batch
```

To disable trace output entirely:

```bash
export KV_LOG_ENDPOINT=
```

### 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_ENDPOINT` 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:

```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


---

# 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/getting-started/understanding-output.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.