Core Concepts

Agent Activity

Search agent runs, evidence bundles, proposals, replay records, query fingerprints, and business objects from one normalized lookup surface.

Overview

Agent Activity is the normalized lookup surface for audit and support investigations. Use it when a human knows a ticket, invoice, order, customer, workflow, capability, principal, request id, query fingerprint, proposal id, evidence id, replay id, or time window and needs to find what the agent saw or proposed.

It is not a chat log and it is not a raw evidence payload. It returns indexed activity rows that point to durable records: run ids, evidence_bundle_id values, proposal ids, replay ids, settlement decisions, query audit fingerprints, workflow names, capability names, business object ids, tenant scope, principal, state, and timestamps.

The fastest production path is still to store an audit receipt beside your app's business object when Synapsor returns a capability response. Agent Activity is the search fallback and reviewer surface when the exact handle is missing or when an incident spans many runs.

Use FROM AGENT ACTIVITY for broad lookup. Use INSPECT AGENT EVIDENCE when you only want activity rows that have evidence handles. Then open synapsor_evidence_bundles, synapsor_evidence_resources, synapsor_query_audit, synapsor_agent_write_proposals, synapsor_replay_records, or the workspace Activity/Evidence/Proposal views for details.

Find evidence later Evidence bundles Replay System views

What Agent Activity indexes

Index by the identifiers humans and systems actually have: tenant, principal, workflow, capability, business object id, request id, run id, evidence bundle id, proposal id, settlement id, replay id, query fingerprint, source table, state, and time window.

The activity row should be treated as a pointer to deeper records. It helps a reviewer find the right run first, then inspect evidence resources, proposal diffs, settlement policy versions, and replay checkpoints without searching logs.

indexed-fields.sql

-- Common lookup fields. Values such as tenant_id, principal, workflow,
-- business_object_id, and request_id come from your app/session or Synapsor
-- response envelope. Do not ask the model to invent these audit keys.
SELECT activity_kind, run_id, evidence_bundle_id, proposal_id, settlement_id,
       replay_id, request_id, workflow, capability, business_object_id,
       query_fingerprint, state, created_at
FROM AGENT ACTIVITY
WHERE tenant_id = 'acme'
  AND principal = 'support_agent_17'
ORDER BY created_at DESC
LIMIT 50;

Recommended app pattern

Store the returned Synapsor ids beside the customer-visible event in your own app. For example, a ticket timeline item can store run_id, evidence_bundle_id, proposal_id, workflow, capability, tenant_id, principal, query_fingerprint, and request_id.

When a reviewer opens the ticket, show the receipt first. If the receipt is missing or incomplete, search Agent Activity by business_object_id and time window.

receipt-to-activity.sql

-- Your app receipt points directly to Synapsor records.
SELECT synapsor_run_id, evidence_bundle_id, proposal_id, settlement_id,
       workflow_name, capability_name, query_fingerprint
FROM app_agent_audit_receipts
WHERE business_object_type = 'ticket'
  AND business_object_id = 'T-1042'
ORDER BY created_at DESC;

-- Fallback: search Synapsor by the same business object.
SELECT activity_kind, run_id, evidence_bundle_id, proposal_id, replay_id,
       workflow, capability, state, created_at
FROM AGENT ACTIVITY
WHERE tenant_id = 'acme'
  AND business_object_id = 'T-1042'
ORDER BY created_at DESC
LIMIT 50;

Developer notes

Store returned run, evidence, proposal, settlement, replay, request, workflow, capability, tenant, principal, business object, query fingerprint, and timestamp fields in your app audit receipt.
Use Agent Activity when the reviewer starts from a business object or time window instead of a pasted handle.
Use INSPECT AGENT EVIDENCE for evidence-only searches.
Open evidence resources, query audit, proposals, settlement, and replay records after finding the activity row.
Do not expose activity rows across tenant boundaries; lookup remains governed by RBAC and redaction policy.

Lookup syntax

SQL

-- Broad activity lookup by business object.
SELECT activity_kind, run_id, evidence_bundle_id, proposal_id, replay_id,
       workflow, capability, business_object_id, state, created_at
FROM AGENT ACTIVITY
WHERE tenant_id = 'acme'
  AND business_object_id = 'INV-3001'
ORDER BY created_at DESC
LIMIT 50;

-- Evidence-only lookup. Use this when the reviewer needs the rows/chunks
-- that supported an answer or proposal.
INSPECT AGENT EVIDENCE
WHERE tenant_id = 'acme'
  AND business_object_id = 'INV-3001'
  AND workflow = 'billing.late_fee_waiver_flow'
ORDER BY TIME DESC
LIMIT 50;

-- Then open the exact bundle and resources.
SELECT evidence_bundle_id, tenant_id, principal, capability, resource_count
FROM synapsor_evidence_bundles
WHERE evidence_bundle_id = 'evb_01HV...';

SELECT source_uri, source_table, source_column, business_object_id,
       query_fingerprint
FROM synapsor_evidence_resources
WHERE evidence_bundle_id = 'evb_01HV...'
ORDER BY rank;

Examples

typescript

const activity = await db.agentActivity.search({
  tenantId: "acme",
  businessObjectId: "INV-3001",
  workflow: "billing.late_fee_waiver_flow",
  capability: "billing.propose_late_fee_waiver",
  timeRange: { from: "2026-06-01T00:00:00Z", to: "2026-06-02T00:00:00Z" },
  limit: 50,
});

for (const row of activity) {
  console.log(row.run_id, row.evidence_bundle_id, row.proposal_id);
}