FAI Agent Patterns Library

What Makes a Good Agent?

A great FAI agent is not just a system prompt in a Markdown file. It is a scoped persona with clear boundaries: what it knows, what tools it can touch, which WAF pillars it enforces, and which solution plays it belongs to. The best agents follow the principle of least privilege — a security reviewer should never have access to deployment tools, and a cost optimizer should not be able to modify infrastructure.

Every FAI agent declares its identity through YAML frontmatter. This metadata is what makes agents discoverable (search by WAF pillar), composable (wire into plays), and governable (restrict tool access). Without frontmatter, an agent is just a Markdown file. With it, the agent becomes a first-class citizen in the FAI Protocol.

Agent Frontmatter Schema

The YAML frontmatter at the top of every .agent.md file controls how the agent integrates with the ecosystem:

Complete Agent Definition

Here is a full agent file with every frontmatter field used. This agent is a RAG architecture specialist that participates in two solution plays and enforces three WAF pillars:

---
description: "RAG architecture expert — Azure AI Search + OpenAI"
name: FAI RAG Architect
model: gpt-4o
tools:
  - file_search
  - read_file
  - semantic_search
  - grep_search
waf:
  - security
  - reliability
  - cost-optimization
plays:
  - "01-enterprise-rag"
  - "03-multimodal-rag"
---

You are an expert RAG architect specializing in Azure AI.

## Core Principles
1. Always use hybrid search (vector + keyword) for recall
2. Apply semantic ranker for precision at query time
3. Use managed identity for all Azure service connections
4. Set max_tokens budgets per query tier:
   - Simple lookup: 500 tokens
   - Complex reasoning: 2,000 tokens
   - Multi-turn dialog: 4,000 tokens
5. Include citation grounding in every response

## Architecture Decisions
- Chunking: 512 tokens with 128-token overlap
- Embedding: text-embedding-3-large (3072 dimensions)
- Index: HNSW with efConstruction=400, efSearch=500
- Reranker: Azure AI Search semantic ranker (L2)

## Security Requirements
- DefaultAzureCredential for all SDK clients
- Key Vault references for connection strings
- Content safety filter on all LLM outputs
- PII redaction in logged queries

The Builder → Reviewer → Tuner Triad

Every FAI solution play uses a three-agent quality chain. This is the foundational pattern that separates FAI from standalone agent setups. Each role has distinct responsibilities, tool access, and evaluation criteria:

The chain is invoked explicitly via @builder, @reviewer, or @tuner in Copilot Chat, or automatically by the FAI Engine during play execution.

5 Agent Patterns

FAI agents follow one of five design patterns. Each pattern determines how the agent interacts with other agents, tools, and the user:

Pattern 1: Specialist

A specialist agent has deep knowledge in one domain — Kubernetes, RAG, Cosmos DB, security, etc. It does not delegate to other agents. It is invoked directly by the user or wired into a play. This is the most common pattern in FAI, used by 80% of the 238 agents in the ecosystem.

# fai-azure-cosmos-db-expert.agent.md
---
description: "Cosmos DB data modeling, partitioning, and query optimization"
model: gpt-4o
tools: [read_file, semantic_search, grep_search]
waf: [performance-efficiency, cost-optimization, reliability]
plays: ["08-real-time-analytics", "15-event-driven-processing"]
---
You are a Cosmos DB specialist. For every data model:
- Choose partition key based on query patterns (not entity ID)
- Set RU/s budgets per container with autoscale max
- Use change feed for event-driven downstream processing

Pattern 2: Supervisor

A supervisor agent routes tasks to specialist agents based on the user's request. It acts as a dispatcher — analyzing intent and delegating to the right expert. The fai-collective-orchestrator is the canonical example. Supervisors have broad tool access but narrow execution — they coordinate rather than implement.

