Use notebook exports with agents

A notebook export gives an agent a finite, named data source. The agent can verify the complete export, select an exported state, decode a supported output, and retain the identities needed to reproduce its answer.

Read a verified output

Build the first notebook export, then verify it in machine mode:

uv run marimo-export verify dist/report --json

Stable result shape:

{
  "ok": true,
  "result": {
    "assets": 0,
    "bytes_verified": 0,
    "outputs": 2,
    "states": 2
  }
}

Read the monthly summary and retain its evidence identity:

from marimo_export import open_export

notebook_export = open_export("dist/report")
state = notebook_export.state("monthly")
output = state.output("summary")

evidence = {
    "export_sha256": notebook_export.identity,
    "spec_sha256": notebook_export.spec_sha256,
    "state_sha256": state.fingerprint,
    "output": output.name,
    "codec": output.codec,
    "media_type": output.media_type,
    "python_type": output.descriptor.provenance.python_type,
}

print(output.json())

The selected representation determines what the agent can inspect. Pair a chart or widget with JSON, Parquet, Arrow, or NumPy data when an answer depends on exact values.

Retain the evidence chain

Keep these facts with a data-driven answer or generated application:

• notebook filename and document SHA-256
• ExportSpec SHA-256
• notebook export identity from canonical index.json
• marimo and marimo-export producer versions
• state name, complete inputs, and state fingerprint
• output name, codec, media type, and stored Python type. Exporter-backed outputs record marimo_export.outputs.BlobAsset
• asset SHA-256 when the output references an asset
• complete-export verification result

Verification proves that files match index.json. It does not authenticate the publisher. Bind publisher identity through the storage, origin, signature, or release mechanism used by the deployment.

Ask an agent to create an export

An agent can use the CLI as a bounded workflow:

mkdir -p dist
uv run marimo-export inspect report.py --json
uv run marimo-export plan report.py --spec report.export.yaml --json
uv run marimo-export build report.py \
  --spec report.export.yaml \
  --output dist/report \
  --jsonl
uv run marimo-export verify dist/report --json

File inspection and preparation execute notebook code with the producer process's environment, working directory, file access, credentials, packages, and network access. Review the notebook and selected outputs before allowing an agent to run them.

The plan reports complete state vectors, reusable state fingerprints, and missing work. Preparation and reuse defines when an exact match can return before notebook startup and how external data freshness enters producer identity and marimo caching.

Ask an agent to create a browser application

The repository includes a notebook-to-static-app workflow. It guides an agent through notebook inspection, ExportSpec authoring, preparation, application implementation, and browser validation.

Require the resulting application to:

• exercise every exported state
• keep the last committed view during rapid changes
• dispose replaced mounts
• surface recoverable errors
• load notebook results from the deployed export origin
• open no Python kernel or WebSocket for exported state changes

Use Build a browser application for the consumer lifecycle and Troubleshooting for evidence to collect when an agent workflow fails.