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

package/.agent/cookbook/score-leads-with-llm-categorization.md

@@ -0,0 +1,624 @@
+---
+title: Score inbound leads into four bands via an LLM agent and route each band to a tailored SMS
+summary: End-to-end agent-driven workflow — a chat-completion LLM agent classifies each lead submission into hot/warm/cold/spam, the workflow's decision interpolates the agent's band, four SMS actions (one per band) fan out, and the run is verified row-by-row so every WEL carries exactly one matched action and three skipped.
+industry: foundation
+slug: score-leads-with-llm-categorization
+vitest_source:
+  - integration-tests/tests/foundation/agent-driven-workflow.test.ts
+  - integration-tests/tests/foundation/generic-tables.test.ts
+  - integration-tests/tests/foundation/tools.test.ts
+  - integration-tests/tests/foundation/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+The previous foundation cookbook (`birthday-greeting-sms-trigger`)
+demonstrated a static decision: the workflow's decision_config was a
+literal Liquid array naming one fixed decision key, and a single SMS
+action fired for every matched row. Many real outbound engagements
+need the opposite: the action that fires depends on what the row
+says, not just on the fact that it matched the filter.
+
+A B2B lead-scoring scenario is the canonical shape. A submission on a
+contact-us form might be a hot prospect ready to buy, a warm explorer
+who needs nurture, a cold tire-kicker, or outright spam. The same
+workflow should pick the right tone of SMS for each. The
+classification is a language task, not a rules task — applying a
+hand-coded keyword filter would either over-fit the training set or
+miss every variation of phrasing.
+
+The Alvera platform's agent-driven workflow primitive flips the
+decision step into an LLM enrichment plus a Liquid interpolation. An
+AI agent receives the row's free-text via a context-mapping template,
+returns a JSON object whose `band` field is one of the four enum
+values, and the workflow's decision_config interpolates that band
+into a one-element decision array
+(`["{{ additional_context["agent-slug"].band }}"]`). Four SMS actions
+are registered against the workflow, one per band; the agent's output
+picks which one runs.
+
+This cookbook walks the **whole** scenario: it provisions the custom
+dataset, agent, and workflow, ingests lead rows through the
+generic-table's auto-provisioned default DAC, runs the workflow so the
+agent classifies each row, and verifies the routing row-by-row —
+every Workflow Execution Log carries exactly one matched action and
+three skipped, proving the agent's band actually steered the fan-out.
+
+The scenario is anchored to
+`platform/integration-tests/tests/foundation/agent-driven-workflow.test.ts`
+— a green end-to-end test (§1–§5). The setup file `_setup/foundation.md`
+already provisioned the tenant + datalake + tenant-scoped client; this
+cookbook starts from there.
+
+# Composition
+
+| Resource provisioned             | Owner       |
+|----------------------------------|-------------|
+| Lead Submissions generic table  | build       |
+| SMS tool (SNS-backed)            | build       |
+| LLM tool (Ollama chat completion)| build       |
+| Score Lead AI agent              | build       |
+| Score Lead workflow              | build       |
+
+The generic table's **default DAC** — auto-provisioned by the
+platform when the generic table is created — is reused for ingestion;
+no separate data source / tool / interop contract / DAC is created.
+The setup file `_setup/foundation.md` already provisioned the tenant +
+datalake + tenant-scoped client; this cookbook starts from there.
+
+# Walkthrough
+
+## 001 — create the Lead Submissions generic table
+
+The agent-driven workflow targets a Generic Table dataset
+(`dataset_type: 'generic_table'`) rather than a regulated domain
+entity, because lead-capture form rows do not fit a canonical industry
+entity. The table's columns mirror the shape an Airtable/Google-Sheets
+export would produce; the `message` and `lead_source` columns are what
+the agent reads, and `band` is what the agent eventually writes back
+in production. The server-derived `name` is captured — the workflow
+run in §009 addresses the regulated table as `regulated_<name>`.
+
+```typescript
+const genericTableResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
+  title: `Cookbook Lead Submissions ${runSuffix}`,
+  description: 'Inbound lead-capture form rows the Score Lead agent classifies.',
+  columns: [
+    {
+      name: 'submission_id',
+      title: 'Submission ID',
+      type: 'string',
+      description: 'Vendor-supplied unique submission id',
+      is_unique: true,
+      privacy_requirement: 'none',
+    },
+    {
+      name: 'name',
+      title: 'Name',
+      type: 'string',
+      description: 'Submitter full name',
+      is_unique: false,
+      privacy_requirement: 'tokenize',
+    },
+    {
+      name: 'email',
+      title: 'Email',
+      type: 'string',
+      description: 'Submitter email — also the legal-entity identifier',
+      is_unique: false,
+      privacy_requirement: 'tokenize',
+    },
+    {
+      name: 'message',
+      title: 'Message',
+      type: 'string',
+      description: 'Free-text lead message — the agent classifies this',
+      is_unique: false,
+      privacy_requirement: 'none',
+    },
+    {
+      name: 'lead_source',
+      title: 'Lead Source',
+      type: 'string',
+      description: 'utm_source / sheet tab id',
+      is_unique: false,
+      privacy_requirement: 'none',
+    },
+    {
+      name: 'band',
+      title: 'Band',
+      type: 'string',
+      description: 'Lead-scoring band assigned by Score Lead agent',
+      is_unique: false,
+      privacy_requirement: 'none',
+    },
+  ],
+})
+genericTableId = genericTableResp.data.id!
+ctx.gtName = genericTableResp.data.name!
+```
+
+## 002 — create the SMS tool
+
+A single SMS tool dispatches every band's outbound message; the
+per-band SMS body lives on each workflow action, not on the tool. Same
+SNS-backed LocalStack wiring as the birthday cookbook — `intent: 'sms'`
+tags it for workflow-action use.
+
+```typescript
+const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Tool ${runSuffix}`,
+  description: 'SNS-backed SMS dispatcher for the Score Lead 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!
+```
+
+## 003 — create the LLM tool
+
+The Score Lead agent calls a chat-completion endpoint to classify each
+row. The tool's `intent: 'llm_enrichment'` distinguishes it from the
+SMS tool above. It is a **provider adapter**: `base_body` authors the
+provider's request — here Ollama's native `/api/chat` shape with
+`think: false` and a `format` schema so the model returns clean,
+schema-constrained JSON — and `response_extractor` maps the provider's
+envelope back to the canonical `{ output_json, … }` the platform reads.
+The extractor's `output_schema` is required for an `llm_enrichment`
+tool. The `api_key`/`auth_method` pair satisfies the REST tool's schema
+even though Ollama ignores the header.
+
+```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 Score Lead classification.',
+  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!
+```
+
+## 004 — create the Score Lead AI agent
+
+The agent binds three things: the model name (sent on every inference
+call), 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: ['hot','warm','cold','spam']` constraint is what
+guards the downstream decision interpolation from emitting a band the
+workflow has no SMS action for. `temperature: 0.0` removes sampling
+noise so identical inputs classify identically. `data_access:
+'unregulated'` says the agent only ever sees the tokenized projection
+of each row, never the regulated identifiers.
+
+```typescript
+const SCORE_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    message: { type: 'string' },
+    lead_source: { type: 'string' },
+  },
+  required: ['name', 'message'],
+}
+
+const SCORE_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    band: { type: 'string', enum: ['hot', 'warm', 'cold', 'spam'] },
+  },
+  required: ['band'],
+}
+
+const AGENT_PROMPT_BODY = `You are a B2B lead-scoring assistant. Classify the following lead's intent into EXACTLY ONE of these bands:
+
+- "hot"  — clear buying intent, decision maker, ready to engage
+- "warm" — interested but exploratory, requires nurture
+- "cold" — generic/lukewarm interest, low conversion signal
+- "spam" — promotional, irrelevant, or low-quality submission
+
+Lead name: {{ name }}
+Lead message: {{ message }}
+Lead source: {{ lead_source }}
+
+Respond with a JSON object: {"band": "<one of hot|warm|cold|spam>"}`
+
+const agentResp = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Score Lead Agent ${runSuffix}`,
+  tool_id: ctx.llmToolId,
+  model: 'qwen3-vl:8b-instruct',
+  data_access: 'unregulated',
+  temperature: 0.0,
+  max_tokens: 1024,
+  enabled: true,
+  input_schema: SCORE_INPUT_SCHEMA,
+  llm_response_schema: SCORE_RESPONSE_SCHEMA,
+  prompt_config: { type: 'custom', body: AGENT_PROMPT_BODY },
+})
+aiAgentId = agentResp.data.id!
+ctx.agentSlug = agentResp.data.slug!
+```
+
+## 005 — create the Score Lead workflow
+
+The workflow has the standard shape — filter, decision, actions — but
+two things distinguish it from the birthday cookbook's static
+workflow. First, the Score Lead agent is **nested** in the workflow
+create body (the `workflow_ai_agents` array — a `cast_assoc`, not a
+separate attach call), binding it into the workflow's enrichment phase
+with a Liquid `context_mapping_config` that projects each lead row's
+fields into the agent's input schema.
+Second, the `decision_config` body is a Liquid template that
+interpolates the agent's `band` output (read from
+`additional_context["<agent-slug>"].band`) into a single-element
+decision array. The four `actions` are keyed `decision_key:
+hot|warm|cold|spam`; whichever band the agent emits picks the action
+that fires, leaving the other three `:skipped`.
+
+Bracket access (`additional_context["..."]`) is required because the
+agent's slug contains hyphens, which Solid's dot parser would
+otherwise read as subtraction operators.
+
+```typescript
+const BANDS = ['hot', 'warm', 'cold', 'spam'] as const
+
+const CONTEXT_MAPPING_BODY = JSON.stringify({
+  name: '{{ event_dataset.name }}',
+  message: '{{ event_dataset.message }}',
+  lead_source: '{{ event_dataset.lead_source }}',
+})
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].band }}"]`
+const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
+
+const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Score Lead Workflow ${runSuffix}`,
+  description: 'Classifies lead_submissions into hot/warm/cold/spam via an LLM agent; one SMS action per band.',
+  dataset_type: 'generic_table',
+  generic_table_id: genericTableId,
+  skip_mdm_resolution: true,
+  status: 'live',
+  filter_config: {
+    type: 'custom',
+    body: 'true',
+    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: `{{ subject_id }}-{{ action_id }}-${band}-{{ "" | uuid }}`,
+    tool_call: {
+      tool_call_type: 'sms_request',
+      to: { type: 'custom', body: '+15551234567' },
+      body: {
+        type: 'custom',
+        body: `Lead band [${band}]: {{ event_dataset.message }}`,
+      },
+      sms_type: 'transactional',
+    },
+  })),
+  // Nest the scoring 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!
+```
+
+## 006 — find the generic table's auto-provisioned default DAC
+
+Creating a generic table provisions two things automatically: an
+identity interoperability contract and a default Data Activation
+Client bound to it (name pattern
+`<datalake> <gt_name> DataActivationClient`, `tool_call:
+manual_upload`). No data source, tool, interop contract, or DAC needs
+to be created by hand for plain row ingestion into the table — the
+default DAC is found by GT-name convention in the DAC listing.
+
+```typescript
+const deadline = Date.now() + 30_000
+let found: { slug?: string | null; name?: string | null } | undefined
+while (Date.now() < deadline && !found) {
+  const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+  found = (data.data ?? []).find((d) => (d.name ?? '').includes(ctx.gtName))
+  if (!found) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (!found?.slug) {
+  throw new Error(`no default DAC found for GT ${ctx.gtName} within 30s`)
+}
+ctx.dacSlug = found.slug
+```
+
+## 007 — ingest three lead rows through the default DAC
+
+Three rows, ingested as inline JSON through the default DAC. Each
+carries a deliberately distinct `message` — a clear buying signal, a
+lukewarm browse, and obvious promotional spam — so the agent has
+something unambiguous to classify. The `band` column is left unset on
+ingest; it is the agent's job to assign one. Each ingest call returns
+its own batch id; all three are pinned for the run scope in §009.
+
+```typescript
+const leadRows = [
+  {
+    submission_id: `LEAD-HOT-${runSuffix}`,
+    name: 'Dana Decisive',
+    email: `dana-${runSuffix}@example.com`,
+    message:
+      'We have budget approved and need to roll out to 500 seats this quarter — can we start onboarding next week?',
+    lead_source: 'cookbook_score_leads',
+  },
+  {
+    submission_id: `LEAD-COLD-${runSuffix}`,
+    name: 'Sam Browsing',
+    email: `sam-${runSuffix}@example.com`,
+    message: 'Just browsing — found your site via a blog post. No particular need right now.',
+    lead_source: 'cookbook_score_leads',
+  },
+  {
+    submission_id: `LEAD-SPAM-${runSuffix}`,
+    name: 'Promo Bot',
+    email: `promo-${runSuffix}@example.com`,
+    message:
+      'BUY CHEAP FOLLOWERS NOW!!! 90% off SEO backlinks, crypto giveaways, click here click here!!!',
+    lead_source: 'cookbook_score_leads',
+  },
+]
+
+const ingestResults = await Promise.all(
+  leadRows.map((row) =>
+    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: row }),
+  ),
+)
+ctx.leadBatchIds = ingestResults.map((r) => r.data.batch_id!)
+if (ctx.leadBatchIds.length !== 3) {
+  throw new Error(`expected 3 ingest batch ids, got ${ctx.leadBatchIds.length}`)
+}
+```
+
+## 008 — wait for the three ingest batches to reach steady-state
+
+Ingestion is async — the DAC enqueues per-row jobs that drain into the
+generic table. Poll the DAC's activation logs until every batch shows
+a row with `dataset_updated >= 1` (the lead row was upserted into the
+table).
+
+```typescript
+const targetBatches = new Set<string>(ctx.leadBatchIds)
+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.dataset_updated !== 'number' || row.dataset_updated < 1) 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}/3 lead-row batches reached steady-state within 90s`)
+}
+```
+
+## 009 — run the workflow against the three lead rows
+
+`workflows.run` triggers the full agent-driven pipeline per row:
+filter → agent enrichment (the Ollama call that classifies the lead)
+→ decision (the band interpolated into the decision array) → action
+fan-out. The SQL where-clause scopes the run to exactly the three
+batches §007 ingested (`regulated_<gt_name>` is the regulated mirror
+the run-query addresses).
+
+Unlike the birthday workflow, the Score Lead actions use
+`trigger_template: 'now'`, so they dispatch immediately and the run
+reaches a terminal status — poll `batchLogs.refresh` until it leaves
+`:pending`. The window is generous because each row's enrichment is a
+live LLM inference call.
+
+```typescript
+const regulatedTable = `regulated_${ctx.gtName}`
+const batchList = (ctx.leadBatchIds as string[]).map((b) => `'${b}'`).join(', ')
+
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: `${regulatedTable}.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 workflow run reached :failed')
+}
+if (!status || status === 'pending') {
+  throw new Error('workflow run did not leave :pending within 240s')
+}
+```
+
+## 010 — verify the agent's band steered the fan-out
+
+This is the assertion the old shallow cookbook could never make,
+because it never ran the workflow. Each lead row produced a Workflow
+Execution Log. Every WEL has exactly **four** action execution logs —
+one per band — and exactly **one** is matched (`:pending` or
+`:completed`, the band the agent emitted) while the other **three**
+are `:skipped`. A run where a WEL had two matched actions, or zero,
+would mean the agent's output did not actually steer the decision;
+this step fails loudly in that case.
+
+```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 !== 3) {
+  throw new Error(`expected 3 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 !== 4) {
+    throw new Error(`WEL ${welId}: expected 4 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) !== 3) {
+    throw new Error(`WEL ${welId}: expected 3 :skipped AELs — ${JSON.stringify(byStatus)}`)
+  }
+}
+```
+
+# Branches
+
+- **The filter is permissive** — `filter_config.body: 'true'` passes
+  every row, so all three lead rows reach the agent. The interesting
+  routing happens at the decision step, not the filter. A production
+  scoring workflow might gate on `lead_source` or a not-yet-contacted
+  flag in the filter; that polarity is covered by the standard-workflow
+  cookbook.
+- **Agent emits an out-of-enum band** — the LLM response schema's
+  `enum: ['hot','warm','cold','spam']` constraint guards the decision
+  interpolation. If the model returned an unexpected string the
+  workflow row's execution log would land `:failed`. The anchor vitest
+  treats that as a model-quality failure rather than a platform bug;
+  production deployments either tighten the prompt or add a `default`
+  SMS action as a fallback band.
+- **Per-band SMS template variation** — each action in the `actions`
+  array carries its own `tool_call.body.body` Liquid template. The
+  cookbook renders the same body shape with the band name interpolated
+  for clarity; production scenarios would author distinct messages per
+  band (a thank-you for hot, a nurture link for warm, an
+  unsubscribe-friendly close for cold, no message at all for spam by
+  omitting that action).
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down created
+resources. The `_setup/foundation.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 ten steps run green:
+
+- A foundation tenant exists with a foundation-domain datalake
+- A Lead Submissions Generic Table, an SMS tool, a chat-completion LLM
+  tool, a Score Lead AI agent (qwen3-vl:8b-instruct, four-band response schema),
+  and a Score Lead agent-driven workflow are all registered
+- Three lead rows have been ingested through the table's
+  auto-provisioned default DAC
+- Running the workflow drove each row through the agent: the LLM
+  classified the lead, 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 three `:skipped`, proving the
+  agent's output actually steered the fan-out
+
+The business outcome — inbound leads classified by an LLM and routed
+to band-specific outreach — is demonstrated end-to-end, not merely
+provisioned.
+
+# See also
+
+- `_setup/foundation.md` — the inlined bootstrap that provisions the
+  tenant + datalake this cookbook starts from
+- `birthday-greeting-sms-trigger.md` — the static-decision counterpart
+  in foundation; same SMS wiring, full data-activation chain, no agent
+- `.agent/tools.md` — SMS and chat-completion tool body shapes; intent
+  classification
+- `.agent/ai_agents.md` — AI agent registration shape; input + response
+  schemas; prompt config
+- `.agent/workflows.md` — standard and agent-driven workflow
+  primitives; `ai_agents`, `context_mapping_config`, and agent-output
+  decision interpolation
+- `.agent/generic_tables.md` — generic-table creation and the
+  auto-provisioned identity contract + default DAC
+- `.agent/ai_sandbox.md` — bounds on the Liquid sandbox the
+  context-mapping and decision templates execute inside
+- `integration-tests/tests/foundation/agent-driven-workflow.test.ts` —
+  the anchor green test (§1–§5) these snippets are lifted from
+- `integration-tests/tests/foundation/generic-tables.test.ts` — §2 the
+  Generic Table create snippet is lifted from
+- `integration-tests/tests/foundation/tools.test.ts` — the SMS tool
+  create snippet is lifted from