Skip to content
Press / to search

Workflow Examples

Three neutral end-to-end workflows through the canonical execution contract.

Implementation GuideLast reviewed: Edit on GitHub
At a glance

This page walks three reference workflows through the canonical execution contract end-to-end. Each shows: invokeAgent envelope → CompiledContext → planner / executor / critic transcript → DecisionRecord. Errors are first-class artifacts, not exceptions.

Customer support refund

Intent: support.refund · Risk class: destructive · Decision specs: support.refund.eligibility, support.refund.execute · Adapters: adp_orders.lookup, adp_policy.eval, adp_payments.issue_refund.

1. Request

{
  "request_id": "req_9f3a12",
  "session_id": "sess_42f1",
  "tenant_id": "tenant_acme_prod",
  "user": { "user_id": "usr_771", "delegation": { "auth_type": "oauth2", "scopes": ["orders.read", "payments.refund"] } },
  "agent": { "agent_id": "agt_support", "workload_identity": "spiffe://contextos/agents/support" },
  "context_pack_refs": ["ctxpack.support@5.2.0"],
  "input": {
    "intent": "support.refund",
    "message": "Refund order ord_881 for INR 4200.",
    "channel": "app_chat",
    "locale": "en-IN",
    "context": { "identity_verified": true, "order_id": "ord_881", "refund_amount": 4200, "currency": "INR" }
  },
  "mode": "stream",
  "runtime": { "max_tool_calls": 8, "max_cost_cents": 25.0 }
}

2. Compile

{
  "manifests": {
    "policy_manifest": [{ "bundle_id": "POLICY_RETURNS_V1", "rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_APPROVAL"] }],
    "tool_manifest": [
      { "adapter_id": "adp_orders", "capabilities": ["lookup"] },
      { "adapter_id": "adp_policy", "capabilities": ["eval"] },
      { "adapter_id": "adp_payments", "capabilities": ["issue_refund"] }
    ],
    "evidence_manifest": [{ "evidence_ref": "kg:order:ord_881#snapshot_kg_2026_05_03_T0930" }]
  },
  "runtime_controls": { "approval_gates_active": ["GATE_FINANCE_APPROVAL"], "must_refuse": [], "must_escalate": [], "redaction_rules_active": [] }
}

3. Plan

{
  "plan_id": "plan_refund_01",
  "intent": "support.refund",
  "steps": [
    { "id": "s1", "tool": "adp_orders.lookup", "params": { "order_id": "ord_881" } },
    { "id": "s2", "tool": "adp_policy.eval", "depends_on": ["s1"] },
    { "id": "s3", "tool": "adp_payments.issue_refund", "depends_on": ["s2"], "approval_mode": "destructive", "requires": ["GATE_FINANCE_APPROVAL"] }
  ],
  "decision_checkpoints": [
    { "decision_id": "support.refund.eligibility", "after_step": "s2" },
    { "decision_id": "support.refund.execute",     "after_step": "s2" }
  ]
}

4. Critic verifies

accept - every tool exists in tool_manifest, every argument validates, approval_mode on s3 matches the adapter’s binding, and GATE_FINANCE_APPROVAL is in runtime_controls.approval_gates_active.

5. Execute

s1 (read_only)        → tc_117 → ok, evidence_ref=tool:adp_orders.lookup:tc_117
s2 (read_only)        → tc_119 → ok, evidence_ref=tool:adp_policy.eval:tc_119
[checkpoint] support.refund.eligibility → DECIDED:eligible
[checkpoint] support.refund.execute     → verified before destructive action
s3 (destructive)      → propose → approver: user_finance_lead_77 → approve (frozen evidence sha256:b2a1...)
                      → tc_121 → ok, evidence_ref=tool:adp_payments.issue_refund:tc_121

6. DecisionRecord (final)

