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

package/.agent/AGENTS.md

@@ -36,9 +36,9 @@ The one-line summaries in the Resources section are
 > The index line `workflows.md — Filter + decision + action;
 > standard + agent-driven variants` **cannot** tell you whether
 > `variant` is a body field. It is not. `workflows.md` §1 shows
-> the variant is **structural** — via the presence of the
-> `ai_agents[]` array on the request body — **not** a top-level
-> discriminator.
+> the variant is **structural** — an agent-driven workflow simply
+> has one or more AI agents *nested* on its body (the
+> `workflow_ai_agents` array) — **not** a top-level `variant` discriminator.
 
 An agent that paraphrases the index into a wire-level claim is
 **hallucinating**. The index summary is too compressed to encode

package/.agent/ai_agents.md

@@ -184,40 +184,75 @@ distinct names. A naming convention like `"<purpose>-<env>"` or
 including the datalake slug in the agent name keeps the
 namespace clean.
 
-## 3. Workflow attachment
+## 3. Workflow & contract nesting
 
-A workflow attaches an AI agent at its **enrichment** stage via
-the inline `ai_agents` array on the workflow body (see
-`workflows.md` §3):
+An agent runs as an **enrichment** step on a workflow or an
+interoperability contract. The agent is **nested directly on the
+parent body** — `agentic-workflows` and `interoperability-contracts`
+create/PUT bodies accept a `workflow_ai_agents` /
+`interoperability_contract_ai_agents` array (a `cast_assoc`). There is
+no separate attach/detach endpoint, and **no per-join checksum**: the
+nested agents fold into the parent's own checksum.
 
 ```typescript
-{
-  // ... other workflow fields ...
-  ai_agents: [
-    {
-      ai_agent_id: createdAgentId,
-      position: 0,                                  // ordering when multiple agents fire
-      context_mapping_config: {
-        type: 'custom',
-        // Liquid renders to a JSON object whose keys match the
-        // agent's input_schema. The values reference the inbound
-        // dataset row via `event_dataset.<field>`.
-        body: JSON.stringify({
-          msg:           '{{ event_dataset.message }}',
-          submission_id: '{{ event_dataset.submission_id }}',
-        }),
-        output_schema: '{"type":"object"}',
+// Nest on create. `position` is REQUIRED.
+const { data: workflow } = await api.workflows.create(
+  tenantSlug, datalakeSlug,
+  {
+    name: 'Contact-Us Triage',
+    dataset_type: 'generic_table',
+    // …other workflow fields…
+    workflow_ai_agents: [
+      {
+        ai_agent_id: createdAgentId,
+        position: 0,                              // ordering when multiple agents fire; REQUIRED
+        context_mapping_config: {
+          type: 'custom',
+          // Liquid renders to a JSON object whose keys match the agent's
+          // input_schema. Values reference the inbound row via `event_dataset.<field>`.
+          body: JSON.stringify({
+            msg:           '{{ event_dataset.message }}',
+            submission_id: '{{ event_dataset.submission_id }}',
+          }),
+          // Workflow joins OMIT output_schema — the server pins it from
+          // the agent's input_schema. Interop joins author it (below).
+        },
       },
-    },
-  ],
-  decision_config: {
-    type: 'custom',
-    // The agent's parsed output is exposed at
-    // `additional_context.<agent_slug>.<field>`. Property paths
-    // match the agent's llm_response_schema.
-    body: '["{{ additional_context.contact-us-triage-categorizer.category }}"]',
-    output_schema: '{"type":"array","items":{"type":"string"}}',
+    ],
   },
+)
+workflow.checksum   // the PARENT checksum — the nested agents fold into it
+```
+
+Interoperability contracts nest the same way, via the
+`interoperability_contract_ai_agents` array on the contract create/PUT
+body. The one difference: a contract join's `context_mapping_config`
+**does** carry `output_schema` (the server does not pin it there).
+
+Adding, repositioning, and removing agents are all expressed as a
+**full-set PUT** on the parent (`on_replace: :delete`):
+
+| Operation  | How                                                  | Result |
+|------------|------------------------------------------------------|--------|
+| add / nest | include in `*_ai_agents` on create or PUT            | parent checksum reflects the agents |
+| reposition | PUT with the same agent at a new `position`          | full-set replace |
+| detach     | PUT omitting that agent (or `[]` to clear all)       | `on_replace: :delete` removes it |
+| drift      | parent `checksum()` endpoint over the full body      | the would-be parent checksum (no persist) |
+
+The parent surfaces its nested agents on GET: a workflow GET returns
+`workflow_ai_agents: [...]` and a contract GET returns
+`interoperability_contract_ai_agents: [...]`. Both arrays are writable
+on the parent body (create + PUT).
+
+The workflow's own `decision_config` reads the agent's parsed output
+at `additional_context.<agent_slug>.<field>` (property paths match the
+agent's `llm_response_schema`):
+
+```typescript
+decision_config: {
+  type: 'custom',
+  body: '["{{ additional_context.contact-us-triage-categorizer.category }}"]',
+  output_schema: '{"type":"array","items":{"type":"string"}}',
 }
 ```
 

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -256,10 +256,11 @@ ctx.agentSlug = agentResp.data.slug!
 
 The workflow has the standard shape — filter, decision, actions —
 but two things distinguish it from a static workflow. First, the
-`ai_agents` array binds the Triage agent into the workflow's
-enrichment phase, with a Liquid `context_mapping_config` that
-projects each submission row's fields into the agent's input
-schema. Second, the `decision_config` body is a Liquid template
+Triage 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 submission row's fields
+into the agent's input schema. Second, the `decision_config` body is a Liquid template
 that interpolates the agent's `category` output (read from
 `additional_context["<agent-slug>"].category`) into a
 single-element decision array. The three `actions` are keyed
