SDS-006: Softmax Router Multi-Agent Pattern

Document Type

Software Design Specification (SDS)

Purpose

Defines the architectural pattern for transformer-inspired multi-agent workflows that preserve attention invariants while enabling governed agentic execution.

1. Overview

This pattern treats attention mechanism mathematics as a coordination protocol that can be implemented as a governed multi-agent workflow. The key insight is that attention is fundamentally a routing + aggregation mechanism over a shared workspace—which is already most of what an orchestrated agent system does.

Core Principle

Attention math inspires agent orchestration patterns. Agents must be anchored to semantic roles with explicit contracts, bounded authority, and governed state.

2. Invariants to Preserve

When translating transformer architecture to agent workflows, these invariants must be maintained for the mapping to be isomorphic (not merely analogous):

Invariant	Transformer Form	Agent Workflow Form
Shared State	Residual stream (single vector stream read/written by all layers)	`ContextSnapshot` — shared context object
Bounded Contribution	Each head contributes bounded vector update	Schema + size + allowed fields per agent (not “infinite prose”)
Normalized Arbitration	Softmax ensures total influence is bounded	Router/arbiter normalizes contributions
Identity Stability	Tokens are stable identities across steps	ConceptId persistence via Semantic Core
Admissible Transformations	Attention reweights and mixes, cannot invent operations	Defined tools/ops per agent (PM-DSL / agent config)
Round-Based Iteration	Layers = discrete refinement steps	Explicit “rounds” (N passes), not open-ended chatter

3. Isomorphic Mapping Table

Transformer Component	Agentic Workflow Equivalent
Token stream / residual	Shared state (`ContextSnapshot` + working memory)
Attention head	Specialist agent (narrow skill, bounded output)
Q/K/V matrices	Query schema / capability signature / payload schema
Softmax routing	Router agent (relevance scoring + normalized budget)
Layer	One governance-checked round of updates
FFN (MLP)	Synthesis agent (transforms combined state)
LayerNorm	Contract validation + normalization + clipping
Multi-head	Parallel specialist proposals
Training objective	Feedback loop (reward / correctness / governance)

4. Component Roles

4.1 Router Agent

Responsibility: Determine which specialist agents are relevant and allocate attention budget.

Input:

Current ContextSnapshot
Task query

Output:

{
  "distribution": [
    { "agentId": "semantic-mapper", "weight": 0.35, "tokenBudget": 500 },
    { "agentId": "rule-analyst", "weight": 0.25, "tokenBudget": 300 },
    { "agentId": "arch-checker", "weight": 0.20, "tokenBudget": 200 },
    { "agentId": "retrieval-agent", "weight": 0.20, "tokenBudget": 200 }
  ],
  "toolPermissions": ["read-kgs", "query-sbvr"]
}

Design Notes:

Weights must sum to 1.0 (normalized)
Token budgets enforce bounded contribution
Tool permissions scope allowed operations

4.2 Specialist Agents (Parallel)

Each specialist has a narrow skill and produces bounded, structured output.

Examples:

Agent	Purpose	Output Schema
Semantic Mapper	Bind terms to ConceptIDs	`{ "mappings": [{ "term": string, "conceptId": string }] }`
Rule Analyst	Evaluate SBVR constraints	`{ "violations": [], "satisfactions": [], "unknowns": [] }`
Architecture Checker	CALM boundary checks	`{ "boundaryStatus": "ok" \| "violation", "details": [] }`
Retrieval Agent	KGS context lookup	`{ "nodes": [], "edges": [], "relevanceScores": [] }`

Output Contract:

Bounded “delta” to shared state (structured JSON, not prose)
Must conform to declared output schema
Cannot exceed token budget

4.3 Aggregator / Synthesis Agent

Responsibility: Combine specialist deltas into next ContextSnapshot.

Input:

All specialist outputs (weighted by router distribution)
Previous ContextSnapshot

Output:

Updated ContextSnapshot

Aggregation Logic:

Weight-based composition
Conflict resolution (if specialists disagree)
State delta tracking for provenance

4.4 Validator / Governor

Responsibility: Enforce invariants before committing state update.

Checks:

Schema conformance (all outputs match declared shapes)
ConceptId persistence (identity invariants)
Policy limits (SBVR rules, CALM controls)
State size bounds (no unbounded growth)

Actions:

Pass: State update committed
Clip: Invalid portions removed, remainder committed
Block: Entire update rejected, violation event emitted

5. Round Execution Flow

┌─────────────────────────────────────────────────────────────┐
│ Round N                                                      │
├─────────────────────────────────────────────────────────────┤
│  1. Router receives ContextSnapshot + Query                  │
│  2. Router outputs weight distribution + permissions         │
│  3. Specialists execute in parallel (bounded outputs)        │
│  4. Aggregator combines weighted deltas                      │
│  5. Validator checks invariants                              │
│     - Pass: ContextSnapshot(N+1) committed                   │
│     - Block: Violation event, no commit                      │
│  6. If more rounds needed: goto Round N+1                    │
└─────────────────────────────────────────────────────────────┘

6. Configurability Knobs

Want This?	Adjust This
Less hallucination	Stricter schemas, shorter deltas, more validator checks
More creativity	Loosen router scoring, add more specialists, but keep output bounded
Explainability	Log router weights (“why was this agent trusted?”) + provenance of each delta
Faster convergence	Reduce round count, increase specialist parallelism
Higher accuracy	Increase round count, tighter validation

7. Failure Modes to Watch

Failure Mode	Cause	Mitigation
Unbounded output	Agents produce prose instead of structured deltas	Enforce output schemas; clip/reject violations
State explosion	State grows without clipping	State size limits; delta-only updates
Political arbitration	“Loudest agent wins”	Normalized weights (softmax); router authority
Identity drift	Concepts rename themselves	ConceptId enforcement; identity invariants
Infinite rounds	No convergence criterion	Hard round limit; convergence detection

8. Integration Points

SEA™ Component	Role
Context Analyzer	Produces initial `ContextSnapshot`
Semantic Core	Provides ConceptIds, SBVR rules
Knowledge Graph Service	Stable identity + retrieval
Agent Configuration Service	Specialist role/capability definitions
Artifact Engine	Consumes final `ContextSnapshot` for projection

9. Example Configuration (Minimal Viable)

# softmax-router-config.yaml
router:
  agentId: "router-v1"
  model: "claude-sonnet"
  maxOutputTokens: 200

specialists:
  - agentId: "semantic-mapper"
    skill: "term-to-concept-binding"
    outputSchema: "$ref: schemas/semantic-mapper-output.json"
    maxOutputTokens: 500
  
  - agentId: "rule-analyst"
    skill: "sbvr-evaluation"
    outputSchema: "$ref: schemas/rule-analyst-output.json"
    maxOutputTokens: 300

aggregator:
  strategy: "weighted-merge"
  conflictResolution: "majority-vote"

validator:
  checks:
    - type: "schema"
    - type: "concept-id-persistence"
    - type: "sbvr-rules"
  onViolation: "block-and-emit"

execution:
  maxRounds: 5
  convergenceThreshold: 0.95

MVP Scope

⏳ Post-MVP (advanced agentic pattern)