Workflow Examples

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

Implementation GuideLast reviewed: 2026-10-16 Edit on GitHub

At a glance

This page walks three illustrative deployment workflows through the canonical execution envelopes. Each shows: invokeAgent envelope → CompiledContext → planner / executor / critic transcript → DecisionRecord. The repository does not execute these external systems. Applicable policy-expression failures throw a structured ContextCompileError; the invocation boundary must report that non-success safely rather than treating the predicate as false.

Admit exact profiles and actual enabled features before work. These enterprise examples start with contextos.enterprise@1; durable/delegated work adds its required profile and conditional controls. The compatible Execution Contract binds current authority, complete action/approval intent, boundary/data routes, stable operations and shared budget. Abbreviated hashes are display placeholders. The executable synthetic reference cases and runtime evidence requirements distinguish useful checks from deployment proof.

Customer support refund

Intent: support.refund · V1 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"], "subject": "u:user:771" } },
  "agent": { "agent_id": "agt_support", "workload_identity": "spiffe://contextos/agents/support", "role": "support_ops" },
  "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 },
  "trace": { "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7" }
}

2. Compile (abridged)

This excerpt shows the fields relevant to the workflow. A schema-valid CompiledContext also carries compiled_prompt, budget_report, and context_ledger; see API Contracts.

{
  "manifests": {
    "policy_manifest": [{ "bundle_id": "POLICY_RETURNS_V4", "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

ok — every tool exists in tool_manifest, every argument validates, native ActionRisk passes policy, the v1 approval_mode projection is conservative, and the required gate is declared. Evidence-dependent commit remains blocked until the checkpoint has all current verified evidence. Merely declaring the gate does not satisfy approval.

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...)
                      → current authorization/boundary/data checks + budget reservation
                      → tc_121 → verified refund and postcondition, evidence_ref=tool:adp_payments.issue_refund:tc_121

6. DecisionRecord (final)

{
  "record_id": "dr_2026_05_04_a17",
  "decision_key": "support.refund.execute",
  "decision_version": "1.0.0",
  "timestamp": "2026-05-04T09:31:42Z",
  "status": "DECIDED",
  "actor": { "type": "AGENT", "id": "agt_support" },
  "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...",
    "decided_at": "2026-05-04T09:31:30Z"
  }],
  "policy_decisions": [{ "policy_decision_id": "pol_9901", "rule_ids": ["R_HIGH_VALUE_REQUIRES_APPROVAL"], "verdict": "require_approval" }],
  "controls_active": { "approval_gates_active": ["GATE_FINANCE_APPROVAL"], "must_refuse": [], "must_escalate": [], "redaction_rules_active": [] },
  "budget_usage": { "tokens": 4720, "tool_calls": 4, "cost_usd_cents": 0.91, "wall_clock_ms": 1840 },
  "lineage": { "pack_version": "ctxpack.support@5.2.0", "decision_spec": "support.refund.execute@1.0.0" },
  "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; retain the paused v1 receipt and durable waiting/checkpoint state. A session ID only locates it. Resume needs current ownership/fencing, authorization, valid approval, boundary/external checks and remaining original budget.
Lost write acknowledgement: keep the stable operation and unknown effect; do not retry from a transport error or idempotency key alone. Verified provider-specific reconciliation determines the next permitted recovery action.

Content moderation review

Intent: content.review · V1 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": { "auth_type": "oauth2", "scopes": ["content.review"], "subject": "u:user:404" } },
  "agent": { "agent_id": "agt_moderation", "workload_identity": "spiffe://contextos/agents/moderation", "role": "content_ops" },
  "context_pack_refs": ["ctxpack.moderation@2.0.0"],
  "input": { "intent": "content.review", "message": "Review post pst_5512" },
  "mode": "batch",
  "runtime": { "max_tool_calls": 6, "max_cost_cents": 10 },
  "trace": { "trace_id": "9aa00000000000000000000000000001", "span_id": "10f067aa0ba902b7" }
}

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": "s2" }
  ]
}

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.