{
  "record_id": "dr_2026_05_04_a17",
  "decision_key": "support.refund.execute",
  "status": "DECIDED",
  "outputs": { "refund_amount_inr": 4200, "currency": "INR", "transaction_id": "txn_q9..." },
  "evidence_refs": [
    "kg:order:ord_881#snapshot_kg_2026_05_03_T0930",
    "tool:adp_orders.lookup:tc_117",
    "tool:adp_policy.eval:tc_119",
    "tool:adp_payments.issue_refund:tc_121"
  ],
  "approvals": [{
    "gate_id": "GATE_FINANCE_APPROVAL",
    "approver": "user_finance_lead_77",
    "approval_mode_effective": "destructive",
    "evidence_snapshot_hash": "sha256:b2a1..."
  }],
  "controls_active": { "approval_gates_active": ["GATE_FINANCE_APPROVAL"], "must_refuse": [], "must_escalate": [], "redaction_rules_active": [] },
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Error packets (illustrative)

  • Policy denial: tc_119 returns ToolResultEnvelope.status=rejected with policy_decision_id=pol_9899; Critic emits escalate; record status=ESCALATED.
  • Approval timeout: gate not answered within TTL; runtime persists ToolResultEnvelope.status=paused and the session is resumable by session_id.

Content moderation review

Intent: content.review · Risk class: delegated · Decision specs: content.review.classify, content.review.action · Adapters: adp_content.classify, adp_policy.eval, adp_queue.append, adp_content.publish_block.

1. Request

{
  "request_id": "req_qx88",
  "tenant_id": "tenant_acme_prod",
  "user": { "user_id": "usr_mod_404", "delegation": { "scopes": ["content.review"] } },
  "agent": { "agent_id": "agt_moderation", "workload_identity": "spiffe://contextos/agents/moderation" },
  "context_pack_refs": ["ctxpack.moderation@2.0.0"],
  "input": { "intent": "content.review", "message": "Review post pst_5512" },
  "mode": "batch"
}

2. Plan

{
  "plan_id": "plan_review_01",
  "steps": [
    { "id": "s1", "tool": "adp_content.classify", "params": { "post_id": "pst_5512" } },
    { "id": "s2", "tool": "adp_policy.eval", "depends_on": ["s1"] },
    { "id": "s3", "tool": "adp_queue.append", "depends_on": ["s2"], "approval_mode": "local_write",
      "execute_when": { "<": [{ "var": "outputs.s1.confidence" }, 0.7] } },
    { "id": "s4", "tool": "adp_content.publish_block", "depends_on": ["s2"], "approval_mode": "delegated",
      "requires": ["GATE_PUBLISH_BLOCK"],
      "execute_when": { ">=": [{ "var": "outputs.s1.confidence" }, 0.7] } }
  ],
  "decision_checkpoints": [
    { "decision_id": "content.review.classify", "after_step": "s2" },
    { "decision_id": "content.review.action",   "after_step": "s4" }
  ]
}

3. Verdict

For high-confidence policy violations, the runtime reaches s4 and pauses on GATE_PUBLISH_BLOCK. For low-confidence cases, the runtime reaches s3 and routes to the human queue without blocking.

4. DecisionRecord

{
  "record_id": "dr_qx88",
  "decision_key": "content.review.action",
  "status": "DECIDED",
  "outputs": { "action": "publish_blocked", "reason_code": "policy_violation_severe" },
  "evidence_refs": ["tool:adp_content.classify:tc_421", "tool:adp_policy.eval:tc_422"],
  "approvals": [{ "gate_id": "GATE_PUBLISH_BLOCK", "approver": "user_mod_lead_12", "approval_mode_effective": "delegated", "evidence_snapshot_hash": "sha256:c4d3..." }],
  "controls_active": { "approval_gates_active": ["GATE_PUBLISH_BLOCK"], "must_refuse": [], "must_escalate": [], "redaction_rules_active": [] },
  "trace_id": "9aa0..."
}

Error packets

  • Classifier disagreement with prior decisions: the Knowledge Graph returns a conflict: true on prior_outcomes for the same creator; Critic emits replan to request a senior reviewer.
  • Schema mismatch on s2: Tool Gateway returns failed with error_code=VALIDATION_ERROR; Executor returns control to Planner under re-plan budget.

Internal data lookup

Intent: data.lookup · Risk class: read_only · Decision spec: data.lookup.result · Adapters: adp_kg.query, adp_bi.snapshot.

1. Request

{
  "request_id": "req_lkp_91",
  "tenant_id": "tenant_acme_prod",
  "user": { "user_id": "usr_analyst_22", "delegation": { "scopes": ["bi.read"] } },
  "agent": { "agent_id": "agt_analyst", "workload_identity": "spiffe://contextos/agents/analyst" },
  "context_pack_refs": ["ctxpack.bi_lookup@1.4.0"],
  "input": { "intent": "data.lookup", "message": "Top 10 customers by LTV in APAC, last 30 days." },
  "mode": "batch"
}

2. Plan + Execute

s1: adp_kg.query        → tc_801 → ok, snapshot_pin=kg_2026_05_03_T0930
s2: adp_bi.snapshot     → tc_802 → ok, snapshot_pin=bi_2026_05_03_T1000
[checkpoint] data.lookup.result → DECIDED:returned

3. DecisionRecord

{
  "record_id": "dr_lkp_91",
  "decision_key": "data.lookup.result",
  "status": "DECIDED",
  "outputs": { "rows": [/* ... */] },
  "evidence_refs": ["kg:query:tc_801", "bi:snapshot:tc_802"],
  "approvals": [],
  "controls_active": { "approval_gates_active": [], "must_refuse": [], "must_escalate": [], "redaction_rules_active": ["pii_email"] },
  "trace_id": "11bb..."
}

Even for read_only, the workflow goes through the full canonical contract — pack pinning, snapshot pinning, evidence_refs, redaction_rules_active, trace propagation. This is what makes any past lookup auditable and replayable.

Error packets

  • Snapshot mismatch: the BI snapshot is older than the freshness window; Tool Gateway returns failed with error_code=STALE_SNAPSHOT; Critic emits replan to fetch a fresher snapshot or escalate if the budget is exhausted.

Pattern (across all three workflows)

StageSame shape?
invokeAgent envelopealways — only intent, pack_ref, and runtime budgets vary
CompiledContextalways — manifests + runtime_controls + budget_report
Planalways typed; steps differ by intent
Approval gatesonly for network, delegated, destructive
DecisionRecordalways — evidence_refs, approvals, controls_active, trace_id are non-negotiable

The shape is the contract. The variation is the pack.