FrootAI User Guide

The complete guide to using FrootAI — from first install to production deployment.

1. Getting Started

Step 1: Install the VS Code Extension

bashcode --install-extension frootai.frootai-vscode

Or search "FrootAI" in the VS Code Extensions Marketplace.

Step 2: Browse the Knowledge Hub

Open the sidebar → FROOT Modules panel to explore 16 knowledge modules across 5 layers:

Step 3: Init DevKit

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → FROOT: Init DevKit

This scaffolds the .github/ Agentic OS into your project:

• agent.md — Agent behavior rules
• copilot-instructions.md — Copilot context
• Prompt files, CI workflows, and config templates

Step 4: Init TuneKit

Command Palette → FROOT: Init TuneKit

Adds tunable configuration files:

• config/agents.json — Agent routing and parameters
• config/model-comparison.json — Model selection criteria
• config/guardrails.json — Safety and content limits
• evaluation/ — Golden sets and scoring scripts

Step 5: Deploy

Command Palette → FROOT: Deploy Solution

Packages your configured play for deployment. Output depends on the selected solution play.

2. Using the VS Code Extension

2.1 All Commands

Open Command Palette and type FROOT: to see all available commands:

2.2 Sidebar Panels

The FrootAI sidebar (click the 🌱 icon) has these panels:

1. FROOT Modules — Expandable tree of all 16 knowledge modules, color-coded by layer
2. Solution Plays — All 20 plays with status badges (Ready / In Progress)
3. MCP Tools — Documentation for all 16 MCP server tools, grouped by type
4. Quick Actions — One-click access to common commands

2.3 Standalone Mode

The extension works offline with bundled knowledge. It caches downloaded content in globalStorage with a 24-hour TTL. No internet required for core functionality.

3. Using the MCP Server

3.1 What is the MCP Server?

The FrootAI MCP Server exposes 23 tools that any MCP-compatible AI agent can call. It adds AI architecture knowledge to your agent's capabilities.

3.2 Setup

Add to your .vscode/mcp.json:

json{
  "servers": {
    "frootai": {
      "command": "npx",
      "args": ["frootai-mcp"]
    }
  }
}

3.3 Tool Reference

Static Tools (bundled knowledge)

Live Tools (real-time retrieval)

Chain Tools (multi-step workflows)

AI Ecosystem Tools

3.4 Using in Copilot Chat

In VS Code with GitHub Copilot, you can invoke MCP tools naturally:

@workspace Use frootai to search for "semantic kernel orchestration"
@workspace Use frootai to get the RAG Architecture module
@workspace Use frootai agent_build to create an IT ticket agent

4. Solution Plays

4.1 What is a Solution Play?

A solution play is a pre-configured scenario accelerator. Each play includes:

• README.md — Overview, architecture, deployment steps
• DevKit (.github/ Agentic OS) — Agent rules, copilot instructions, prompts, CI
• TuneKit (config/ + evaluation/) — Tunable parameters and quality benchmarks

4.2 Available Plays (20)

4.3 Choosing a Play

Use the Solution Configurator at /configurator — answer 3 questions and get a recommendation. Or use the AI Assistant at /chatbot.

4.4 Customizing a Play

1. FROOT: Init DevKit to scaffold the play's .github files
2. Edit agent.md to adjust behavior rules
3. FROOT: Init TuneKit to add config parameters
4. Tune config/agents.json for your scenario
5. Run evaluation against the golden set

5. DevKit Deep Dive

The DevKit scaffolds .github Agentic OS — a structured set of files that make your project agent-ready.

5.1 File Reference

5.2 The 7 Primitives

The Agentic OS uses 7 composable primitives:

