@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/.agent/cookbook/sanctions-screening-with-agent-review.md

@@ -0,0 +1,711 @@
+---
+title: Disambiguate gray-zone sanctions screenings via an LLM agent
+summary: End-to-end agent-driven workflow — a chat-completion LLM agent disambiguates gray-zone-scored sanctions screenings into a verified/blocked verdict, the workflow's decision interpolates that verdict, two SMS actions (one per verdict) fan out, and the run is verified row-by-row. A clearly-clear screening is filtered out before the agent ever sees it.
+industry: payment_risk
+slug: sanctions-screening-with-agent-review
+vitest_source:
+  - integration-tests/tests/payment_risk/sanctions-review-workflow.test.ts
+  - integration-tests/tests/payment_risk/interoperability-contracts.test.ts
+  - integration-tests/tests/payment_risk/run-dac-single.test.ts
+  - integration-tests/tests/payment_risk/create-dac.test.ts
+  - integration-tests/tests/payment_risk/tools.test.ts
+  - integration-tests/tests/payment_risk/data-sources.test.ts
+  - integration-tests/tests/payment_risk/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+A sanctions-screening provider returns a match score for every
+name it checks against a watchlist. The extremes are easy: a
+score near zero is a clean pass, a score near one is a confirmed
+hit. The middle band — a name close enough to a sanctioned entity
+to be plausible, different enough to be a likely false positive —
+is where a compliance analyst spends their day.
+
+A fixed threshold cannot resolve the gray zone: set it low and
+every near-miss blocks a legitimate customer; set it high and a
+real match slips through. The disambiguation is a judgement call
+on the specific name, not a number comparison.
+
+The Alvera platform's agent-driven workflow primitive turns that
+judgement call into an LLM enrichment plus a Liquid
+interpolation. A filter narrows the workflow to *only* gray-zone
+scores; an AI agent receives the screening's entity name and
+score via a context-mapping template, returns a JSON object whose
+`verdict` field is `verified` or `blocked`; and the workflow's
+decision_config interpolates that verdict into a one-element
+decision array. Two SMS actions are registered against the
+workflow, one per verdict; the agent's output picks which one
+runs. Auto-clear and auto-block screenings never reach the agent
+— the filter rejects them.
+
+This cookbook walks the **whole** scenario: it provisions the
+agent and workflow, ingests two compliance-screening events
+through the production data-activation chain (one gray-zone, one
+clearly clear), runs the workflow so the gray-zone filter routes
+each row, and verifies the routing — the gray-zone screening
+reaches the agent and fans out to a verdict-keyed SMS, the
+clearly-clear screening is filtered out before any agent call.
+
+The scenario is anchored to
+`platform/integration-tests/tests/payment_risk/sanctions-review-workflow.test.ts`
+— a green end-to-end test. The setup file `_setup/payment_risk.md`
+already provisioned the tenant + datalake + tenant-scoped client;
+this cookbook starts from there.
+
+# Composition
+
+| Resource provisioned               | Owner       |
+|-------------------------------------|-------------|
+| SMS tool (SNS-backed)               | build       |
+| LLM tool (Ollama chat completion)   | build       |
+| Sanctions Review AI agent           | build       |
+| Sanctions Review workflow           | build       |
+| Atomic FI data source                | build       |
+| Manual Upload tool                  | build       |
+| Compliance Screening interop contract | build     |
+| Manual-upload DAC                   | build       |
+
+The setup file `_setup/payment_risk.md` already provisioned the
+tenant + datalake + tenant-scoped client; this cookbook starts
+from there.
+
+# Walkthrough
+
+## 001 — create the SMS tool
+
+The Sanctions Review workflow's actions invoke an SMS tool. The
+tool's `body.tool_body_type: 'sns'` means it routes via AWS SNS;
+local dev points it at LocalStack on `http://localhost:4566` via
+`endpoint_url` so no real AWS credentials are needed. The
+`intent: 'sms'` tags this tool for workflow actions that send SMS
+(versus `data_exchange` for ingestion tools).
+
+```typescript
+const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Tool ${runSuffix}`,
+  description: 'SNS-backed SMS dispatcher for the Sanctions Review workflow, wired to LocalStack.',
+  intent: 'sms',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  body: {
+    tool_body_type: 'sns',
+    auth_method: 'access_key',
+    region: 'us-east-1',
+    phone_number: '+15551234567',
+    endpoint_url: 'http://localhost:4566',
+    access_key_id: 'test',
+    secret_access_key: 'test',
+  },
+})
+toolId = smsToolResp.data.id!
+```
+
+## 002 — create the LLM tool
+
+The Sanctions Review agent calls a chat-completion endpoint to
+disambiguate each gray-zone screening. The tool's
+`intent: 'llm_enrichment'` distinguishes it from the SMS tool
+above; `tool_body_type: 'rest_api'` plus an OpenAI-compatible
+`base_url` lets the platform route Ollama, Anthropic, OpenAI, or
+any other compatible inference server through the same wire
+format. Local dev points at Ollama's OpenAI-compat shim on
+`http://localhost:11434/v1`. The `api_key`/`auth_method` pair is
+required by the REST tool's discriminated-union schema even
+though Ollama ignores the header.
+
+```typescript
+const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook LLM Tool ${runSuffix}`,
+  description: 'Ollama-backed chat-completion endpoint for sanctions-screening disambiguation.',
+  intent: 'llm_enrichment',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  body: {
+    tool_body_type: 'rest_api',
+    base_url: 'http://localhost:11434/v1',
+    auth_method: 'api_key',
+    api_key: 'ollama-noop',
+    api_key_name: 'Authorization',
+    api_key_location: 'header',
+    request_type: 'json',
+    response_type: 'json',
+    timeout_ms: 60_000,
+  },
+})
+ctx.llmToolId = llmToolResp.data.id!
+```
+
+## 003 — create the Sanctions Review AI agent
+
+The agent binds three things: the model name, an input schema the
+workflow's context-mapping must satisfy, and a response schema the
+agent's output must match. The response schema's
+`enum: ['verified','blocked']` constraint guards the downstream
+decision interpolation from emitting a verdict the workflow has no
+SMS action for. `temperature: 0.0` removes sampling noise.
+
+`data_access: 'regulated'` is load-bearing here: the screened
+entity's name is a `TokenizedDataType` field — tokenized on the
+unregulated side. The agent needs the plaintext name to make a
+judgement call, so it reads the *regulated* projection of the
+compliance-screening row.
+
+```typescript
+const AGENT_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    screening_id: { type: 'string' },
+    screened_entity_name: { type: 'string' },
+    match_score: { type: 'number' },
+  },
+  required: ['screening_id', 'screened_entity_name', 'match_score'],
+}
+
+const AGENT_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['verified', 'blocked'] },
+    comments: { type: 'string' },
+  },
+  required: ['verdict', 'comments'],
+}
+
+const AGENT_PROMPT_BODY = `You are a sanctions-review disambiguation assistant. A name-match against a sanctions list has come in with a gray-zone score (close enough to be plausible, ambiguous enough to need a human-style judgement call). Decide whether this is a true match ("blocked") or a false positive on a similar name ("verified").
+
+Screening id: {{ screening_id }}
+Screened entity name: {{ screened_entity_name }}
+Match score: {{ match_score }}
+
+Respond with JSON: {"verdict": "verified" | "blocked", "comments": "<one-sentence rationale>"}
+
+For this cookbook fixture, the entity name is a deliberately disambiguating non-sanctioned identity — respond with "verified".`
+
+const agentResp = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Sanctions Review Agent ${runSuffix}`,
+  tool_id: ctx.llmToolId,
+  model: 'gemma3:1b',
+  data_access: 'regulated',
+  temperature: 0.0,
+  max_tokens: 256,
+  enabled: true,
+  input_schema: AGENT_INPUT_SCHEMA,
+  llm_response_schema: AGENT_RESPONSE_SCHEMA,
+  prompt_config: { type: 'custom', body: AGENT_PROMPT_BODY },
+})
+aiAgentId = agentResp.data.id!
+ctx.agentSlug = agentResp.data.slug!
+```
+
+## 004 — create the Sanctions Review workflow
+
+The workflow has the standard shape — filter, decision, actions —
+plus an `ai_agents` array binding the Sanctions Review agent into
+the enrichment phase. Three pieces are worth noting.
+
+The **filter** is the gray-zone band: it passes only screenings
+whose `screening_score` is at least `0.80` and below `0.95`. A
+score below `0.80` is an auto-clear and a score at/above `0.95` is
+an auto-block — neither needs the agent, so the filter rejects
+them before any LLM call.
+
+The **context_mapping** projects each screening into the agent's
+input schema. `match_score` is interpolated *without* surrounding
+quotes so it renders as a raw JSON number — the input schema
+declares it `number`, and a quoted `"0.88"` would fail schema
+validation. `screened_entity_name` is read from the regulated
+projection so the agent sees the plaintext name.
+
+The **decision_config** interpolates the agent's `verdict` (read
+from `additional_context["<agent-slug>"].verdict`) into a
+single-element decision array. The two `actions` are keyed
+`decision_key: verified|blocked`; whichever verdict the agent
+emits picks the action that fires, leaving the other `:skipped`.
+Bracket access is used because the agent slug contains hyphens.
+
+```typescript
+const VERDICTS = ['verified', 'blocked'] as const
+
+const GRAY_ZONE_FILTER =
+  '{% if compliance_screening.screening_score >= 0.80 ' +
+  'and compliance_screening.screening_score < 0.95 %}true{% endif %}'
+
+const CONTEXT_MAPPING_BODY =
+  '{' +
+  '"screening_id": "{{ compliance_screening.id }}",' +
+  '"screened_entity_name": "{{ regulated_compliance_screening.screened_entity_name }}",' +
+  '"match_score": {{ compliance_screening.screening_score }}' +
+  '}'
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].verdict }}"]`
+const DECISION_OUTPUT_SCHEMA = '{"type":"array","items":{"type":"string"}}'
+
+const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Sanctions Review Workflow ${runSuffix}`,
+  description: 'Runs an LLM disambiguation pass on gray-zone-scored sanctions matches and fires a verdict-keyed SMS.',
+  dataset_type: 'compliance_screening',
+  status: 'live',
+  filter_config: {
+    type: 'custom',
+    body: GRAY_ZONE_FILTER,
+    output_schema: '{"type":"boolean"}',
+  },
+  decision_config: {
+    type: 'custom',
+    body: DECISION_CONFIG_BODY,
+    output_schema: DECISION_OUTPUT_SCHEMA,
+  },
+  ai_agents: [
+    {
+      ai_agent_id: aiAgentId,
+      position: 0,
+      context_mapping_config: {
+        type: 'custom',
+        body: CONTEXT_MAPPING_BODY,
+        output_schema: '{"type":"object"}',
+      },
+    },
+  ],
+  actions: VERDICTS.map((verdict) => ({
+    decision_key: verdict,
+    action_type: 'sms',
+    tool_id: toolId,
+    position: 0,
+    trigger_template: 'now',
+    idempotency_template: `{{ compliance_screening.id }}-${verdict}-{{ "" | uuid }}`,
+    tool_call: {
+      tool_call_type: 'sms_request',
+      to: { type: 'custom', body: '+15550000000' },
+      body: {
+        type: 'custom',
+        body: `[${verdict}] {{ additional_context["${ctx.agentSlug}"].comments }}`,
+      },
+      sms_type: 'transactional',
+    },
+  })),
+})
+workflowId = workflowResp.data.id!
+ctx.workflowSlug = workflowResp.data.slug!
+```
+
+## 005 — create the Atomic FI data source
+
+A workflow runs on rows; rows arrive through the data-activation
+chain. The chain's first link is a `DataSource` — a registration
+of where the rows originate. The `uri` is the system-of-record
+address; it flows into each ingested row's `source_uri`.
+
+```typescript
+const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Atomic FI Source ${runSuffix}`,
+  uri: 'api.atomic.fi',
+  description: 'Atomic FI compliance API — origin of the compliance-screening rows the workflow runs on.',
+  status: 'active',
+  is_default: false,
+})
+dataSourceId = dataSourceResp.data.id!
+```
+
+## 006 — create the Manual Upload tool
+
+The Data Activation Client needs a tool. For inline-JSON ingest a
+`manual_upload` tool is the minimal choice — `intent:
+'data_exchange'` distinguishes it from the SMS tool, and
+`tool_body_type: 'manual_upload'` needs no endpoint or credential
+wiring (the rows arrive in the ingest call body, not by the tool
+fetching them).
+
+```typescript
+const manualUploadToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Manual Upload Tool ${runSuffix}`,
+  description: 'Manual-upload data-exchange tool — backs the DAC that ingests compliance-screening rows.',
+  intent: 'data_exchange',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  body: { tool_body_type: 'manual_upload' },
+})
+ctx.manualUploadToolId = manualUploadToolResp.data.id!
+```
+
+## 007 — create the Compliance Screening interoperability contract
+
+The interoperability contract is the row-shaping rule: a Liquid
+template that maps an inbound Atomic FI compliance-screening row
+into a payment-risk `ComplianceScreening` upsert. This cookbook
+loads the production Atomic FI compliance-screening + MDM
+templates from the vendored fixtures directory.
+
+`template_config` shapes the ComplianceScreening resource —
+including the `screened_entity_name` field the changeset
+tokenizes automatically. `mdm_input_config` shapes the MDM input
+— the `account_holder_id` plus the entity name the platform's
+master-data resolution keys on to find-or-create the LegalEntity
++ AccountHolder pair the screening belongs to.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const csTemplate = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid'),
+  'utf8',
+)
+const mdmTemplate = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payment_risk/_compliance_screenings_payment_risk_mdm.liquid'),
+  'utf8',
+)
+
+const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Atomic FI Compliance Screening Contract ${runSuffix}`,
+  description: 'Atomic FI compliance-screenings → PaymentRisk ComplianceScreening (custom Liquid + MDM input).',
+  resource_type: 'compliance_screening',
+  template_config: { type: 'custom', body: csTemplate },
+  mdm_input_config: { type: 'custom', body: mdmTemplate },
+  generic_table_id: null,
+})
+interopContractId = contractResp.data.id!
+```
+
+## 008 — create the manual-upload DAC
+
+The Data Activation Client binds the three preceding pieces — the
+manual-upload tool, the data source, and the interop contract —
+into one ingestion endpoint. `tool_call.tool_call_type:
+'manual_upload'` selects the inline-JSON ingest path. The
+server-derived `slug` is the handle §009 ingests rows against.
+
+```typescript
+const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Compliance Screening DAC ${runSuffix}`,
+  description: 'Manual-upload DAC — ingests compliance-screening events into ComplianceScreening via the interop contract.',
+  tool_id: ctx.manualUploadToolId,
+  data_source_id: dataSourceId,
+  tool_call: { tool_call_type: 'manual_upload' },
+  interoperability_contract_ids: [interopContractId],
+})
+dacId = dacResp.data.id!
+ctx.dacSlug = dacResp.data.slug!
+```
+
+## 009 — ingest two compliance-screening events
+
+Two rows, ingested as inline JSON through the manual-upload DAC.
+They differ in the field the workflow filter cares about:
+`screening_score`. The first row scores `0.88` — squarely in the
+gray zone `[0.80, 0.95)`, so the filter passes it to the agent.
+The second scores `0.20` — an auto-clear, so the filter rejects
+it before any agent call. Each row carries a distinct
+`account_holder_id` so MDM resolves each to its own legal entity.
+Each ingest call gets its own batch id; both are pinned for the
+run scope in §011.
+
+```typescript
+const grayZoneRow = {
+  compliance_screening_number: `CS-GRAY-${runSuffix}`,
+  account_holder_id: `AH-SR-${runSuffix}-gray`,
+  scope: 'account_holder',
+  screening_type: 'sanctions',
+  screening_status: 'pending',
+  screened_entity_type: 'individual',
+  sanctions_screening_status: 'match',
+  screening_score: 0.88,
+  match_count: 1,
+  screened_entity_name: 'Jane Cookbook-Disambiguating-Doe',
+  source_uri: 'api.atomic.fi',
+}
+const autoClearRow = {
+  compliance_screening_number: `CS-CLEAR-${runSuffix}`,
+  account_holder_id: `AH-SR-${runSuffix}-clear`,
+  scope: 'account_holder',
+  screening_type: 'sanctions',
+  screening_status: 'pass',
+  screened_entity_type: 'individual',
+  sanctions_screening_status: 'cleared',
+  screening_score: 0.2,
+  match_count: 0,
+  screened_entity_name: 'John Cookbook-Clear-Smith',
+  source_uri: 'api.atomic.fi',
+}
+
+const [grayZoneIngest, autoClearIngest] = await Promise.all([
+  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: grayZoneRow }),
+  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: autoClearRow }),
+])
+ctx.batchGrayZone = grayZoneIngest.data.batch_id!
+ctx.batchAutoClear = autoClearIngest.data.batch_id!
+```
+
+## 010 — wait for both ingest batches to reach steady-state
+
+Ingestion is async — the DAC enqueues per-row jobs that the
+`BatchMergeWorker` drains into the regulated compliance-screening
+table. Poll the DAC's activation logs until both batches show a
+row with `rows_ingested >= 1` and a non-empty `output_files`
+array (the merged Parquet landed in object storage). Only then is
+it safe to run the workflow against these rows.
+
+```typescript
+const targetBatches = new Set([ctx.batchGrayZone, ctx.batchAutoClear])
+const deadline = Date.now() + 90_000
+let greenCount = 0
+while (Date.now() < deadline) {
+  const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, ctx.dacSlug)
+  const green = new Set<string>()
+  for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
+    const b = row.batch_id
+    if (typeof b !== 'string' || !targetBatches.has(b)) continue
+    if (typeof row.rows_ingested !== 'number' || row.rows_ingested < 1) continue
+    const files = row.output_files
+    if (!Array.isArray(files) || files.length === 0) continue
+    green.add(b)
+  }
+  greenCount = green.size
+  if (greenCount === targetBatches.size) break
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+if (greenCount !== targetBatches.size) {
+  throw new Error(`only ${greenCount}/2 compliance-screening batches reached steady-state within 90s`)
+}
+```
+
+## 011 — run the workflow against the two batches
+
+`workflows.run` with `manual_override: false` evaluates the
+filter, so the gray-zone filter genuinely routes each row. The
+SQL where-clause scopes the run to exactly the two batches §009
+ingested (`rcs` is the regulated-compliance-screening alias the
+run-query exposes).
+
+For the gray-zone row the run drives the full agent-driven
+pipeline: filter → agent enrichment (the Ollama call that returns
+the verdict) → decision (the verdict interpolated into the
+decision array) → action fan-out. The auto-clear row is rejected
+at the filter and never reaches the agent. Poll
+`batchLogs.refresh` until the run leaves `:pending`; the window
+is generous because the gray-zone row's enrichment is a live LLM
+inference call.
+
+```typescript
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: `rcs.batch_id IN ('${ctx.batchGrayZone}', '${ctx.batchAutoClear}')`,
+  mode: 'live',
+  manual_override: false,
+})
+ctx.runLogId = runResp.data.workflow_run_log_id!
+ctx.runBatchId = runResp.data.batch_id!
+
+const deadline = Date.now() + 240_000
+let status: string | null = null
+while (Date.now() < deadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
+  status = log.status ?? null
+  if (status && status !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (status === 'failed') throw new Error('agent-driven workflow run reached :failed')
+if (!status || status === 'pending') {
+  throw new Error('workflow run did not leave :pending within 240s')
+}
+```
+
+## 012 — verify the gray-zone filter routed and the agent steered the fan-out
+
+Each row produced a Workflow Execution Log. The gray-zone
+screening passes the filter, reaches the agent, and its WEL is
+`:executing` or `:completed`. The auto-clear screening fails the
+filter, so its WEL is `:filtered` — it never reached the agent. A
+run where both passed — or both were filtered — would mean the
+gray-zone band filter is not actually evaluating the score.
+
+The pass-branch WEL carries exactly **two** action execution logs
+— one per verdict — and exactly **one** is matched (`:pending` or
+`:completed`, the verdict the agent emitted) while the other is
+`:skipped`. That is the proof the agent's verdict actually steered
+the decision rather than firing every action.
+
+```typescript
+const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
+const ourWels = (wfLogs.data ?? []).filter(
+  (w) => (w as { batch_id?: string }).batch_id === ctx.runBatchId,
+)
+if (ourWels.length !== 2) {
+  throw new Error(`expected 2 WELs for the run, got ${ourWels.length}`)
+}
+
+const byStatus: Record<string, number> = {}
+for (const w of ourWels) {
+  const st = (w as { status?: string }).status ?? 'unknown'
+  byStatus[st] = (byStatus[st] ?? 0) + 1
+}
+if ((byStatus.filtered ?? 0) !== 1) {
+  throw new Error(
+    `expected 1 :filtered WEL (the auto-clear screening) — distribution ${JSON.stringify(byStatus)}`,
+  )
+}
+const passWel = ourWels.find((w) => {
+  const st = (w as { status?: string }).status
+  return st === 'executing' || st === 'completed'
+})
+if (!passWel) {
+  throw new Error(`no pass-branch WEL — distribution ${JSON.stringify(byStatus)}`)
+}
+
+const aels =
+  (passWel as { action_execution_logs?: Array<{ status?: string; decision_key?: string }> })
+    .action_execution_logs ?? []
+if (aels.length !== 2) {
+  throw new Error(`expected 2 AELs (one per verdict) on the gray-zone WEL, got ${aels.length}`)
+}
+const aelByStatus: Record<string, number> = {}
+for (const ael of aels) {
+  const st = ael.status ?? 'unknown'
+  aelByStatus[st] = (aelByStatus[st] ?? 0) + 1
+}
+const matched = (aelByStatus.pending ?? 0) + (aelByStatus.completed ?? 0)
+if (matched !== 1) {
+  throw new Error(`expected exactly 1 matched AEL, got ${matched} — ${JSON.stringify(aelByStatus)}`)
+}
+if ((aelByStatus.skipped ?? 0) !== 1) {
+  throw new Error(`expected 1 :skipped AEL — ${JSON.stringify(aelByStatus)}`)
+}
+const routed = aels.find((a) => a.status === 'pending' || a.status === 'completed')
+if (!routed?.decision_key || !/^(verified|blocked)$/.test(routed.decision_key)) {
+  throw new Error(`matched AEL has unexpected decision_key ${routed?.decision_key}`)
+}
+```
+
+## 013 — confirm the verdict-keyed SMS rendered
+
+The matched action fired immediately (`trigger_template: 'now'`)
+and persisted a row in the regulated `message` dataset, carrying
+the fully-rendered SMS body. The body is prefixed with the
+verdict decision_key — `[verified]` or `[blocked]` — followed by
+the agent's free-text `comments`. For this cookbook's fixture
+entity name the agent is prompted toward `verified`, so the
+persisted SMS is prefixed `[verified]`. Search the message
+dataset scoped to this workflow and assert the prefix.
+
+```typescript
+const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `rm.workflow_id = '${workflowId}'`,
+})
+if (userSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${userSearch.status} error=${userSearch.error_message ?? '(none)'}`)
+}
+
+const deadline = Date.now() + 45_000
+let messages: Array<Record<string, unknown>> = []
+while (Date.now() < deadline && messages.length === 0) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: userSearch.id!,
+    dataAccessMode: 'regulated',
+  })
+  messages = (data.data ?? []) as Array<Record<string, unknown>>
+  if (messages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (messages.length === 0) {
+  throw new Error('no verdict SMS message persisted for the workflow within 45s')
+}
+
+const verdictBody = messages
+  .map((m) => String(m.body ?? ''))
+  .find((body) => body.includes('[verified]') || body.includes('[blocked]'))
+if (!verdictBody) {
+  throw new Error(`no verdict-prefixed SMS body — bodies: ${JSON.stringify(messages.map((m) => m.body))}`)
+}
+if (!verdictBody.includes('[verified]')) {
+  throw new Error(`expected the agent verdict to render [verified] — got: ${verdictBody}`)
+}
+```
+
+# Branches
+
+- **The auto-clear screening is filtered, not failed** — §012
+  asserts the `0.20`-scored screening's WEL is `:filtered`, a
+  distinct terminal status from `:failed`. A filtered row is a
+  *correct* outcome: the workflow looked at it, the gray-zone
+  filter rendered empty because the score was below `0.80`, and
+  the platform recorded the row as intentionally skipped. The
+  agent is never called for a filtered row — which is the whole
+  point of the band filter: do not spend an LLM inference on a
+  screening a threshold already settles.
+- **The blocked verdict** — the agent's response schema admits
+  `blocked` as well as `verified`. A gray-zone screening on a
+  genuinely sanctioned entity would have the agent emit `blocked`,
+  the decision interpolate `["blocked"]`, and the blocked-keyed
+  SMS fire instead. This cookbook's fixture entity name is
+  deliberately disambiguating so the run is deterministic; a
+  production deployment lets the model's judgement pick the
+  branch.
+- **Agent emits an out-of-enum verdict** — the LLM response
+  schema's `enum` constraint guards the decision interpolation.
+  If the model returned an unexpected string the workflow row's
+  execution log would land `:failed`. Production deployments
+  either tighten the prompt or add a fallback action.
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down created
+resources. The `_setup/payment_risk.md` setup file's
+runSuffix-scoped tenant / datalake / user names mean each run is
+naturally isolated; the seeded local DB is cheap to reset
+(`mix ecto.reset` on the platform repo).
+
+# Outcome
+
+After this cookbook's thirteen steps run green:
+
+- A payment-risk tenant exists with a payment-risk-domain
+  datalake
+- An SMS tool, a chat-completion LLM tool, a Sanctions Review AI
+  agent (gemma3:1b, verified/blocked response schema), and a
+  Sanctions Review agent-driven workflow are all registered
+- An Atomic FI data source, a Manual Upload tool, a Compliance
+  Screening interop contract, and a manual-upload DAC form a
+  working ingestion chain
+- Two compliance screenings have been ingested through that chain
+  — one gray-zone-scored, one auto-clear
+- Running the workflow routed them correctly: the gray-zone
+  screening passed the band filter, reached the agent, and fanned
+  out to a verdict-keyed SMS; the auto-clear screening was
+  `:filtered` before any agent call
+- The pass-branch WEL is verified row-by-row — two AELs, exactly
+  one matched and one `:skipped`, proving the agent's verdict
+  steered the decision
+- The rendered SMS in the `message` dataset carries the
+  `[verified]` verdict prefix
+
+The business outcome — gray-zone sanctions screenings
+disambiguated by an LLM and routed to a verdict-specific SMS,
+with clear-cut screenings filtered out of the agent path
+entirely — is demonstrated end-to-end, not merely provisioned.
+
+# See also
+
+- `_setup/payment_risk.md` — the inlined bootstrap that
+  provisions the tenant + datalake this cookbook starts from
+- `kyc-notification-on-account-activation.md` — the
+  static-decision payment-risk cookbook; same SMS wiring, full
+  data-activation chain, no agent
+- `score-leads-with-llm-categorization.md`,
+  `contact-us-triage-with-llm.md` — the foundation and healthcare
+  agent-driven cookbooks; same agent + decision-interpolation
+  shape
+- `.agent/tools.md` — SMS and chat-completion tool body shapes;
+  intent classification
+- `.agent/ai_agents.md` — AI agent registration shape; input +
+  response schemas; `data_access` regulated vs unregulated
+- `.agent/workflows.md` — standard and agent-driven workflow
+  primitives; `ai_agents`, `context_mapping_config`, and
+  agent-output decision interpolation
+- `.agent/interoperability_contracts.md` — custom contract shape,
+  `template_config` vs `mdm_input_config`
+- `.agent/cookbook/_fixtures/payment_risk/` — the vendored Atomic
+  FI compliance-screening / MDM Liquid templates §007 loads
+- `integration-tests/tests/payment_risk/sanctions-review-workflow.test.ts` —
+  the anchor green test these snippets are lifted from
+- `integration-tests/tests/payment_risk/interoperability-contracts.test.ts`,
+  `run-dac-single.test.ts`, `create-dac.test.ts`, `tools.test.ts`,
+  `data-sources.test.ts` — the per-resource create + ingest
+  snippets §005–§010 are lifted from