FAI Protocol — v0.1 Specification

The declarative context-wiring standard for AI primitive orchestration.

Abstract

The FAI Protocol defines a JSON-based manifest format (fai-manifest.json) for declaring how AI primitives — agents, instructions, skills, hooks, workflows, plugins, tools, prompts, and guardrails — are wired together into a coherent, evaluated, deployable system. It provides the missing “glue layer” between isolated AI building blocks, enabling them to share context, enforce quality gates, and compose into reproducible solutions. The protocol is model-agnostic, framework-agnostic, and cloud-agnostic.

Status

This specification is at v0.1 (Draft). It is implemented by the FAI Engine reference implementation and validated across solution plays comprising agents, instructions, skills, and plugins.

1. Introduction

1.1 Problem

The AI tooling ecosystem has produced hundreds of capable building blocks — agents, retrieval pipelines, prompt templates, guardrails, evaluation harnesses, infrastructure modules — but no standard for wiring them together. Each framework (LangChain, Semantic Kernel, AutoGen, CrewAI) defines its own composition model, and each platform (Azure AI Foundry, AWS Bedrock, Vertex AI) adds its own orchestration layer. The result is fragmented, non-portable AI systems where changing one component requires rewiring everything manually.

Protocols like MCP (Model Context Protocol) standardize tool calling. A2A (Agent-to-Agent) standardizes delegation. AG-UI standardizes rendering. But none of them address the fundamental question: how do you declare which primitives a system uses, how they share context, and what quality thresholds they must meet?

1.2 Solution

The FAI Protocol introduces fai-manifest.json — a single declarative file that serves as the Dockerfile equivalent for AI systems. Just as a Dockerfile declares base images, dependencies, and build steps for a container, fai-manifest.json declares knowledge context, primitives, quality guardrails, infrastructure, and toolkit paths for an AI solution. A conformant runtime reads the manifest, resolves all paths, injects shared context into every primitive, and evaluates outputs against declared thresholds.

1.3 Scope

The FAI Protocol covers:

• Declaration of the 9 primitive types and their file paths
• Shared context wiring (knowledge modules + WAF pillars)
• Quality guardrail thresholds (groundedness, coherence, relevance, safety, cost)
• Infrastructure-as-Code references (Bicep, Terraform, Pulumi, Docker, Helm, Kubernetes)
• Toolkit structure (DevKit, TuneKit, SpecKit)
• Standalone primitive context via the companion fai-context.json format

The FAI Protocol delegates to other standards:

2. Terminology

3. Manifest Format

A manifest is a JSON file named fai-manifest.json located at the root of a play directory. It MUST conform to the JSON Schema at ../schemas/fai-manifest.schema.json.

3.1 Required Fields

Every manifest MUST include four top-level fields:

Example — Minimal manifest:

{
  "play": "01-enterprise-rag",
  "version": "1.0.0",
  "context": {
    "knowledge": ["R2-RAG-Architecture", "O4-Azure-AI-Services"],
    "waf": ["security", "reliability", "cost-optimization"]
  },
  "primitives": {
    "agents": [
      "./agent.md",
      "./.github/agents/builder.agent.md"
    ],
    "instructions": [
      "./.github/copilot-instructions.md"
    ],
    "skills": [
      "./.github/skills/rag-indexer"
    ]
  }
}

3.2 Context Section

The context object declares shared knowledge and governance that applies to every primitive loaded from this manifest. It is the mechanism that transforms isolated building blocks into a coherent system.

Example:

{
  "context": {
    "knowledge": [
      "F1-GenAI-Foundations",
      "R2-RAG-Architecture",
      "O4-Azure-AI-Services",
      "T3-Production-Patterns"
    ],
    "waf": [
      "security",
      "reliability",
      "cost-optimization",
      "responsible-ai"
    ],
    "scope": "enterprise-rag-qa"
  }
}

When the FAI Engine loads a primitive, it injects the resolved knowledge content and WAF constraints into the primitive’s execution context. This ensures that an agent designed for RAG automatically receives RAG architecture knowledge and enforces the security pillar, without the agent needing to declare these dependencies itself.

3.3 Primitives Section

The primitives object maps each primitive type to an array of file or folder paths, relative to the manifest’s directory.

Paths follow the resolution rules defined in §5.

3.4 Guardrails Section

Guardrails are inline quality thresholds declared within the primitives object. The FAI Engine evaluates every agent response against these thresholds and reports pass/fail per metric.

Example:

{
  "primitives": {
    "agents": ["./agent.md"],
    "guardrails": {
      "groundedness": 0.95,
      "coherence": 0.90,
      "relevance": 0.85,
      "safety": 0,
      "costPerQuery": 0.02
    }
  }
}