1. Agent Rules (agent.md) — Behavioral boundaries
2. Context (copilot-instructions.md) — Project knowledge
3. Prompts (prompts/*.prompt.md) — Reusable prompt templates
4. Workflows (workflows/*.yml) — CI/CD automation
5. Templates (ISSUE_TEMPLATE/, pull_request_template.md) — Structured collaboration
6. Config (config/) — Tunable parameters
7. Evaluation (evaluation/) — Quality benchmarks

6. TuneKit Deep Dive

6.1 Config Files

6.2 Tuning Workflow

1. Review current config: FROOT: Show Config
2. Adjust parameters based on your scenario
3. Run evaluation: python evaluation/evaluate.py
4. Compare scores against the golden set
5. Iterate until quality targets are met

6.3 Evaluation

Each play includes:

• evaluation/golden-set.jsonl — Expected inputs/outputs (5+ examples)
• evaluation/evaluate.py — Scoring script (accuracy, latency, safety)
• Results output to evaluation/results.json

6b. SpecKit Deep Dive

SpecKit provides architecture specifications and WAF (Well-Architected Framework) alignment for every solution play.

What's in SpecKit?

WAF Alignment (6 Pillars)

Every play is scored across the Azure Well-Architected Framework:

CLI WAF Scorecard

bashnpx frootai validate --waf

Runs 17 checks across 6 pillars and shows per-pillar scores + failing items.

6c. Using the CLI

The FrootAI CLI (npx frootai) provides 8 commands for terminal-based workflows.

Commands

Scaffold Command

One-command play scaffolding — creates all 5 FROOT kits + froot.json manifest:

bashnpx frootai scaffold 01-enterprise-rag
# or shorthand:
npx frootai scaffold play-01

Creates: .github/agents/, config/, spec/, evaluation/, froot.json, WAF instructions. Auto-detects existing projects and merges files alongside yours.

6d. Using Docker

Run the FrootAI MCP Server as a container — no Node.js required.

Quick Start

bashdocker run -i --rm ghcr.io/frootai/frootai-mcp:latest

Client Configuration

Claude Desktop / Cursor:

json{
  "mcpServers": {
    "frootai": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/frootai/frootai-mcp:latest"]
    }
  }
}

VS Code Copilot (.vscode/mcp.json):

json{
  "servers": {
    "frootai": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/frootai/frootai-mcp:latest"],
      "type": "stdio"
    }
  }
}

Multi-arch (amd64 + arm64). Same 23 tools, 682KB knowledge. Pinnable versions.

6e. Using the REST API

The FrootAI REST API provides 5 HTTP endpoints — no SDK or MCP client needed.

Base URL

https://frootai-chatbot-api.azurewebsites.net

Endpoints

Rate Limits

60 requests/minute per IP. Sliding window. Returns HTTP 429 when exceeded.

7. Agent Chain

The build → review → tune chain is a three-step workflow:

Step 1: Build (agent_build)

Generate a new agent scaffold based on your scenario description. Produces agent.md, config files, and evaluation templates.

Step 2: Review (agent_review)

Analyze the generated agent for:

• Security gaps
• Missing error handling
• Unclear scope boundaries
• Config completeness

Step 3: Tune (agent_tune)

Optimize parameters based on review findings and evaluation results. Adjusts temperature, model selection, guardrails, and routing.

Deploying a Solution Play

Deploy any play with one command:

bash# Deploy play 01 (Enterprise RAG)
./scripts/deploy-play.sh 01 --resource-group rg-frootai-dev

# Deploy play 05 (IT Ticket Resolution) without evaluation
./scripts/deploy-play.sh 05 --resource-group rg-frootai --skip-eval

The script: validates the play structure → deploys Azure infra via Bicep → copies config files → runs evaluation.

Exporting FROOT Knowledge as Copilot Skills

Make any FROOT module available as a GitHub Copilot skill:

bash# Export a single module
./scripts/export-skills.sh F1

# Export all 16 modules
./scripts/export-skills.sh --all

This creates .github/skills/<module-id>/SKILL.md + README.md that Copilot reads automatically.

Knowledge Auto-Update

The MCP server can auto-refresh its knowledge:

• Bundled knowledge.json is checked every 7 days
• If stale, fetches latest from GitHub automatically
• Falls back to bundled version if offline

To manually rebuild: ./scripts/rebuild-knowledge.sh

8. FAQ

Q: Does FrootAI require an internet connection? A: Core functionality works offline. The VS Code extension bundles knowledge locally. Live tools (fetch_azure_docs, fetch_external_mcp) require connectivity.

Q: Which AI models does FrootAI support? A: FrootAI is model-agnostic. Solution plays can be configured for any model in config/agents.json. The knowledge modules cover GPT-4o, Claude, Gemini, Phi, Llama, and more.

Q: Can I use FrootAI without VS Code? A: Yes. The MCP server works with any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Azure AI Foundry). The website is accessible via browser.

Q: How do I add a custom solution play? A: See the Contributor Guide for step-by-step instructions.

Q: Is FrootAI free? A: Yes. FrootAI is 100% open source under the MIT license.

Q: How do I report a bug? A: Open an issue on GitHub using the bug report template.

Q: How often is the knowledge base updated? A: Knowledge modules are updated with each release. The changelog tracks all content changes.

Next: Admin Guide · Contributor Guide · API Reference