FAI Quick Start
From zero to running FAI Engine in 5 minutes — install, validate, explore, build.
Prerequisites
Before starting, verify you have the required tools installed:
# Required: Node.js 18+ and npm
node --version # Expected: v18.x or higher
npm --version # Expected: 9.x or higher
# Required: VS Code with GitHub Copilot
code --version # Expected: 1.90+ recommended
# Optional: Azure CLI (for deployment steps)
az --version # Expected: 2.60+ if deployingIf any command fails, install the missing tool before continuing. Node.js 22 LTS is recommended for best compatibility with the FAI Engine.
Step 1: Install the MCP Server
The FAI MCP Server connects GitHub Copilot to the FrootAI knowledge base — 18 modules, 100 solution plays, 200+ glossary terms. Install it globally so it is available across all workspaces:
# Install the FAI MCP Server globally
npx frootai-mcp@latest
# Verify installation
npx frootai-mcp --versionExpected Output
frootai-mcp v5.0.1 — 45 tools registered, ready
Troubleshooting
If you get EACCES permission errors on macOS/Linux, use sudo npx frootai-mcp@latest or fix npm global permissions. On Windows, run the terminal as Administrator.
Step 2: Install the Essentials Plugin
The essentials plugin bundles the most-used agents, instructions, and skills into a single installable package. It sets up your .github/ directory with core primitives:
# Install the fai-essentials plugin
npx frootai install fai-essentials
# What gets created:
# .github/agents/fai-architect.agent.md
# .github/agents/fai-code-reviewer.agent.md
# .github/instructions/typescript-waf.instructions.md
# .github/instructions/python-waf.instructions.md
# .github/skills/fai-play-initializer/SKILL.md
# .github/copilot-instructions.mdExpected Output
✓ Installed fai-essentials (2 agents, 2 instructions, 1 skill)
Troubleshooting
If .github/ already exists, the installer merges non-conflicting files and skips existing ones. To force overwrite, use npx frootai install fai-essentials --force.
Step 3: Validate Primitives
Run the validator to confirm all installed primitives have correct frontmatter, naming conventions, and schema compliance:
# Validate all primitives in the workspace
npm run validate:primitives
# Or run directly
node scripts/validate-primitives.js --verboseExpected Output
Scanning primitives... ✓ 2 agents — all valid ✓ 2 instructions — all valid ✓ 1 skill — all valid ✓ 0 hooks — none found ✓ 0 errors, 0 warnings
Troubleshooting
Common errors: missing description in agent frontmatter (must be 10+ chars), incorrect file naming (must be lowercase-hyphen), skill folder name not matching name field in SKILL.md.
Step 4: Run FAI Engine on a Play
The FAI Engine reads a fai-manifest.json and resolves all referenced primitives, knowledge modules, WAF pillars, and guardrails. Test it against the built-in Enterprise RAG play:
# Load and verify Play 01 — Enterprise RAG
node engine/index.js \
solution-plays/01-enterprise-rag/fai-manifest.json \
--statusExpected Output
FAI Engine v2.x.x Loading: solution-plays/01-enterprise-rag/fai-manifest.json Play: 01-enterprise-rag Version: 1.0.0 Knowledge: R2 (RAG), O4 (Azure AI) WAF: security, reliability, cost-optimization Primitives: 3 agents, 2 instructions, 2 skills Guardrails: groundedness ≥ 0.8, safety ≥ 0.9 Status: ✓ All references resolved
Troubleshooting
If you see “unresolved reference” errors, the referenced primitive file may be missing. Run npm run validate:primitives first to identify gaps.
Step 5: Explore the Marketplace
Browse 77+ plugins, search the knowledge base, and discover solution plays:
# List all available plugins
npx frootai list
# Search for RAG-related resources
npx frootai search "RAG architecture"
# Install a specific plugin
npx frootai install enterprise-rag
# View play details
npx frootai play 01 --detailsExpected Output (list)
FAI Marketplace — 77 plugins available enterprise-rag RAG with Azure AI Search + OpenAI smart-chatbot Multi-turn conversational AI document-processor Invoice and form extraction ... Use: npx frootai install <name>
What's Next?
You now have the FAI ecosystem running locally. Here are the recommended next steps:
Follow the End-to-End Workshop (L15) to create a complete solution play from scratch — manifest, primitives, deployment, evaluation.
Read the Primitive Primer (L1) to understand agents, instructions, skills, hooks, and how they wire together.
See the Configuration Guide (L4) to set up openai.json, guardrails.json, and model parameters for your use case.
Open Copilot Chat and ask questions — the 25 MCP tools give Copilot direct access to the FrootAI knowledge base.
Quick Reference
| Command | Purpose |
|---|---|
| npx frootai-mcp@latest | Install/update MCP Server |
| npx frootai install <plugin> | Install a marketplace plugin |
| npm run validate:primitives | Validate all primitives in workspace |
| node engine/index.js <manifest> --status | Load and verify a solution play |
| npx frootai list | Browse marketplace plugins |
| npx frootai search <query> | Search knowledge base |
Project Structure After Setup
After completing all 5 steps, your workspace will have this structure:
your-project/
├── .github/
│ ├── agents/
│ │ ├── fai-architect.agent.md
│ │ └── fai-code-reviewer.agent.md
│ ├── instructions/
│ │ ├── typescript-waf.instructions.md
│ │ └── python-waf.instructions.md
│ ├── skills/
│ │ └── fai-play-initializer/
│ │ └── SKILL.md
│ └── copilot-instructions.md
├── config/
│ ├── openai.json
│ └── guardrails.json
└── solution-plays/
└── 01-enterprise-rag/
└── fai-manifest.jsonThe .github/ directory holds all primitives recognized by GitHub Copilot. The config/ directory holds TuneKit runtime configuration. Solution plays reference both through the manifest.
Common Pitfalls
The FAI Engine requires Node.js 18+. If you see syntax errors on startup, check node --version. Recommend v22 LTS.
Primitives must live under .github/ for Copilot to detect them. If agents aren't appearing in chat, check the directory path.
Agent description must be 10+ characters. File names must be lowercase-hyphen. WAF values must be from the 6-pillar set.
Restart VS Code after installing the MCP server. Check the Output panel → GitHub Copilot for connection logs. Ensure no firewall blocks localhost stdio.