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]        ──┐
[model-provider]          ─┤
[kit-provider]            ─┤→ [agent] ──→ [agent.invoke: composition port]
[credential-provider]     ─┤
[capacity-provider]       ─┤
[capability.memory]       ─┤
[issue-tracker-provider]  ─┘

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

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

agent

The Agent Composer node. Fan-ins up to eight 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. DisplayName: Agent Definition.

Config

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

model-provider

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

Legacy alias: the id llm-model continues to resolve in saved workflows for back-compat. Use model-provider for all new definitions.

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-provider

DisplayName: Capacity Provider. 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.

Legacy alias: the id capacity-pool continues to resolve in saved workflows for back-compat. Use capacity-provider for all new definitions.

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

Output port - output (CapacityPoolRef)

issue-tracker-provider

DisplayName: Issue Tracker Provider. Points at one of the project's configured issue trackers and emits a typed IssueTrackerRef for wiring into the agent composer's optional issueProvider input port (the 8th port). The node uses a picker over the project's configured trackers - no manual tracker ID entry.

When issueProvider is omitted from the agent composer, the run resolves the project's PRIMARY tracker at dispatch time. Wire an issue-tracker-provider node only when you want to explicitly pin a non-default tracker for a particular dispatch path, or when a workflow serves a project with multiple active trackers and you need deterministic selection.

Emitted type

interface IssueTrackerRef {
  provider: string    // "linear" | "github_issues" | "jira" | "asana"
  trackerId: string   // Tracker-specific identifier (Linear workspace ID, GitHub repo full name, etc.)
}

Config - tracker picker (uses x-resource-kind: issue-tracker); selects from the project's configured and active trackers. Defaults to the project PRIMARY when no explicit selection is made in the config.

Output port - output (IssueTrackerRef)

Why this matters: before this node, agent composition was implicitly tied to the project's LINEAR tracker. Wiring an issue-tracker-provider node lets an agent read and write the project's chosen tracker (Linear, GitHub Issues, Jira, or others) through the tracker-agnostic issue.* generic action nodes, making the same workflow template portable across organizations using different trackers.

Codex tags: composition, provider

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. At dispatch the agent's session gains the af_code_* tool set: repository map (import-centrality ranked), symbol search, code search, duplicate detection, and type-usage scans, served over the runner's built-in code-intelligence MCP server against the session checkout.

Code-intel is enabled per project (an org admin opts a project in); until a project is enabled, wiring the node validates but resolves to a disabled stub at dispatch.

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: model-provider
    config:
      provider: claude
      model: claude-opus-4-8

  - id: pool
    type: action
    nodeId: capacity-provider
    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 model-provider profile refs resolve to actual models
• Sandbox Providers: Capacity Pools - what capacity-provider nodes point at
• Agent Cards: Overview - the agent_cards rows that agent-definition references
• Generic Action Nodes - tracker-agnostic issue.* nodes that use the resolved tracker from issue-tracker-provider