> ## Documentation Index
> Fetch the complete documentation index at: https://noesis-32c1d602-cursor-technical-documentation-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hello Episode: See Your Agent Think in 5 Minutes

> Run a tiny agent through Noēsis, open the artifacts, and read the timeline that shows every phase.

You want proof that Noēsis is actually recording how your agent thinks. This quickstart runs a minimal agent once, shows where the episode lands on disk, and reads the timeline so you see observe → interpret → plan → act → reflect in a few lines of code.

**Why this matters (the “wow”):** after one run you get a sealed evidence bundle you can diff, audit, and gate in CI.

<Tip>
  Learning path:

  1. Hello Episode (this page) → traces in 5 minutes.
  2. Governed Side Effects → enforce action\_candidate → governance → act.
  3. Trace-Based Evals → score behavior over traces.
</Tip>

## What you'll build

* A one-call episode using a local adapter (no LLM required)
* A recorded episode under `.noesis/episodes/<episode-id>/`
* A sealed evidence bundle you can diff (`final.json` + `manifest.json`)
* A timeline with phases and a couple of quick metrics

## Prerequisites

* Python environment with `noesis` installed (`uv add noesis` or `pip install noesis`)
* Optional: An OpenAI-compatible key in `OPENAI_API_KEY` if you later wire an LLM-backed adapter

## 1) Run your first episode (Python-first)

```python quickstart.py theme={null}
from __future__ import annotations

from pathlib import Path
import noesis as ns


DEMO_ROOT = Path("/tmp/noesis-demo")


def summarize_demo_files(task: str) -> str:
    _ = task
    readme = (DEMO_ROOT / "readme.txt").read_text(encoding="utf-8").strip()
    todo = (DEMO_ROOT / "todo.txt").read_text(encoding="utf-8").strip()
    todos = [line.strip("- ").strip() for line in todo.splitlines() if line.strip().startswith("-")]
    lines = [
        "Summary:",
        f"- README: {readme.splitlines()[0] if readme else '(empty)'}",
        f"- TODO items: {len(todos)}",
    ]
    if todos:
        lines.append("Next actions:")
        lines.extend([f"- {item}" for item in todos[:2]])
    return "\n".join(lines)


def main() -> None:
    DEMO_ROOT.mkdir(parents=True, exist_ok=True)
    (DEMO_ROOT / "readme.txt").write_text("Noesis demo workspace", encoding="utf-8")
    (DEMO_ROOT / "todo.txt").write_text("TODO\n- Add a safety policy\n- Write a short summary\n", encoding="utf-8")

    verify = [
        ns.file_exists("readme.txt"),
        ns.file_exists("todo.txt"),
        ns.file_contains("todo.txt", "TODO"),
    ]
    episode_id = ns.solve(
        "Summarize the demo files and propose next actions.",
        using=summarize_demo_files,
        workspace=str(DEMO_ROOT),
        verify=verify,
    )
    print("Episode ID:", episode_id)


if __name__ == "__main__":
    main()
```

Run it:

```bash theme={null}
python quickstart.py
```

<Note>
  Auth reminder: Noēsis does not create API keys for you. Set `OPENAI_API_KEY` before running any LLM-backed adapters.
</Note>

## 2) Open the episode folder

Episodes are written to `.noesis/episodes/<episode-id>/`. Inspect the files:

```bash theme={null}
ls .noesis/episodes/<episode-id>/
```

| File            | What it tells you                                                                 |
| --------------- | --------------------------------------------------------------------------------- |
| `events.jsonl`  | The full timeline: observe, plan, act, reflect (plus timestamps and causal links) |
| `summary.json`  | Outcome and metrics (success, plan\_count, act\_count, latencies)                 |
| `state.json`    | The persisted plan/state at the end of the run                                    |
| `manifest.json` | Checksums for integrity                                                           |
| `final.json`    | The seal: if present, the episode is finalized                                    |

## 3) Read the timeline

```python read_timeline.py theme={null}
import noesis as ns


def show_timeline(episode_id: str):
    for event in ns.events.read(episode_id):
        phase = event["phase"]
        payload = event.get("payload", {})
        status = payload.get("status") or payload.get("reason") or "ok"
        print(f"[{phase:<8}] {status}")


if __name__ == "__main__":
    eid = "<episode-id>"  # paste from the previous step
    show_timeline(eid)
```

You should see phases like `observe`, `interpret`, `plan`, `act`, `reflect` with concise statuses. That is the "agent brain" trace users keep asking for.

## 4) Inspect a couple of metrics

```python read_metrics.py theme={null}
import noesis as ns
import json


def load_metrics(episode_id: str):
    summary = ns.summary.read(episode_id)
    metrics = summary.get("metrics", {})
    print(json.dumps({
        "success": metrics.get("success"),
        "plan_count": metrics.get("plan_count"),
        "act_count": metrics.get("act_count"),
        "latency_ms": metrics.get("latencies", {}).get("total_ms"),
    }, indent=2))


if __name__ == "__main__":
    load_metrics("<episode-id>")  # paste the same ID
```

This is enough to prove that Noēsis is capturing the agent’s trajectory, not just the final answer.

## Next steps

* Move to guardrails: [Governed Side Effects](/tutorials/governed-side-effects) to see vetoes in traces.
* Move to evals: [Trace-Based Evals](/tutorials/trace-based-evals) to score behavior across tasks.