@alvera-ai/platform-sdk 0.10.0-rc.8 → 0.11.0

package/.agent/cookbook/system-templates.md

@@ -0,0 +1,129 @@
+---
+title: "Capability: discover the platform's built-in row-mapping templates"
+summary: A capability walk for system-template discovery. List the Liquid templates the platform ships for your datalake's data domain (`api.templates.systemTemplates`), read the human-readable catalog (`api.templates.metadata`), and pull one template's detail (`api.templates.metadataDetails`) — so you can start an interoperability contract from a platform template instead of hand-writing Liquid. Read-only; creates nothing.
+industry: accounts_receivable
+slug: system-templates
+vitest_source:
+  - integration-tests/tests/accounts_receivable/system-templates.test.ts
+  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+status: green
+---
+
+# Capability
+
+**What you get:** the list of row-mapping Liquid templates the platform already
+ships for your datalake's data domain, so an interoperability contract can start
+from a vetted template instead of hand-written Liquid.
+
+`api.templates.*` is read-only discovery. Three calls:
+
+- `systemTemplates(tenantSlug, datalakeSlug)` — the machine-readable list:
+  `{ data: [{ path, content, output_schema }] }`. The list is **filtered to your
+  datalake's data domain** plus globals — a payment-risk or healthcare template
+  never appears in an accounts-receivable datalake.
+- `metadata(tenantSlug, datalakeSlug)` — the same catalog as a markdown summary.
+- `metadataDetails(tenantSlug, datalakeSlug, basename, intent)` — one template's
+  detail by basename + intent.
+
+This is **global** to every data domain — only the anchor template paths below
+differ by domain. See `templates.md` for the reference, and
+`interoperability_contracts.md` for how a template becomes a contract.
+
+# Walkthrough
+
+The `_setup/accounts_receivable.md` bootstrap already provisioned the tenant +
+datalake and left `api`, `tenantSlug`, and `datalakeSlug` populated. This walk
+starts from there.
+
+## 001 — list the system templates in scope for this datalake
+
+`systemTemplates` returns every platform-shipped Liquid template visible to this
+datalake: the templates for its data domain (here, `accounts_receivable`) plus
+domain-agnostic globals (e.g. the SNS delivery-status poller). Each entry has a
+`path`, the Liquid `content`, and an `output_schema` (`null` when the template
+has no companion schema). The list is domain-scoped — templates for other data
+domains (`healthcare`, `payment_risk`, `foundation`, …) are filtered out, so you
+only see what is usable here.
+
+```typescript
+const { data: templates } = await api.templates.systemTemplates(tenantSlug, datalakeSlug)
+
+const paths = (templates.data ?? []).map((t) => t.path)
+if (paths.length === 0) {
+  throw new Error('expected the platform to ship at least one system template')
+}
+
+// The accounts-receivable anchor template is present...
+const arAnchor = 'data_activation/interoperability/accounts_receivable/stripe/customers_accounts_receivable_customer'
+if (!paths.some((p) => p.includes(arAnchor))) {
+  throw new Error(`expected the AR customer template (${arAnchor}) in the list`)
+}
+
+// ...and templates for other data domains are filtered out of an AR datalake.
+const otherDomains = ['healthcare', 'payment_risk', 'foundation', 'core_banking', 'service_commerce', 'trading']
+const leaked = paths.filter((p) => otherDomains.some((d) => p.split('/').includes(d)))
+if (leaked.length > 0) {
+  throw new Error(`cross-domain templates leaked into an AR datalake: ${leaked.join(', ')}`)
+}
+```
+
+## 002 — read the catalog as markdown
+
+`metadata` returns the same catalog as a markdown document — the form an agent
+reads to decide which template to start from. It names the in-scope templates,
+including the AR customer template by basename.
+
+```typescript
+const { data: catalog } = await api.templates.metadata(tenantSlug, datalakeSlug)
+if (typeof catalog !== 'string' || catalog.length === 0) {
+  throw new Error('expected a non-empty markdown template catalog')
+}
+if (!catalog.includes('customers_accounts_receivable_customer')) {
+  throw new Error('expected the AR customer template named in the catalog markdown')
+}
+```
+
+## 003 — read one template's detail by basename + intent
+
+`metadataDetails` pulls a single template's detail. Address it by its
+**basename** (the template name without the path) and its **intent** (the path
+prefix joined with underscores — here `data_activation_interoperability`). The
+result is a markdown body you can show an operator or feed an agent before it
+copies the template into a contract's `template_config`.
+
+```typescript
+const { data: detail } = await api.templates.metadataDetails(
+  tenantSlug,
+  datalakeSlug,
+  'customers_accounts_receivable_customer',
+  'data_activation_interoperability',
+)
+if (typeof detail !== 'string' || detail.length === 0) {
+  throw new Error('expected a non-empty markdown detail for the AR customer template')
+}
+```
+
+# Gotchas
+
+- **The list is domain-scoped, not global.** `systemTemplates` only returns
+  templates for this datalake's data domain plus globals. Calling it on a
+  healthcare datalake returns the healthcare templates, never the AR ones —
+  there is no "all templates" view.
+- **`output_schema` is often `null`.** A template carries a non-null
+  `output_schema` only when it ships a companion schema; most interop templates
+  return `null`. Don't treat `null` as an error.
+- **`metadataDetails` keys on basename + intent, not the full path.** Pass the
+  bare template name and the underscore-joined path prefix (the "intent"), not
+  the slash path from `systemTemplates`.
+- **Discovery only.** None of these calls create or mutate anything — they read
+  what the platform ships. To turn a template into a live mapping, copy its
+  `content` into an `interoperabilityContracts.create(...)` `template_config`
+  (see `interoperability_contracts.md`).
+
+# See also
+
+- `templates.md` — the `api.templates.*` reference (wire shapes, intents)
+- `interoperability_contracts.md` — how a template becomes a live row mapping
+- `_setup/accounts_receivable.md` — the bootstrap this walk starts from
+- `integration-tests/tests/accounts_receivable/system-templates.test.ts` — the
+  green test these calls are lifted from