# fai-collective-orchestrator.agent.md
---
description: "Routes tasks to specialist agents based on domain analysis"
model: gpt-4o
tools: [semantic_search, file_search, read_file]
waf: [operational-excellence]
---
You are the FAI orchestrator. Analyze the user request and delegate:
- Infrastructure questions → @fai-azure-infra-expert
- RAG design → @fai-rag-architect
- Security review → @fai-security-expert
- Cost analysis → @fai-cost-optimizer
Always explain your routing decision before delegating.

Pattern 3: Pipeline

Pipeline agents process work sequentially — the output of one agent becomes the input of the next. The Builder → Reviewer → Tuner chain is a pipeline. This pattern ensures separation of concerns: building, validation, and optimization happen in distinct steps with no circular dependencies.

Pattern 4: Debate

Two or more agents with opposing mandates review the same artifact. A cost agent might argue for gpt-4o-mini, while a quality agent pushes for gpt-4o. The user (or a supervisor) resolves the tension. This pattern surfaces trade-offs that a single agent would miss. Useful for architecture decision records (ADRs).

Pattern 5: Hybrid

A hybrid agent combines specialist knowledge with supervisor routing. It can handle straightforward requests directly and escalate complex ones. The fai-architect agent uses this pattern — it answers architecture questions directly but delegates implementation to builders.

Pattern Comparison

Tool Restrictions

The tools array in agent frontmatter acts as a whitelist. If omitted, the agent can use all available tools. When specified, the agent is restricted to only the listed tools. This is critical for security: a reviewer agent that can only read files cannot accidentally delete them.

# Security reviewer — read-only tools
tools:
  - read_file
  - grep_search
  - semantic_search
  # No create_file, no run_in_terminal → cannot modify code

# Builder — full write access
tools:
  - read_file
  - create_file
  - replace_string_in_file
  - run_in_terminal
  # Can modify files and run commands

# Tuner — config validation only
tools:
  - read_file
  - validate_config
  - run_evaluation
  # Cannot modify source code, only evaluate it

Model Selection Per Pattern

Different patterns benefit from different models. The modelfield in frontmatter is a hint — the actual model depends on availability and the FAI Engine's cost routing:

Agent Naming & Discovery

All agent files follow lowercase-hyphen naming: fai-{domain}.agent.md. The fai- prefix makes agents discoverable in Copilot Chat with @fai- autocomplete. The ecosystem currently has 238 agents organized by domain:

# Azure Services (40+ agents)
fai-azure-openai-expert.agent.md
fai-azure-ai-search-expert.agent.md
fai-azure-cosmos-db-expert.agent.md

# Architecture & Design (20+ agents)
fai-architect.agent.md
fai-api-gateway-designer.agent.md
fai-capacity-planner.agent.md

# Play Teams — Builder/Reviewer/Tuner (100 plays x 3)
fai-collective-implementer.agent.md
fai-collective-reviewer.agent.md
fai-collective-orchestrator.agent.md

# DevOps & Infrastructure
fai-cicd-pipeline-expert.agent.md
fai-azure-devops-expert.agent.md
fai-terraform-expert.agent.md

Wiring Agents into Solution Plays

In standalone mode, an agent works independently in your editor. In wired mode, the fai-manifest.json lists agents in the primitives.agents array. The FAI Engine then propagates shared context — knowledge modules, WAF pillars, and guardrail thresholds — to every listed agent automatically.

{
  "play": "01-enterprise-rag",
  "primitives": {
    "agents": [
      "fai-rag-architect",
      "fai-azure-ai-search-expert",
      "fai-azure-openai-expert",
      "fai-code-reviewer"
    ],
    "instructions": ["python-waf", "bicep-waf"],
    "skills": ["deploy-01-enterprise-rag"],
    "hooks": ["fai-secrets-scanner", "fai-cost-guardian"]
  }
}

When the FAI Engine loads this manifest, all four agents share the same knowledge context (F1, F2, R2, O4), enforce the same WAF pillars, and respect the same guardrail thresholds — without any duplication in their individual agent files.