Description

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

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