package/.agent/cookbook/triage-prospects-by-priority.md

@@ -0,0 +1,533 @@
+---
+title: Triage inbound AR prospects into priority bands via an LLM agent and route each to a tailored SMS
+summary: End-to-end agent-driven workflow over the accounts-receivable customer dataset — a chat-completion LLM agent classifies each customer into a priority band (high/medium/low) by account type, the workflow's decision interpolates the agent's band, three SMS actions (one per band) fan out, and the run is verified row-by-row so every Workflow Execution Log carries exactly one matched action and two skipped.
+industry: accounts_receivable
+slug: triage-prospects-by-priority
+vitest_source:
+  - integration-tests/tests/accounts_receivable/agent-lead-triage.test.ts
+  - integration-tests/tests/accounts_receivable/interoperability-contracts.test.ts
+  - integration-tests/tests/accounts_receivable/run-dac-single.test.ts
+  - integration-tests/tests/accounts_receivable/create-dac.test.ts
+  - integration-tests/tests/accounts_receivable/tools.test.ts
+  - integration-tests/tests/accounts_receivable/data-sources.test.ts
+  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+The `dunning-sms-for-delinquent` cookbook fired the **same** action for every
+customer that passed its filter. Many AR engagements need the opposite: which
+outreach fires should depend on **what kind of account** the customer is — a
+high-value enterprise account gets a white-glove message, a self-serve
+individual gets a standard nudge, a slow-paying government account gets a
+low-urgency note. That banding is a judgement call over the account, not a
+fixed rule.
+
+The Alvera platform's agent-driven workflow turns the decision step into an LLM
+classification plus a Liquid interpolation. An AI agent reads each customer's
+type, returns a JSON object whose `priority_band` is one of three enum values,
+and the workflow's `decision_config` interpolates that band into a one-element
+decision array (`["{{ additional_context["agent-slug"].priority_band }}"]`).
+Three SMS actions are registered, one per band; the agent's output picks which
+one runs.
+
+This cookbook walks the **whole** scenario: it provisions the SMS tool, the LLM
+tool, the triage agent, the AR customer ingestion chain, and the agent-driven
+workflow; ingests two Stripe customers (an enterprise and an individual);
+runs the workflow so the agent bands each one; and verifies the routing
+row-by-row — every Workflow Execution Log carries exactly one matched action
+and two `:skipped`.
+
+The scenario is anchored to
+`platform/integration-tests/tests/accounts_receivable/agent-lead-triage.test.ts`.
+The setup file `_setup/accounts_receivable.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 adapter)  | build |
+| Priority Triage AI agent                   | build |
+| Stripe data source                         | build |
+| Manual Upload tool                         | build |
+| Stripe Customer interop contract           | build |
+| Manual-upload DAC                          | build |
+| Priority Triage workflow                   | build |
+
+# Walkthrough
+
+## 001 — create the SMS tool
+
+A single SMS tool dispatches every band's message; the per-band body lives on
+each workflow action. SNS-backed, pointed at LocalStack locally; `intent: 'sms'`
+tags it for workflow actions.
+
+```typescript
+const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Tool ${runSuffix}`,
+  description: 'SNS-backed SMS dispatcher for the priority-triage 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 triage agent calls a chat-completion endpoint. This tool is a **provider
+adapter**: `base_body` authors Ollama's native `/api/chat` request with
+`think: false` and a `format` schema so the model returns clean,
+schema-constrained JSON, and `response_extractor` maps the response back to the
+canonical `{ output_json, … }`. The extractor's `output_schema` is required for
+an `llm_enrichment` tool.
+
+```typescript
+const ENRICHMENT_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    output_json: {},
+    input_tokens: { type: ['integer', 'null'] },
+    output_tokens: { type: ['integer', 'null'] },
+    total_tokens: { type: ['integer', 'null'] },
+    explanation: { type: ['string', 'null'] },
+  },
+  required: ['output_json'],
+}
+
+const OLLAMA_BASE_BODY =
+  '{"model": "{{ model }}", "messages": [{"role": "user", "content": "{{ rendered_prompt | json_escape }}", "images": [{% for img in images %}{% unless forloop.first %}, {% endunless %}"{{ img.data }}"{% endfor %}]}], "stream": false, "think": false, "options": {"temperature": 0, "num_ctx": 40960}, "format": {{ schema | to_json }}}'
+
+const OLLAMA_EXTRACTOR =
+  '{"output_json": "{{ msg.message.content | json_escape }}", "explanation": "{{ msg.message.thinking | json_escape }}", "input_tokens": {{ msg.prompt_eval_count | default: 0 }}, "output_tokens": {{ msg.eval_count | default: 0 }}, "total_tokens": {{ msg.prompt_eval_count | default: 0 | plus: msg.eval_count }}}'
+
+const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook LLM Tool ${runSuffix}`,
+  description: 'Ollama-backed chat-completion adapter for AR priority triage.',
+  intent: 'llm_enrichment',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
+  body: {
+    tool_body_type: 'rest_api',
+    base_url: 'http://localhost:11434',
+    base_path: { type: 'custom', body: '/api/chat' },
+    auth_method: 'api_key',
+    api_key: 'stub-key',
+    api_key_name: 'Authorization',
+    api_key_location: 'header',
+    request_type: 'json',
+    response_type: 'json',
+    timeout_ms: 60_000,
+    base_body: { type: 'custom', body: OLLAMA_BASE_BODY },
+  },
+})
+ctx.llmToolId = llmToolResp.data.id!
+```
+
+## 003 — create the Priority Triage agent
+
+The agent binds the model, an `input_schema` the workflow's context-mapping must
+satisfy, and an `llm_response_schema` whose `enum: ['priority_high',
+'priority_medium', 'priority_low']` guards the decision interpolation from
+emitting a band the workflow has no action for. `temperature: 0.0` makes
+identical inputs classify identically. `data_access: 'unregulated'` keeps the
+agent on the tokenized projection.
+
+```typescript
+const TRIAGE_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    customer_number: { type: 'string' },
+    customer_type: { type: 'string' },
+  },
+  required: ['customer_number', 'customer_type'],
+}
+
+const TRIAGE_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    priority_band: { type: 'string', enum: ['priority_high', 'priority_medium', 'priority_low'] },
+  },
+  required: ['priority_band'],
+}
+
+const TRIAGE_PROMPT_BODY = `You are an AR customer-priority triage assistant. Classify the customer's dunning priority into EXACTLY ONE band by account type:
+
+- "priority_high"   — enterprise (large account, high balance, white-glove outreach)
+- "priority_medium" — individual (standard self-serve account)
+- "priority_low"    — government (long payment cycles, low urgency)
+
+Customer number: {{ customer_number }}
+Customer type: {{ customer_type }}
+
+Respond with JSON: {"priority_band": "<one of priority_high|priority_medium|priority_low>"}`
+
+const agentResp = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Priority Triage Agent ${runSuffix}`,
+  tool_id: ctx.llmToolId,
+  model: 'qwen3-vl:8b-instruct',
+  data_access: 'unregulated',
+  temperature: 0.0,
+  max_tokens: 1024,
+  enabled: true,
+  input_schema: TRIAGE_INPUT_SCHEMA,
+  llm_response_schema: TRIAGE_RESPONSE_SCHEMA,
+  prompt_config: { type: 'custom', body: TRIAGE_PROMPT_BODY },
+})
+aiAgentId = agentResp.data.id!
+ctx.agentSlug = agentResp.data.slug!
+```
+
+## 004 — create the Stripe data source
+
+```typescript
+const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Stripe Source ${runSuffix}`,
+  uri: 'stripe.example.com',
+  description: 'Stripe billing system — origin of the customer rows the triage workflow runs on.',
+  status: 'active',
+  is_default: false,
+})
+dataSourceId = dataSourceResp.data.id!
+```
+
+## 005 — create the Manual Upload tool
+
+```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 Stripe customer 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!
+```
+
+## 006 — create the Stripe Customer interoperability contract
+
+The contract maps each inbound Stripe customer row into a `Customer` upsert.
+It loads the production Stripe customer + MDM templates from the vendored
+fixtures. `customer_type` flows through to `mdm_output.customer.customer_type`,
+which §008's context-mapping feeds the agent.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const customerTemplate = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'accounts_receivable/_customers_accounts_receivable_customer.liquid'),
+  'utf8',
+)
+const mdmTemplate = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'accounts_receivable/_customers_accounts_receivable_mdm.liquid'),
+  'utf8',
+)
+
+const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Stripe Customer Contract ${runSuffix}`,
+  description: 'Stripe customers → AccountsReceivable Customer (custom Liquid + MDM input).',
+  resource_type: 'customer',
+  template_config: { type: 'custom', body: customerTemplate },
+  mdm_input_config: { type: 'custom', body: mdmTemplate },
+  generic_table_id: null,
+})
+interopContractId = contractResp.data.id!
+```
+
+## 007 — create the manual-upload DAC
+
+```typescript
+const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Stripe Customer DAC ${runSuffix}`,
+  description: 'Manual-upload DAC — ingests Stripe customer rows into Customer 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!
+```
+
+## 008 — create the Priority Triage workflow
+
+The workflow targets the AR `customer` dataset. Two things make it
+agent-driven. First, the triage agent is **nested** in the create body (the
+`workflow_ai_agents` array) with a `context_mapping_config` that projects each
+customer's fields into the agent's input schema. Second, the `decision_config`
+interpolates the agent's `priority_band` (read from
+`additional_context["<agent-slug>"]`, bracket access because the slug has
+hyphens) into a one-element decision array. The three `actions` are keyed by
+band; whichever the agent emits fires, leaving the other two `:skipped`. The
+filter keeps only SMS-reachable, KYC-complete customers
+(`customer.phone and customer.tax_id`).
+
+```typescript
+const BANDS = ['priority_high', 'priority_medium', 'priority_low'] as const
+
+const CONTEXT_MAPPING_BODY = JSON.stringify({
+  customer_number: '{{ customer.customer_number }}',
+  customer_type: '{{ mdm_output.customer.customer_type }}',
+})
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].priority_band }}"]`
+const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
+
+const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Priority Triage Workflow ${runSuffix}`,
+  description: 'Bands AR customers into priority_high/medium/low via an LLM agent; one SMS action per band.',
+  dataset_type: 'customer',
+  status: 'live',
+  filter_config: {
+    type: 'custom',
+    body: '{% if customer.phone and customer.tax_id %}true{% endif %}',
+    output_schema: { type: 'boolean' },
+  },
+  decision_config: {
+    type: 'custom',
+    body: DECISION_CONFIG_BODY,
+    output_schema: DECISION_OUTPUT_SCHEMA,
+  },
+  actions: BANDS.map((band) => ({
+    decision_key: band,
+    action_type: 'sms',
+    tool_id: toolId,
+    position: 0,
+    trigger_template: 'now',
+    idempotency_template: `{{ customer_id }}-${band}-{{ "" | uuid }}`,
+    tool_call: {
+      tool_call_type: 'sms_request',
+      to: { type: 'custom', body: '{{ mdm_output.regulated_customer.phone }}' },
+      body: {
+        type: 'custom',
+        body: `[${band}] {{ mdm_output.regulated_customer.name }}, a note about account {{ customer.customer_number }}.`,
+      },
+      sms_type: 'transactional',
+    },
+  })),
+  // Nest the triage agent inline. Workflow joins omit output_schema — the
+  // server pins it from the agent's input_schema.
+  workflow_ai_agents: [
+    {
+      ai_agent_id: aiAgentId,
+      position: 0,
+      context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
+    },
+  ],
+})
+workflowId = workflowResp.data.id!
+ctx.workflowSlug = workflowResp.data.slug!
+```
+
+## 009 — ingest two Stripe customers
+
+Two rows through the manual-upload DAC: one enterprise account, one individual.
+Both carry a phone and a tax id so both pass the filter and reach the agent;
+they differ in `customer_type`, which is exactly what the agent bands on. Each
+ingest returns its own batch id; both are pinned for the run scope.
+
+```typescript
+const customerRows = [
+  {
+    customer_number: `CUS-ENT-${runSuffix}`,
+    customer_type: 'enterprise',
+    status: 'contracted',
+    name: 'Pinnacle Financial Group',
+    email: `ap-${runSuffix}@pinnacle.example`,
+    phone: '+12125559000',
+    tax_id: '84-2156789',
+    currency: 'usd',
+    source_uri: 'stripe.example.com',
+  },
+  {
+    customer_number: `CUS-IND-${runSuffix}`,
+    customer_type: 'individual',
+    status: 'contracted',
+    name: 'James Whitfield',
+    email: `james-${runSuffix}@example.com`,
+    phone: '+12025551001',
+    tax_id: '123-45-6789',
+    currency: 'usd',
+    source_uri: 'stripe.example.com',
+  },
+]
+
+const ingestResults = await Promise.all(
+  customerRows.map((row) =>
+    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: row }),
+  ),
+)
+ctx.customerBatchIds = ingestResults.map((r) => r.data.batch_id!)
+if (ctx.customerBatchIds.length !== 2) {
+  throw new Error(`expected 2 ingest batch ids, got ${ctx.customerBatchIds.length}`)
+}
+```
+
+## 010 — wait for the two ingest batches to reach steady-state
+
+Ingestion is async — poll the DAC's activation logs until both batches show a
+customer row was upserted (`rows_ingested >= 1` and a non-empty `output_files`).
+
+```typescript
+const targetBatches = new Set<string>(ctx.customerBatchIds)
+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
+    if (!Array.isArray(row.output_files) || row.output_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 customer batches reached steady-state within 90s`)
+}
+```
+
+## 011 — run the workflow against the two customers
+
+`workflows.run` drives the full agent-driven pipeline per row: filter → agent
+enrichment (the inference call that bands the customer) → decision (the band
+interpolated into the decision array) → action fan-out. The SQL where-clause
+scopes the run to the two batches (`ra` is the customer dataset alias). The
+window is generous because each row's enrichment is a live LLM call.
+
+```typescript
+const batchList = (ctx.customerBatchIds as string[]).map((b) => `'${b}'`).join(', ')
+
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: `ra.batch_id IN (${batchList})`,
+  mode: 'live',
+  manual_override: true,
+})
+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 triage workflow run reached :failed')
+}
+if (!status || status === 'pending') {
+  throw new Error('workflow run did not leave :pending within 240s')
+}
+```
+
+## 012 — verify the agent's band steered the fan-out
+
+Each customer produced a Workflow Execution Log. Every WEL has exactly **three**
+action execution logs — one per band — and exactly **one** is matched
+(`:pending` or `:completed`, the band the agent emitted) while the other **two**
+are `:skipped`. A WEL with two matched actions, or zero, would mean the agent's
+output did not actually steer the decision.
+
+```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}`)
+}
+
+for (const wel of ourWels) {
+  const welId = (wel as { id?: string }).id
+  const aels =
+    (wel as { action_execution_logs?: Array<{ status?: string }> }).action_execution_logs ?? []
+  if (aels.length !== 3) {
+    throw new Error(`WEL ${welId}: expected 3 AELs (one per band), got ${aels.length}`)
+  }
+  const byStatus: Record<string, number> = {}
+  for (const ael of aels) {
+    const st = ael.status ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const matched = (byStatus.pending ?? 0) + (byStatus.completed ?? 0)
+  if (matched !== 1) {
+    throw new Error(`WEL ${welId}: expected exactly 1 matched AEL, got ${matched} — ${JSON.stringify(byStatus)}`)
+  }
+  if ((byStatus.skipped ?? 0) !== 2) {
+    throw new Error(`WEL ${welId}: expected 2 :skipped AELs — ${JSON.stringify(byStatus)}`)
+  }
+}
+```
+
+# Branches
+
+- **Agent emits an out-of-enum band** — the response schema's
+  `enum: ['priority_high','priority_medium','priority_low']` guards the decision
+  interpolation. If the model returned an unexpected string the row's execution
+  log would land `:failed`. Production deployments either tighten the prompt or
+  add a `default` band action as a fallback.
+- **Per-band SMS template variation** — each action carries its own
+  `tool_call.body.body` Liquid. The cookbook renders the same body shape with
+  the band interpolated for clarity; production scenarios author a distinct
+  message per band (white-glove for high, a standard nudge for medium, a
+  low-urgency note for low).
+- **The filter still runs** — `customer.phone and customer.tax_id` gates which
+  customers reach the agent at all; both rows here qualify, so both are banded.
+  A customer missing either field would be `:filtered` before the agent saw it.
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down created resources. The
+`_setup/accounts_receivable.md` setup file's runSuffix-scoped names keep each run
+isolated; the seeded local DB is cheap to reset (`mix ecto.reset` on the platform
+repo).
+
+# Outcome
+
+After this cookbook runs green:
+
+- An SMS tool, an Ollama chat-completion LLM tool, a Priority Triage AI agent
+  (qwen3-vl:8b-instruct, three-band response schema), and an agent-driven
+  workflow over the `customer` dataset are all registered
+- Two Stripe customers (enterprise + individual) have been ingested through the
+  AR customer chain
+- Running the workflow drove each through the agent: the LLM banded the
+  customer, the decision interpolated the band, and the matching band's SMS
+  action fired
+- The routing is verified row-by-row — every Workflow Execution Log carries
+  exactly one matched action and two `:skipped`, proving the agent's output
+  steered the fan-out
+
+# See also
+
+- `_setup/accounts_receivable.md` — the inlined bootstrap this cookbook starts from
+- `dunning-sms-for-delinquent.md` — the static-decision AR counterpart (same
+  customer chain, one fixed action, no agent)
+- `score-leads-with-llm-categorization.md` — the foundation analogue (leads into
+  four bands over a generic table)
+- `ai-agent-invoke.md` — the capability doc for the agent + tool surface this uses
+- `.agent/workflows.md` — agent-driven workflow primitive; `workflow_ai_agents`,
+  `context_mapping_config`, agent-output decision interpolation
+- `integration-tests/tests/accounts_receivable/agent-lead-triage.test.ts` — the
+  anchor green test these snippets are lifted from