A conformant engine MUST evaluate at least groundedness and safety when guardrails are declared. Engines MAY skip metrics that require infrastructure not available in the runtime environment (e.g., costPerQuery requires a billing API).

3.5 Infrastructure Section (Optional)

The infrastructure object references Infrastructure-as-Code templates for provisioning cloud resources. This section is OPTIONAL — plays that are framework-only (no cloud resources) omit it.

A manifest MAY declare multiple infrastructure formats simultaneously, enabling multi-cloud deployment from a single play.

Example:

{
  "infrastructure": {
    "bicep": "./infra/main.bicep",
    "parameters": "./infra/main.bicepparam",
    "docker": "./docker-compose.yml"
  }
}

3.6 Toolkit Section (Optional)

The toolkit object declares paths to the three kits that equip every play. This section is OPTIONAL but RECOMMENDED for plays that follow the full FAI structure.

Example:

{
  "toolkit": {
    "devkit": "./.github",
    "tunekit": "./config",
    "speckit": "./spec"
  }
}

4. Context Resolution

4.1 Knowledge Module IDs

Knowledge modules are identified by a layer prefix, numeric ID, and descriptive name, following the FROOT taxonomy:

A conformant engine MUST recognize all module IDs listed above. Engines MAY support additional custom module IDs prefixed with X (e.g., X1-Custom-Domain).

4.2 WAF Pillar Values

The following six values are the only valid entries in the context.waf and fai-context.json waf arrays:

4.3 Context Inheritance

When a primitive is loaded into a play, context flows as follows:

1. The FAI Engine reads the manifest’s context.knowledge and resolves each module ID to content.
2. The engine reads the manifest’s context.waf to determine which pillars are enforced.
3. For each primitive path in primitives.*, the engine loads the primitive file.
4. If the primitive has a sibling fai-context.json, the engine merges the standalone context with the play context. Play context takes precedence on conflict.
5. The merged context is injected into the primitive’s runtime environment.

Precedence rules:

• Play-level waf pillars are additive: a standalone primitive declaring ["security"] in its fai-context.json, loaded into a play declaring ["security", "reliability"], will have both pillars enforced.
• Play-level knowledge modules replace standalone assumes: if the play declares knowledge, the engine resolves play-level modules, not the primitive’s assumed modules.
• Play-level guardrails override any evaluation thresholds in fai-context.json.

5. Path Resolution

5.1 Relative Paths

All paths in the manifest are resolved relative to the directory containing fai-manifest.json.

Example — Mixed paths:

{
  "primitives": {
    "agents": [
      "./agent.md",
      "./.github/agents/builder.agent.md",
      "../../agents/fai-rag-architect.agent.md"
    ],
    "skills": [
      "./.github/skills/rag-indexer",
      "../../skills/fai-play-initializer"
    ]
  }
}

A conformant engine MUST resolve all paths and report an error if any path does not point to an existing file or directory.

5.2 Standalone vs Embedded

Primitives can be authored in two modes:

A standalone primitive becomes embedded when referenced from a play’s manifest. The FAI Engine handles context injection transparently — the primitive’s code does not need to change.

DRY Principle: If a primitive is used by 2 or more plays, it SHOULD be authored as standalone and referenced via ../../ paths. If it is specific to a single play, it SHOULD be embedded.

6. Companion Format: fai-context.json

The fai-context.json file is a lightweight context descriptor for standalone primitives. It is the “LEGO connector” that makes an isolated building block aware of the broader FAI ecosystem.

A fai-context.json file MUST conform to the JSON Schema at ../schemas/fai-context.schema.json.

6.1 Fields

6.2 Example

{
  "assumes": ["R2-RAG-Architecture", "O3-MCP-Tools"],
  "waf": ["security", "reliability"],
  "compatiblePlays": ["01-enterprise-rag", "21-agentic-rag", "28-graphrag"],
  "evaluation": {
    "groundedness": 0.95,
    "coherence": 0.90,
    "relevance": 0.85,
    "costPerQuery": 0.01
  },
  "requires": []
}

6.3 Placement

The fai-context.json file MUST be placed as a sibling of the primitive it describes, or inside the primitive’s folder:

agents/
├── fai-rag-architect.agent.md
└── fai-rag-architect/
    └── fai-context.json          ← context for the agent above
skills/
└── fai-play-initializer/
    ├── SKILL.md
    └── fai-context.json          ← context for this skill

7. Schemas

The FAI Protocol is formally defined by two JSON Schema files:

Both schemas use JSON Schema Draft-07 and are published at:

• https://frootai.dev/schemas/fai-manifest.schema.json
• https://frootai.dev/schemas/fai-context.schema.json

Manifests SHOULD include a $schema reference for editor validation:

{
  "$schema": "https://frootai.dev/schemas/fai-manifest.schema.json",
  "play": "01-enterprise-rag",
  "version": "1.0.0"
}