@@ -299,17 +300,6 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     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: BUCKETS.map((bucket) => ({
     decision_key: bucket,
     action_type: 'sms',
@@ -327,6 +317,15 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       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!

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

@@ -201,8 +201,10 @@ 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.
+plus the Sanctions Review agent **nested** in the create body (the
+`workflow_ai_agents` array — a `cast_assoc`, not a separate attach
+call) to bind it 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
@@ -256,17 +258,6 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     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',
@@ -284,6 +275,15 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       sms_type: 'transactional',
     },
   })),
+  // Nest the sanctions-review 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!

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

@@ -264,9 +264,11 @@ ctx.agentSlug = agentResp.data.slug!
 
 The workflow has the standard shape — filter, decision, actions — but
 two things distinguish it from the birthday cookbook's static
-workflow. First, the `ai_agents` array binds the Score Lead agent 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.
+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
@@ -307,17 +309,6 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     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: BANDS.map((band) => ({
     decision_key: band,
     action_type: 'sms',
@@ -335,6 +326,15 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       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!

package/.agent/interoperability_contracts.md

@@ -290,7 +290,72 @@ const { data: list } = await api.interoperabilityContracts.list(
 const editable = list.data.filter((c) => !c.system_created)
 ```
 
-## 6. Gotchas
+## 6. Nesting AI agents on the contract body
+
+A contract can run AI-agent **enrichment** during ingestion. Agents
+are **nested directly on the contract body** — the create/PUT body
+accepts an `interoperability_contract_ai_agents` array (a `cast_assoc`).
+There is no separate attach/detach endpoint, and **no per-join
+checksum**: the nested agents fold into the contract's own checksum.
+
+```typescript
+// Nest on create. `position` is REQUIRED.
+const { data: contract } = await api.interoperabilityContracts.create(
+  tenantSlug, datalakeSlug,
+  {
+    name: 'MOA Enrichment Contract',
+    resource_type: 'legal_entity',
+    template_config: { type: 'custom', body: '{{ name }}' },
+    mdm_input_config: { type: 'null' },
+    // …other contract fields…
+    interoperability_contract_ai_agents: [
+      {
+        ai_agent_id: createdAgentId,
+        position: 0,                       // ordering when multiple agents fire; REQUIRED
+        context_mapping_config: {
+          type: 'custom',
+          // Liquid renders to a JSON object whose keys match the agent's
+          // input_schema; values reference the inbound row via `msg.<field>`.
+          body: JSON.stringify({ name: '{{ msg.company_name }}' }),
+          // A contract join AUTHORS output_schema — unlike a workflow
+          // join, the server does NOT pin it here.
+          output_schema: '{"type":"object","properties":{"lead":{"type":"string"}}}',
+        },
+      },
+    ],
+  },
+)
+contract.checksum   // the PARENT checksum — the nested agents fold into it
+```
+
+Adding, repositioning, and removing agents are all expressed as a
+**full-set PUT** on the contract (`on_replace: :delete`):
+
+| Operation  | How                                              | Result |
+|------------|--------------------------------------------------|--------|
+| add / nest | include in the array on create or PUT            | contract checksum reflects the agents |
+| reposition | PUT with the same agent at a new `position`      | full-set replace |
+| detach     | PUT omitting that agent (or `[]` to clear all)   | `on_replace: :delete` removes it |
+| drift      | contract `checksum()` endpoint over the full body| the would-be contract checksum (no persist) |
+
+A contract GET surfaces its nested agents as
+`interoperability_contract_ai_agents: [...]`. The array is writable on
+the contract body (create + PUT).
+
+**Runtime.** Enrichment fires on the ingest path (`execute_contract`),
+**not** on the sandbox `.run`. Attached agents run in `position`
+order: each agent's `context_mapping_config` renders against the row,
+the result is validated against the agent's `input_schema`, sent to
+the bound `llm_enrichment` tool, and the parsed response is merged
+under `msg.enrichment.<agent_slug>` for the contract's
+`template_config` to read. So attaching an agent to a DAC-wired
+contract makes ingestion run enrichment per row — keep agents off
+contracts whose only job is a straight-through upsert.
+
+See `ai_agents.md` §3 for the agent create body and the shared attach
+surface, and `workflows.md` for the workflow side of the same join.
+
+## 7. Gotchas
 
 1. **`filter_template` is empty-passes, non-empty-skips.**
    Already documented in §2 — repeated here because it's the

package/.agent/workflows.md

@@ -92,9 +92,9 @@ const { data: created } = await api.workflows.create(
 )
 ```
 
-`actions`, `context_datasets`, and (for agent-driven workflows)
-`ai_agents` are all inline arrays — one POST builds the whole
-workflow.
+`actions`, `context_datasets`, and `workflow_ai_agents` are all
+inline arrays — one POST builds the entire workflow body, agents
+included (see §3).
 
 ## 2. Rules the type cannot encode
 
@@ -115,9 +115,9 @@ to validate the rendered output before invoking the next stage.
 
 ### Replace-on-PUT semantics for inline arrays
 
-`actions`, `context_datasets`, and `ai_agents` (when present)
-use **replace semantics on PUT**. Submitting an update body that
-omits any of these arrays silently disassociates ALL of its
+`actions` and `context_datasets` use **replace semantics on PUT**.
+Submitting an update body that omits either array silently
+disassociates ALL of its
 entries. Always re-supply the full array on every update, even
 when you're only changing `description`.
 
@@ -185,29 +185,43 @@ When `decision_config.type` references an AI agent (instead of
    action(s)
 ```
 
-Bound agents are declared in `ai_agents: []` on the workflow
-body. The full AI agent surface (create body, prompt config,
-input_schema / llm_response_schema, runtime failure codes) lives
-in `ai_agents.md`. The workflow-side embed shape is:
+Agents are **nested directly on the workflow body** — the create and
+PUT body accept a `workflow_ai_agents` array (a `cast_assoc`). There is
+no separate attach/detach endpoint. The agents **fold into the
+workflow's own checksum** — there is no per-join checksum. `position` is
+required, and workflow joins **omit `output_schema`** (the server pins
+it from the agent's `input_schema`). The agent create body (prompt
+config, `input_schema` / `llm_response_schema`, runtime failure codes)
+lives in `ai_agents.md` §3. A workflow GET surfaces the nested agents as
+`workflow_ai_agents: [...]`.
+
+PUT is a **full-set replace** (`on_replace: :delete`): the body must
+re-supply every agent you want to keep — agents absent from the array
+are detached, and re-supplied ones are repositioned.
 
 ```typescript
-ai_agents: [
-  {
-    ai_agent_id: aiAgentId,                          // UUID from api.aiAgents.create
-    position: 0,                                     // ordering when multiple agents fire
-    context_mapping_config: {
-      type: 'custom',
-      // Liquid renders to a JSON object whose keys match the
-      // referenced agent's input_schema. The values reference
-      // the inbound dataset row's fields via `event_dataset.<field>`.
-      body: JSON.stringify({
-        msg:           '{{ event_dataset.message }}',
-        submission_id: '{{ event_dataset.submission_id }}',
-      }),
-      output_schema: '{"type":"object"}',
+await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: 'Contact-Us Triage',
+  dataset_type: 'generic_table',
+  // …other workflow fields…
+  workflow_ai_agents: [
+    {
+      ai_agent_id: aiAgentId,                      // UUID from api.aiAgents.create
+      position: 0,                                 // ordering when multiple agents fire; REQUIRED
+      context_mapping_config: {
+        type: 'custom',
+        // Liquid renders to a JSON object whose keys match the referenced
+        // agent's input_schema. Values reference the inbound row's fields
+        // via `event_dataset.<field>`. Workflow joins OMIT output_schema
+        // — the server pins it from the agent's input_schema.
+        body: JSON.stringify({
+          msg:           '{{ event_dataset.message }}',
+          submission_id: '{{ event_dataset.submission_id }}',
+        }),
+      },
     },
-  },
-],
+  ],
+})
 ```
 
 The agent's parsed output is exposed in the workflow's runtime
@@ -219,9 +233,9 @@ action templates reference it via Liquid:
 {{ additional_context.contact-us-triage-categorizer.category }}
 ```
 
-Standard (non-agent) workflows omit `ai_agents` — the enrichment
-stage observably runs but emits `{ status: 'skipped' }` in the
-per-step artifact (see §6).
+A workflow with no attached agents observably runs the enrichment
+stage but emits `{ status: 'skipped' }` in the per-step artifact
+(see §6).
 
 ### `event_dataset` is the workflow accessor for the inbound row
 
@@ -273,7 +287,7 @@ filter_config                required embed — { type, body, output_schema }
 decision_config              required embed — same shape
 context_datasets             required array — inline; replace-on-PUT
 actions                      required array — inline; replace-on-PUT
-ai_agents                    optional array — inline; replace-on-PUT (§3)
+workflow_ai_agents          optional array — inline; replace-on-PUT (see §3)
 ```
 
 **Write-only (Request-only).** None.
@@ -550,10 +564,11 @@ record `opened_at` / `form_submitted_at`.
    `interoperability_contracts.md` §2 for the worked example.
 
 2. **Replace-on-PUT silently drops omitted arrays.** Workflow
-   updates must re-supply `actions`, `context_datasets`, and
-   `ai_agents` verbatim — otherwise the existing rows are
-   deleted. Factor the body construction so create and update
-   share one builder.
+   updates must re-supply `actions` and `context_datasets`
+   verbatim — otherwise the existing rows are deleted. Factor the
+   body construction so create and update share one builder.
+   (Nested `workflow_ai_agents` follow the same replace-on-PUT
+   rule — re-supply the full set on every PUT; see §3.)
 
 3. **`sql_where_clause` ids require an alias prefix.** `id` is
    ambiguous across the multi-JOIN base query; use