Agent workflows and run graphs

Agent frameworks decide what to do next.

Synapsor decides what is allowed, what must be recorded, what evidence is required, what can be written, what needs approval, and how the whole run can be replayed.

Outside Synapsor, teams often build Agent framework + MCP tools + vector DB + normal DB + app glue + audit logs + approval code. With Synapsor, the shape becomes Agent framework + Synapsor workflow contract + Synapsor MCP/framework adapter.

The agent can still use LangGraph, OpenAI Agents SDK, CrewAI, MCP, or a custom planner. It is the database-side contract those orchestrators call into when a step touches customer data, policy, writes, memory, side effects, or audit state.

In plain English, this says: for this refund workflow, the agent is only allowed to use these approved capabilities. It must have trusted tenant, user, ticket, and customer values. It must attach evidence. A risky Synapsor-native write must stage on a branch, while a risky external Postgres/MySQL write must stage as a Synapsor review branch. Every step must be recorded. If risk is medium, a support lead must approve.

That is very different from telling the model: please be careful, use policy, ask for approval if needed, and do not refund twice.

Prompts are advice. A Synapsor workflow is a database contract.

A LangGraph graph might say: triage -> policy lookup -> billing tool -> approval -> answer.

A Synapsor workflow says: this billing workflow requires tenant_id, principal, current_ticket_id, and current_customer_id; only these reviewed capabilities are allowed; evidence is required; refund proposals must stage as native branches or Synapsor review branches depending on target; medium-risk actions require support_lead approval; every step must be retained for replay.

Use LangGraph, OpenAI Agents SDK, CrewAI, MCP, or your own loop for orchestration: deciding the next node, collecting the user response, calling the next tool, or waiting for a human.

Use Synapsor for the durable contract around that orchestration: trusted session keys, allowed capabilities, required evidence, Synapsor-native branch-staged writes or external review-branch proposals, external-action idempotency, approval rules, settlement policy, memory policy, retention, and replay.

The practical integration is simple: pass run_id and step_key from your framework into Synapsor calls whenever the step touches customer data, policy, memory, proposals, external actions, or audit state.

Synapsor workflows do not make the model smarter. They make the agent's durable actions safer, clearer, replayable, and easier to approve.

The sections below show the practical effect: fewer low-level tools, trusted session fields, automatic evidence, native branches or external review branches for risky writes, and replayable run graphs.

Without Synapsor, the model may see many low-level tools: get_customer, get_ticket, search_policy, get_invoice, issue_refund, update_ticket, send_email, save_memory, and write_audit_log.

With Synapsor, the model can see fewer high-level tools such as answer_ticket_with_evidence, propose_refund, and settle_agent_run.

Synapsor handles tenant binding, evidence, RBAC, branches, approvals, proposals, replay, and audit behind those tools.

Values such as tenant_id, principal, current_customer_id, current_ticket_id, region, and entitlement should come from trusted backend session context, not model JSON.

The workflow can require those session fields before a run starts, and the capability can copy them into HIDDEN bindings. The caller can still provide ARG values such as question or amount_cents, but ARG values do not override HIDDEN values.

Without Synapsor, the app has to retrieve policy, include it in the prompt, save chunk ids, show citations, log evidence, and make replay possible.

Evidence becomes automatic: EVIDENCE REQUIRED and INLINE EVIDENCE handles_only let the agent receive compact handles while Synapsor keeps the durable why trail.

That keeps repeated context and evidence out of the prompt while preserving inspectable evidence for humans, support review, and replay.

Risky writes become proposals: AUTO BRANCH ON PROPOSAL means the agent proposes a change, Synapsor stages it on a Synapsor-native branch or an external-source review branch depending on target, and a human or settlement policy decides what can proceed later.

The application or framework can request a write, but the workflow contract decides whether that write must be staged, reviewed, settled, committed, merged for native data, or approved for trusted writeback for external data. Rejected proposals leave production unchanged.

The whole run becomes replayable: a run can carry run_id, step_key, capability invocation id, evidence id, proposal id, branch name, external action id, guardrail event, handoff or interrupt event, and final output.

A workflow run is useful only if operators and developers can reconstruct it later. Synapsor stores the run, ordered steps, edges, evidence lookup records, proposals, branches, external actions, guardrail events, handoffs, interrupts, and final output.

Use EXPLAIN AGENT RUN for the graph-shaped view. Use system views when you need SQL-level inspection for support, incident review, regression evals, or customer audit.

Synapsor workflows do not replace LangGraph, OpenAI Agents SDK, CrewAI, MCP, or a custom planner. They give those systems a durable database contract for sensitive steps.

Synapsor does not guarantee safe AI by prompt text alone. The value is in enforceable session binding, RBAC, evidence requirements, branch-staged proposals, deterministic settlement, and replayable records.

Synapsor does not pretend an outside API call can be rolled back by a database transaction. External actions are recorded as durable intents, claimed by trusted workers with idempotency keys, and confirmed back into the run graph.