Core Concepts

Replay

Replay reruns a captured agent workflow against the original or current context.

Overview

Replay is how you debug, audit, and regression-test agent behavior. The implemented replay path is the agent-run replay API; SQL is used for historical reads and creating investigation branches from a run snapshot.

The run_id value is produced by Synapsor when a capability invocation is recorded. Use the agent_run_id field from the response envelope, the agent-run:// resource, or synapsor_agent_runs; do not invent a run number.

Replay is linked from the same trail as evidence and proposals. If you start from a proposal, follow it back to the originating run and evidence bundle; if you start from a business object, find the run with FROM AGENT ACTIVITY by tenant/principal, workflow, capability, query fingerprint, request id, and time window.

The default deterministic persisted replay returns the stored run, evidence, memory provenance, resource pins, and audit trail without re-running side effects.

Comparison replay modes such as original_snapshot, current, version, timestamp, and branch are for read-only capabilities. Write/proposal capabilities should be investigated by creating a branch from the original agent-run snapshot.

Agent Activity Find evidence later Evidence bundles Write proposals

Developer notes

Store run ids with user-visible outputs.
Grant READ on the agent-run resource before exposing replay to auditors.
Use deterministic persisted replay for audits that must show what was captured at run time.
Use current replay before changing prompts, contexts, or policies.
Create a branch from the agent-run snapshot before investigating write/proposal capabilities.
Compare evidence bundle ids during investigations.

Implemented replay API

REST

POST /v1/agent/runs/replay
Authorization: Bearer <database-api-key>
Content-Type: application/json

{
  "run_id": 123,
  "session": {
    "tenant_id": "acme",
    "principal": "auditor_01"
  },
  "mode": "deterministic_persisted_replay"
}

Notes:
  run_id comes from a prior INVOKE/PROPOSE response or synapsor_agent_runs.
  tenant_id/principal are trusted session values for the replay request.

Examples

bash

# Replace 123 with the agent_run_id returned by INVOKE/PROPOSE.
curl -fsS https://synapsor.ai/v1/agent/runs/replay \
  -H "Authorization: Bearer $SYNAPSOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "run_id": 123,
  "session": {
    "tenant_id": "acme",
    "principal": "auditor_01"
  },
  "mode": "deterministic_persisted_replay"
  }'