How FAI Context Wiring Works

The Context Problem

In traditional AI tooling, each agent, skill, and instruction is isolated. They don't know about each other. Your RAG architect agent doesn't know which security instructions apply. Your deployment skill doesn't know which guardrail thresholds to check. You end up manually wiring context by duplicating rules, setting environment variables, and hoping everything stays in sync.

This is the problem the FAI Protocol solves. One JSON file — fai-manifest.json — declares the full context graph. The FAI Engine reads it and propagates shared context to every primitive automatically.

The FAI Solution: One Manifest to Wire Them All

The fai-manifest.json is a declarative wiring specification. It answers five questions simultaneously:

• Knowledge — Which FROOT modules should primitives reference? (F1, R2, O4…)
• Governance — Which WAF pillars are enforced across all primitives?
• Composition — Which agents, instructions, skills, and hooks participate?
• Quality — What groundedness, relevance, and safety thresholds apply?
• Infrastructure — What Azure services are required for deployment?

{
  "play": "01-enterprise-rag",
  "version": "1.0.0",
  "context": {
    "knowledge": ["F1", "F2", "R2", "O4"],
    "waf": ["security", "reliability", "cost-optimization"]
  },
  "primitives": {
    "agents": ["fai-rag-architect", "fai-azure-ai-search-expert"],
    "instructions": ["python-waf", "bicep-waf"],
    "skills": ["fai-play-initializer", "deploy-01-enterprise-rag"],
    "hooks": ["fai-secrets-scanner", "fai-cost-guardian"]
  },
  "guardrails": {
    "groundedness": 0.85,
    "relevance": 0.80,
    "coherence": 0.90,
    "safety": 0.95
  },
  "infrastructure": {
    "services": ["azure-openai", "azure-ai-search", "azure-cosmos-db"],
    "compute": "azure-container-apps"
  }
}

Context Resolution Chain (6 Steps)

When the FAI Engine loads a manifest, it follows this deterministic resolution chain:

How Shared Context Propagates

Once the manifest is resolved, every primitive in the play inherits the shared context. This means:

• An agent declared in primitives.agents automatically gets knowledge from context.knowledge injected as background context
• All instructions receive the WAF pillar overlays from context.waf
• Skills can reference guardrail thresholds for self-validation during execution
• Hooks inherit the full primitive list to enforce policies across the entire play

No primitive needs to declare its own knowledge or WAF settings when running inside a play — the manifest provides them. This eliminates duplication and ensures consistency across every component.

fai-manifest.json vs fai-context.json

These two files serve different purposes. The manifest is the full wiring spec for a solution play. The context file is a lightweight pointer for standalone primitives.

Standalone Context Example

A standalone agent or skill can ship with fai-context.json to declare its assumptions. This helps the FAI Engine auto-wire it when added to a play:

{
  "assumes": {
    "knowledge": ["F1", "R2"],
    "description": "Expects GenAI foundations and RAG module context"
  },
  "waf": ["security", "reliability"],
  "compatible-plays": ["01-enterprise-rag", "03-multimodal-rag"]
}

Knowledge Module References

The context.knowledgearray references FROOT modules by ID. Each module provides domain expertise that gets injected into the primitive's context window:

WAF Pillar Inheritance

When the manifest declares "waf": ["security", "reliability"], the engine automatically loads the corresponding instruction overlays and applies them to every primitive. Individual primitives can declare additional pillars, which get merged (union) with the play-level pillars.

# Play-level WAF (from fai-manifest.json)
  waf: [security, reliability]

# Agent-level WAF (from fai-rag-architect.agent.md)
  waf: [cost-optimization]

# Effective WAF for this agent inside this play:
  → [security, reliability, cost-optimization]   # Union of both

Wiring in Action

Load a play and inspect its resolved context using the FAI Engine CLI:

# Load Play 01 and show resolved status
node engine/index.js solution-plays/01-enterprise-rag/fai-manifest.json --status

# Output:
# ✅ Play: 01-enterprise-rag v1.0.0
# ✅ Knowledge: F1, F2, R2, O4 (4 modules loaded)
# ✅ WAF: security, reliability, cost-optimization (3 pillars active)
# ✅ Primitives: 2 agents, 2 instructions, 2 skills, 2 hooks
# ✅ Guardrails: groundedness≥0.85 relevance≥0.80 coherence≥0.90
# ✅ Status: READY

Common Wiring Patterns

Different solution architectures call for different wiring configurations. Here are the three most common patterns:

Debugging Context Issues

When a primitive doesn't behave as expected inside a play, the issue is usually a context wiring problem. Use these diagnostic steps:

# 1. Check if the manifest resolves cleanly
node engine/index.js fai-manifest.json --status

# 2. Verify a specific primitive is listed
node engine/index.js fai-manifest.json --list-primitives

# 3. Inspect resolved WAF pillars for the play
node engine/index.js fai-manifest.json --show-waf

# 4. Validate all primitives exist on disk
npm run validate:primitives

# Common fixes:
# - Primitive name in manifest doesn't match filename → fix the typo
# - Knowledge module ID invalid → use F1, F2, R1, R2, O1-O6, T1-T3
# - WAF pillar misspelled → use exact names from the 6-pillar set
# - Missing fai-context.json → standalone primitive can't auto-wire

Key Takeaways

• fai-manifest.json is the single source of truth for a solution play's context
• The 6-step resolution chain is deterministic and auditable
• WAF pillars are inherited (union merge) from play and primitive levels
• Standalone primitives use fai-context.json as a lightweight context pointer
• Knowledge modules are referenced by ID and injected at resolution time
• Always run --status after manifest changes to verify wiring