Foundational Nodes

Foundational nodes are configuration-source nodes: they produce typed reference objects that wire into agent.invoke or agent.dispatch as input ports, but they have no runtime side effects of their own. Every foundational node except wait is a pure configuration emitter - it resolves a reference at publish time and passes it downstream.

Think of them as named, typed configuration slots. Separating configuration from execution lets you:

• Reuse the same agent definition or model profile across multiple dispatch nodes
• Swap a model or credential in one place and have every downstream node pick up the change
• Build platform templates that users customize by replacing foundational nodes without editing action node configs

Composition pattern

Foundational nodes work in two ways:

Fan-in via the agent composer node (recommended for SDLC-style templates):

[agent-definition] ──┐
[llm-model]         ─┤
[kit-provider]      ─┤→ [agent] ──→ [agent.invoke: composition port]
[credential-provider]─┤
[capacity-pool]     ─┘
[capability.memory] ─/

Direct slot wiring (for one-off or override patterns):

[agent-definition] ──→ [agent.invoke: definition port]
[llm-model]         ──→ [agent.invoke: model port]

agent

The Agent Composer node. Fan-ins up to seven foundational ref inputs and emits a single composed AgentDispatchRef on its output port. Wire this to the composition port of agent.invoke or agent.dispatch.

Input ports

Output port - output (AgentDispatchRef): the fully composed dispatch reference.

agent-definition

Points at an agent_cards row and optionally applies inline overrides. Emits an AgentDefinitionRef for wiring into the agent composer or directly to agent.invoke's definition port.

Config

Output port - output (AgentDefinitionRef): { cardId, overrides? }

llm-model

Selects a model profile from the org catalog and optionally overrides per-call parameters. Emits a ModelRef.

Config

Output port - model (ModelRef)

kit-provider

Selects one or more donmai kits to attach to the agent. Emits a KitRef[]. Multiple kit-provider nodes can fan-in to the kits port of the agent composer - the executor concatenates them.

Config

Output port - kits (KitRef[])

credential-provider

Points at a credential stored in the org's credential vault. Emits a CredentialRef that the dispatcher resolves to env vars at dispatch time. Multiple credential-provider nodes can fan-in to the credentials port of the agent composer.

Config - credential picker (uses x-resource-kind: credential); select from connected org credentials.

Output port - output (CredentialRef)

capacity-pool

Points at an execution provider pool (the configuration that determines which sandbox the agent runs in). Required input for the agent composer and for agent.invoke's capacityPool slot.

Config - pool picker (uses x-resource-kind: capacity-pool); select from configured pools.

Output port - output (CapacityPoolRef)

sandbox-provider

Points at a specific sandbox provider (e2b, Vercel Sandbox, Docker, etc.) directly, bypassing the capacity pool routing layer. Use this when you need to pin a workflow to a specific sandbox type rather than letting the pool selector choose.

Config - sandbox provider picker.

Output port - output (SandboxRef)

Capability nodes

Capability nodes configure optional agent intelligence layers. Wire their outputs to the capabilities array port of the agent composer. Multiple capability nodes fan-in to build the full capability set for the agent dispatch.

capability.memory

Enables persistent memory for the agent. The agent can recall prior observations at session start and store durable facts as it works.

Config

Output port - capability (MemoryCapabilityRef)

capability.a2a

Enables agent-to-agent (A2A) communication. The agent can discover and call other registered agents via the A2A registry.

Output port - capability (A2ACapabilityRef)

capability.architecture

Enables architectural intelligence. The agent gets access to the knowledge graph and can query architectural context, code structure, and decision provenance.

Output port - capability (ArchitectureCapabilityRef)

capability.code-intel

Declares code intelligence for the agent. Requires a repo (code-intel is repo-scoped) and accepts an optional ref commit/branch pin.

Output port - capability (CodeIntelCapabilityRef)

wait

Pauses the workflow until a resume condition is met. Unlike the gate node (which is human-driven), wait supports timer, webhook, and signal-based resumption. The wait node is foundational because it is side-effect-free - it does not call any provider; it only suspends and resumes the execution flow.

Resume modes

Config

Ports: trigger input (optional, passes upstream envelope through) → output (resume payload)

Example: SDLC agent composition

steps:
  - id: def
    type: action
    nodeId: agent-definition
    config:
      cardId: "{{ org.agentCards.devAgent }}"

  - id: model
    type: action
    nodeId: llm-model
    config:
      provider: claude
      model: claude-opus-4-8

  - id: pool
    type: action
    nodeId: capacity-pool
    config: {}  # uses x-resource-kind picker in UI

  - id: mem
    type: action
    nodeId: capability.memory
    config:
      scope: project

  - id: composed
    type: action
    nodeId: agent
    inputs:
      definition: "{{ nodes.def.output }}"
      model: "{{ nodes.model.model }}"
      capacityPool: "{{ nodes.pool.output }}"
      capabilities: ["{{ nodes.mem.capability }}"]

  - id: dispatch
    type: action
    nodeId: agent.invoke
    inputs:
      composition: "{{ nodes.composed.output }}"
      stageEvent: "{{ $trigger.data }}"

Related pages

• Agent Action Nodes - agent.invoke, agent.dispatch_stage, consuming foundational refs
• Model Routing: Catalog and Routing - how llm-model profile refs resolve to actual models
• Sandbox Providers: Capacity Pools - what capacity-pool nodes point at
• Agent Cards: Overview - the agent_cards rows that agent-definition references