8. Reference Implementation

The FAI Engine at ../engine/ implements this specification as six cooperating modules:

8.1 Processing Pipeline

fai-manifest.json
       │
       ▼
┌──────────────┐     ┌──────────────────┐     ┌────────────────┐
│  Manifest    │────▶│  Context         │────▶│  Primitive     │
│  Reader      │     │  Resolver        │     │  Wirer         │
└──────────────┘     └──────────────────┘     └────────────────┘
                                                      │
                                                      ▼
                                              ┌────────────────┐
                                              │  Hook Runner   │
                                              │  (lifecycle)   │
                                              └────────────────┘
                                                      │
                                                      ▼
                                              ┌────────────────┐
                                              │  Evaluator     │
                                              │  (guardrails)  │
                                              └────────────────┘
                                                      │
                                                      ▼
                                              ┌────────────────┐
                                              │  MCP Bridge    │
                                              │  (tool export) │
                                              └────────────────┘

9. Conformance

9.1 Conformance Levels

9.2 Conformance Requirements

A conformant implementation MUST:

1. Parse — Read fai-manifest.json and validate it against fai-manifest.schema.json. Report all validation errors with field paths.
2. Resolve paths — Resolve every entry in primitives.agents, primitives.instructions, primitives.skills, primitives.hooks, and primitives.workflows to an existing file or directory. Report missing paths as errors.
3. Inject context — Make context.knowledge module content and context.waf pillar list available to all loaded primitives during execution.
4. Evaluate guardrails — After each agent response, evaluate the output against each declared guardrail threshold. A response with a score below the threshold MUST be flagged as a guardrail violation.
5. Report results — Produce a structured report indicating pass/fail for each guardrail metric, including the measured score and the threshold.

A conformant implementation SHOULD:

6. Merge context — When a loaded primitive has a sibling fai-context.json, merge its context with the play-level context following the precedence rules in §4.3.
7. Run hooks — Execute hook scripts at the lifecycle events declared in hooks.json.
8. Bridge to MCP — Expose wired primitives as MCP-compatible tools for external consumption.

9.3 Error Handling

10. Security Considerations

• Manifests MUST NOT contain secrets, API keys, or connection strings. Use environment variables or secret managers.
• Primitive paths MUST be confined to the play directory or the known catalog directories. Path traversal beyond the repository root MUST be rejected.
• Hook scripts execute with the permissions of the runtime process. Conformant engines SHOULD sandbox hook execution.
• Guardrail evaluation results SHOULD be logged for audit, but MUST NOT include PII from user queries.

11. Versioning

The FAI Protocol uses semantic versioning. The version field in the manifest refers to the play’s version, not the protocol version. The protocol version is identified by the $schema URI.

Breaking changes to the schema (removing required fields, changing field types) will increment the major protocol version. Additive changes (new optional fields) will increment the minor version.

12. Full Example

A complete fai-manifest.json for an enterprise RAG solution:

{
  "$schema": "https://frootai.dev/schemas/fai-manifest.schema.json",
  "play": "01-enterprise-rag",
  "version": "2.0.0",
  "context": {
    "knowledge": [
      "F1-GenAI-Foundations",
      "F2-LLMs",
      "R2-RAG-Architecture",
      "O4-Azure-AI-Services",
      "T3-Production-Patterns"
    ],
    "waf": [
      "security",
      "reliability",
      "cost-optimization",
      "performance-efficiency",
      "responsible-ai"
    ],
    "scope": "enterprise-rag-qa"
  },
  "primitives": {
    "agents": [
      "./agent.md",
      "./.github/agents/builder.agent.md",
      "./.github/agents/reviewer.agent.md",
      "./.github/agents/tuner.agent.md",
      "../../agents/fai-rag-architect.agent.md"
    ],
    "instructions": [
      "./.github/copilot-instructions.md",
      "./.github/instructions/rag-domain.instructions.md"
    ],
    "skills": [
      "./.github/skills/rag-indexer",
      "./.github/skills/rag-evaluator"
    ],
    "hooks": [
      "./.github/hooks/rag-guardrails"
    ],
    "workflows": [
      "./.github/workflows/rag-pipeline.yml"
    ],
    "guardrails": {
      "groundedness": 0.95,
      "coherence": 0.90,
      "relevance": 0.85,
      "safety": 0,
      "costPerQuery": 0.02
    }
  },
  "infrastructure": {
    "bicep": "./infra/main.bicep",
    "parameters": "./infra/main.bicepparam",
    "docker": "./docker-compose.yml"
  },
  "toolkit": {
    "devkit": "./.github",
    "tunekit": "./config",
    "speckit": "./spec"
  }
}

Appendix A: Relationship to Other Protocols

Appendix B: Primitive File Conventions

License

MIT — FrootAI Contributors

See LICENSE for the full license text.