The 0.7 threshold is an illustrative pinned classifier policy, not authorization. Both branches need current authority and data-flow admission; queue insertion is a governed write. The local execute_when field is a deployment-plan extension, not a new base PlanStep field. Expression errors block that routing decision. Before s4, exact stored action approval and current dispatch checks are required; emit the final decision only after verifying the selected branch’s required effect.

4. DecisionRecord

{
  "record_id": "dr_qx88",
  "decision_key": "content.review.action",
  "decision_version": "1.0.0",
  "timestamp": "2026-05-04T10:00:00Z",
  "status": "DECIDED",
  "actor": { "type": "AGENT", "id": "agt_moderation" },
  "outputs": { "action": "publish_blocked", "reason_code": "policy_violation_severe" },
  "evidence_refs": ["tool:adp_content.classify:tc_421", "tool:adp_policy.eval:tc_422", "tool:adp_content.publish_block:tc_423"],
  "policy_decisions": [{ "policy_decision_id": "pol_content_01", "rule_ids": ["R_SEVERE_CONTENT_REVIEW"], "verdict": "require_approval" }],
  "approvals": [{ "gate_id": "GATE_PUBLISH_BLOCK", "approver": "user_mod_lead_12", "approval_mode_effective": "delegated", "evidence_snapshot_hash": "sha256:c4d3...", "decided_at": "2026-05-04T09:59:50Z" }],
  "controls_active": { "approval_gates_active": ["GATE_PUBLISH_BLOCK"], "must_refuse": [], "must_escalate": [], "redaction_rules_active": [] },
  "budget_usage": { "tokens": 2310, "tool_calls": 3, "cost_usd_cents": 0.48, "wall_clock_ms": 980 },
  "lineage": { "pack_version": "ctxpack.moderation@2.0.0", "decision_spec": "content.review.action@1.0.0" },
  "trace_id": "9aa00000000000000000000000000001"
}

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 · V1 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": { "auth_type": "oauth2", "scopes": ["bi.read"], "subject": "u:user:22" } },
  "agent": { "agent_id": "agt_analyst", "workload_identity": "spiffe://contextos/agents/analyst", "role": "data_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",
  "runtime": { "max_tool_calls": 4, "max_cost_cents": 5 },
  "trace": { "trace_id": "11bb0000000000000000000000000001", "span_id": "20f067aa0ba902b7" }
}

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",
  "decision_version": "1.0.0",
  "timestamp": "2026-05-04T10:15:00Z",
  "status": "DECIDED",
  "actor": { "type": "AGENT", "id": "agt_analyst" },
  "outputs": { "rows": [] },
  "evidence_refs": ["kg:query:tc_801", "bi:snapshot:tc_802"],
  "policy_decisions": [{ "policy_decision_id": "pol_lookup_01", "rule_ids": ["R_BI_READ_ALLOWED"], "verdict": "allow" }],
  "approvals": [],
  "controls_active": { "approval_gates_active": [], "must_refuse": [], "must_escalate": [], "redaction_rules_active": ["pii_email"] },
  "budget_usage": { "tokens": 960, "tool_calls": 2, "cost_usd_cents": 0.16, "wall_clock_ms": 410 },
  "lineage": { "pack_version": "ctxpack.bi_lookup@1.4.0", "decision_spec": "data.lookup.result@1.0.0" },
  "trace_id": "11bb0000000000000000000000000001"
}

Even for read_only, current reader authority, purpose, actual processor/recipient and source-label policy still apply. The gateway verifies approved masking before exposing customer data, rather than treating a compiled redaction-rule name as proof. Pack/snapshot pins, evidence refs and trace correlation support replay when the permitted artifacts remain available.

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)

Stage	Same shape?
`invokeAgent` envelope	same base schema; identity, tenant, `context_pack_refs`, input and runtime limits vary
`CompiledContext`	always — `manifests` + `runtime_controls` + `budget_report`
Plan	always typed; steps differ by intent
Approval gates	only when policy emits an approval obligation for the concrete action context
`DecisionRecord`	always — all base-schema required fields are present; domain fields follow the active DecisionSpec

The shared shapes support portability. Exact profile requirements, current semantic checks, verified effects and observed deployment evidence determine whether a particular workflow satisfies the contract.