Hosted workflow

Agent write proposal approval flow

Let an agent prepare a write, then require human approval before commit.

Problem

Team tools need agent-assisted writes, but direct writes from an LLM are too risky.

Why app glue gets messy

Read-only agents cannot finish work. Direct-write agents create audit and rollback problems.

How Synapsor helps

Synapsor capabilities can run in proposal mode, attach evidence, and expose a diff before approval.

Value sources

Example names and seed ids are developer-defined. SESSION values are set by your backend. ARG values come from the SDK/HTTP call. Handles such as wrp://..., evidence://..., and agent-run://... are returned by Synapsor and should be stored for audit/replay.

Read the value-source guide

Expected outcome

A reviewer sees the proposal, evidence, and SQL diff before committing the change.

Production checks

The capability cannot commit without an approval step.
The proposal contains the affected rows and branch diff.
Rejected proposals leave the main branch unchanged.
Commit writes an audit event with reviewer and reason.

schema.sql

CREATE TABLE invoices (
  id INT PRIMARY KEY,
  tenant_id VARCHAR NOT NULL,
  customer_id VARCHAR NOT NULL,
  status VARCHAR NOT NULL,
  late_fee_cents INT NOT NULL
);

agent.ddl.sql

CREATE AGENT WORKFLOW billing.late_fee_waiver_flow
SESSION REQUIRE tenant_id, principal, current_invoice_id
ALLOWED CAPABILITIES (
  billing.propose_late_fee_waiver
)
EVIDENCE REQUIRED
AUTO BRANCH ON PROPOSAL
CHECKPOINT EVERY STEP
ON RISK medium REQUIRE APPROVAL ROLE 'billing_reviewer';

CREATE AGENT CONTEXT billing.invoice_context
ROOT invoices AS invoice
LOOKUP invoice.id = SESSION current_invoice_id
BIND tenant_id FROM SESSION tenant_id
BIND principal FROM SESSION principal
OUTPUT SLOTS
  invoice_id AS invoice.id,
  customer_id AS invoice.customer_id,
  status AS invoice.status,
  late_fee_cents AS invoice.late_fee_cents
EVIDENCE ON;

CREATE AGENT CAPABILITY billing.propose_late_fee_waiver
DESCRIPTION 'Create a previewable late-fee waiver proposal'
ARG invoice_id INT64 REQUIRED
ARG reason VARCHAR REQUIRED
HIDDEN tenant_id FROM SESSION tenant_id
HIDDEN principal FROM SESSION principal
USE CONTEXT billing.invoice_context
EXECUTION PROPOSAL
RETURNS JSON '{"type":"object","properties":{"proposal":{},"branch":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only
WRITE PROPOSAL TARGET invoices
OPERATION UPDATE
LOOKUP id FROM ARG invoice_id
TENANT tenant_id FROM BINDING tenant_id
COLUMNS late_fee_cents FROM VALUE 0,
        reviewer FROM BINDING principal,
        decision_note FROM ARG reason
AUDIT billing_audit
SUMMARY TEMPLATE 'Waive late fee for invoice {invoice_id}';

python

run = db.agent_runs.start(
    workflow="billing.late_fee_waiver_flow",
    input={"invoice_id": 3001, "request": "Waive the late fee"},
)

proposal = run.invoke_capability(
    "billing.propose_late_fee_waiver",
    step_key="propose_late_fee_waiver",
    arguments={"invoice_id": 3001, "reason": "card update failure"},
    mode="propose_only",
    auto_branch=True,
    response_envelope=True,
)

proposal_id = proposal["proposal"]["proposal_id"]
db.approve_write(proposal_id, reason="Reviewed support ticket and policy evidence")
committed = db.commit_write(proposal_id)
print(committed["status"])