agentreplay

Capture n8n workflow executions as shareable replay URLs. Loom for agent runs.

Package Information

Downloads: 3 weekly / 165 monthly
Latest Version: 0.1.0
Author: Sharad Selvam

Available Nodes

AgentReplay Trace icon
AgentReplay Trace
Capture this workflow run as a shareable replay URL

Documentation

n8n-nodes-agentreplay

Loom for agent runs.

AgentReplay makes any n8n execution a shareable link — a step-by-step timeline
with failures highlighted. Drop the AgentReplay Trace node in a workflow, run it,
send the URL. Debugging agents becomes a paste, not a screen-share.

Works in any n8n instance, cloud or self-hosted.

For n8n users — install in 60 seconds

1. Install the node

In n8n: Settings → Community Nodes → Install, then enter:

n8n-nodes-agentreplay

(Self-hosted, headless: set N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true and
install the same package name.)

2. Add the AgentReplay API credential — see Credentials.

3. Use it

Drop the AgentReplay Trace node anywhere in a workflow (typically at the
end). Run the workflow. The node's output item contains a replayUrl — open
it to see the run timeline with failed steps highlighted.

Screenshot placeholder — replace with a capture of a failed run's replay page.
![AgentReplay replay page](docs/replay-screenshot.png)

Example

Import demo/workflow.json: a 5-node workflow where an
"LLM tool call" deliberately 500s. The run shows a red failed step and
AgentReplay still emits a shareable replayUrl — that is the whole pitch. Step
through it with scripts/local-test.md.

Credentials

AgentReplay API — API-key auth.

Field Required Default Notes
API Key yes — Sent as Authorization: Bearer <key>. Create one at https://agentreplay.dev.
Backend URL no https://agentreplay.dev/api Override only for self-hosted backends.

The credential Test button issues GET {backendUrl}/health and expects
200. Traces are sent as POST {backendUrl}/traces, which returns
{ "id": "...", "url": "https://agentreplay.dev/r/..." }.

For the n8n team / reviewers

Why this exists

Agent reliability is a communication problem before it's an engineering one.
"Check the execution log" doesn't travel across people, tools, or time zones.
AgentReplay collapses a run into one link that drops into any bug report, Slack
thread, or customer ticket — no screen-share, no "works on my machine." One
community node, zero infra to adopt.

What's in v0.1

  • One node (AgentReplay Trace) + one credential (AgentReplay API).
    Programmatic style — custom payload composition and conditional output.
  • Two capture modes: Input Only (this node's input items) and Upstream
    Snapshot     (previous node + this node as a two-step trace, via public
    getInputSourceData() + getWorkflowDataProxy() only).
  • Trace schema (trace-schema.ts) designed to map onto OpenTelemetry GenAI
    conventions in v2 without breaking changes.
  • Best-effort failure detection (an upstream error key marks a step failed),
    passThrough toggle, continueOnFail honored, dependency-free UUIDv7.
  • Honest scope boundary: the host n8n runtime version is not exposed to
    community nodes through any stable API, and reading it via process is
    forbidden by the n8n Cloud lint ruleset — so source_version reports this
    package's version. See the roadmap.

v1 roadmap

  • Native upstream-execution capture API integration — full multi-node run
    capture once a stable host API exists (v0.1 is best-effort, previous-node only).
  • OpenTelemetry GenAI export — emit traces in OTel GenAI semantic conventions.
  • Automatic failure taxonomy — classify failures (timeout, auth, rate-limit,
    schema, model-refusal) instead of a raw error string.
  • Per-step LLM trace nodes — capture prompts, completions, token usage, and
    tool calls as first-class spans.
  • Screenshot capture for browser-step nodes — visual replay of browser
    automation steps.
  • True host runtime-version capture — once n8n exposes it to community nodes.

Publishing (maintainer)

Publishing to npm requires provenance attestation (n8n community-node
requirement since 2026-05-01). The inherited .github/workflows/publish.yml
handles this via GitHub OIDC — do not modify its permissions: block.

  1. On npmjs.com: package settings → Publish access → Trusted Publishers.

  2. Add a publisher: GitHub Actions, repo
    nocoder26/n8n-nodes-agentreplay, workflow publish.yml, environment
    blank.

  3. Push a version tag — the workflow publishes with --provenance
    automatically:

    git tag v0.1.0 && git push --tags

Development

npm install
npm run dev      # @n8n/node-cli: compile + linked n8n + hot-reload
npm run build    # compile + copy assets to dist/
npm run lint     # n8n-node lint (n8n Cloud compatibility checks)

End-to-end testing: scripts/local-test.md.

License

MIT © 2026 Sharad Selvam

Discussion