What you’ll get (artifacts shown in this guide)

• A consistent extension folder layout you can copy into a project-level .specify/extensions/ directory for local testing. (If your environment uses a different extension directory, replace .specify accordingly.)
• Full extension.yml manifest.
• A slash command file: addon/commands/speckit.extn.myfeature.md.
• A lifecycle hook descriptor: addon/hooks/after-plan.yml and platform run wrappers.
• A small C# console app (MyFeatureRunner) that reads a spec path and writes structured JSON to stdout.
• Install scripts (install.sh, install.ps1) and OS wrappers (run.sh/run.ps1) to select the right binary.
• A GitHub Actions workflow that builds platform binaries and packages a ZIP for publishing.
• Tests (xUnit) that exercise the analyzer logic (no Python anywhere).

Step 0 — conventions & a note on paths

• I’ll use “Spec Kit” consistently here and show the local extension install path as .specify/extensions/ (this is the common convention in community examples). If your tooling uses a different folder, replace .specify accordingly.
• Slash command namespace convention: /speckit.extn..* — follow this for discoverability.
• Hooks use placeholders like {{spec.path}}; confirm your Spec Kit version’s exact interpolation tokens and adapt if necessary.

Step 1 — pick scope and design
Decide the minimal valuable feature for your first release. Example here:

• Add a slash command /speckit.extn.myfeature that runs an analysis on the current spec and returns structured JSON with a summary and issues. Also register an after-plan lifecycle hook that runs the same analyzer automatically when planning completes.

Define:

• Inputs: spec path (string), format (json|text), output path (optional).
• Outputs: structured JSON (summary, issues[]), exit codes.
• Failure modes: missing spec, parse errors, internal errors — map to clear exit codes and clear stderr messages.

Design outcome: a C# console app MyFeatureRunner that accepts –spec and writes JSON to stdout or an output file. Hooks call the executable with placeholders.

Step 2 — folder layout (concrete)
Create this structure (top-level folder is the extension package root):

com.yourorg.myfeature/
extension.yml
README.md
addon/
commands/
speckit.extn.myfeature.md
hooks/
after-plan.yml
templates/
mytemplate.txt
bin/
linux/
MyFeatureRunner <– published single-file linux binary
macos/
MyFeatureRunner <– published macos binary
windows/
MyFeatureRunner.exe <– published windows exe
run.sh <– wrapper selecting right binary on Unix
run.ps1 <– wrapper for Windows
src/
MyFeatureRunner/ <– dotnet project (Program.cs, Analyzer.cs, MyFeatureRunner.csproj)
tests/
MyFeatureRunner.Tests/ <– xUnit tests
examples/
sample-spec.md
install.sh
install.ps1

Notes:

• Place platform-specific published binaries under addon/bin//. Include wrapper scripts (run.sh, run.ps1) that forward args to the right binary.
• The extension.yml manifest (next) will map addon/ directories into the install target.

Step 3 — extension manifest (full example)
Put this file at the extension root as extension.yml:

name: com.yourorg.myfeature
version: 0.1.0
description: “Adds /speckit.extn.myfeature — analyzes a spec and returns structured JSON with issues.”
authors:

• name: Your Name
  email: you@example.com
  license: MIT
  tags:
• spec-analysis
• speckit
  install:
  files:
  • src: addon/commands/
    dest: commands/
  • src: addon/hooks/
    dest: hooks/
  • src: addon/templates/
    dest: templates/
  • src: addon/bin/
    dest: bin/
    hooks:
• name: after-plan
  file: addon/hooks/after-plan.yml

Explanation:

• install.files tells the Spec Kit installer how to copy files into the runtime extension directory. Keep the paths relative to the extension archive root.
• hooks are entry points to a hook descriptor file (next).

Step 4 — slash command file (full example)
File: addon/commands/speckit.extn.myfeature.md

Description: Analyze the given Spec file for structural issues and return a JSON report with “summary” and “issues”.
Inputs:

• spec-path: path to the spec file. Defaults to the current spec in the workspace if omitted.
• format: “json” (default) or “text”.
• output: optional path to write the JSON report.

Outputs:

• result (JSON):
  {
  “summary”: “string”,
  “issues”: [
  {
  “line”: 12,
  “severity”: “warning”,
  “ruleId”: “SP-001”,
  “message”: “Example issue message”
  }
  ]
  }

Examples:

• /speckit.extn.myfeature spec-path=specs/login.spec format=json
• /speckit.extn.myfeature format=text

Behavior:

• When invoked, the agent will run the extension’s hook or run wrapper that calls the C# CLI with –spec . The CLI emits structured JSON to stdout. The agent should present JSON results or a text summary as requested.

Notes:

• Keep examples explicit and provide the JSON schema so integrators know how to parse the result.

Step 5 — hook descriptor (full example)
File: addon/hooks/after-plan.yml

hook: after-plan
run: ./bin/run.sh
args:

• –spec
• “{{spec.path}}”
• –output
• “{{workspace}}/.specify/extensions/com.yourorg.myfeature/latest-report.json”
  env:
  LOG_LEVEL: info

Notes:

• run points to the wrapper script in addon/bin/ that selects the correct binary for the host OS. This simplifies cross-platform support.
• args include placeholders. Confirm the exact placeholder names in your Spec Kit version; many installations support {{spec.path}} and {{workspace}} or similar fields.

Step 6 — C# helper (full source example)
We’ll implement a small console app that performs simple analysis: counts characters and looks for TODO comments as “issues”. It’s intentionally simple but structured to be extended.

Project: src/MyFeatureRunner/MyFeatureRunner.csproj Exe net8.0 enable enable

Program.cs (src/MyFeatureRunner/Program.cs)

using System.Text.Json;
using System.Text.Json.Serialization;

public static class Program
{
  public static int Main(string[] args)
  {
    var parsed = CliArgs.Parse(args);
    if (!parsed.IsValid)
    {
      Console.Error.WriteLine(parsed.ErrorMessage);
      return parsed.ExitCode;
    }

    try
    {
        var report = Analyzer.AnalyzeFile(parsed.SpecPath);
        var options = new JsonSerializerOptions { WriteIndented = true };
        string json = JsonSerializer.Serialize(report, options);

        if (!string.IsNullOrEmpty(parsed.Output))
        {
            File.WriteAllText(parsed.Output, json);
            Console.WriteLine($"Report written to {parsed.Output}");
        }
        else
        {
            Console.WriteLine(json);
        }

        return 0;
    }
    catch (FileNotFoundException ex)
    {
        Console.Error.WriteLine(ex.Message);
        return 3;
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"Internal error: {ex.Message}");
        return 10;
    }
}
}

CliArgs helper (embedded in same file or separate file for clarity):

internal sealed class CliArgs
{
public string SpecPath { get; init; } = string.Empty;
public string Output { get; init; } = string.Empty;
public bool IsValid { get; init; }
public string ErrorMessage { get; init; } = string.Empty;
public int ExitCode { get; init; }
public static CliArgs Parse(string[] args)
{
    if (args.Length == 0)
        return new CliArgs { IsValid = false, ErrorMessage = "Usage: MyFeatureRunner --spec <path> [--output <path>]", ExitCode = 2 };

    var dict = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
    for (int i = 0; i < args.Length; i++)
    {
        if (args[i].StartsWith("--") && i + 1 < args.Length)
        {
            dict[args[i]] = args[i + 1];
            i++;
        }
    }

    if (!dict.TryGetValue("--spec", out var spec) || string.IsNullOrWhiteSpace(spec))
        return new CliArgs { IsValid = false, ErrorMessage = "Missing required --spec <path>", ExitCode = 2 };

    dict.TryGetValue("--output", out var output);

    return new CliArgs { IsValid = true, SpecPath = spec!, Output = output ?? string.Empty };
}
}

Analyzer (src/MyFeatureRunner/Analyzer.cs)

using System.Text.Json.Serialization;

public static class Analyzer
{
  public static AnalysisReport AnalyzeFile(string path)
  {
  if (!File.Exists(path))
    throw new FileNotFoundException($"Spec not found: {path}", path); 
   var text = File.ReadAllText(path);
    var lines = text.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries);

    var issues = new List<Issue>();
    for (int i = 0; i < lines.Length; i++)
    {
        var line = lines[i];
        if (line.Contains("TODO", StringComparison.OrdinalIgnoreCase))
        {
            issues.Add(new Issue
            {
                Line = i + 1,
                Severity = "warning",
                RuleId = "SP-001",
                Message = "Found TODO in spec; consider clarifying acceptance criteria."
            });
        }
    }

    return new AnalysisReport
    {
        Summary = $"Spec has {text.Length} chars, {lines.Length} non-empty lines, {issues.Count} issues.",
        Issues = issues
    };
}
}

public class AnalysisReport
{
[JsonPropertyName("summary")]
public string Summary { get; set; } = string.Empty;
[JsonPropertyName("issues")]
public List<Issue> Issues { get; set; } = new();
}

public class Issue
{
[JsonPropertyName("line")]
public int Line { get; set; }
[JsonPropertyName("severity")]
public string Severity { get; set; } = string.Empty;
[JsonPropertyName("ruleId")]
public string RuleId { get; set; } = string.Empty;
[JsonPropertyName("message")]
public string Message { get; set; } = string.Empty;
}

Design notes:

• Analyzer.AnalyzeFile is pure and easily testable. Keep the CLI thin.
• Exit codes:
  • 0 success
  • 2 argument error / usage
  • 3 not found (spec path)
  • 10 internal error

Step 7 — unit tests (xUnit)
Create src/MyFeatureRunner.Tests/MyFeatureRunner.Tests.csproj and a simple test that calls Analyzer directly (no process spawning), ensuring repeatable logic.

Sample test (src/MyFeatureRunner.Tests/AnalyzerTests.cs)

using Xunit;
using System.IO;
using System.Text.Json;

public class AnalyzerTests
{
  [Fact]
  public void AnalyzeFile_ReturnsIssuesForTODO()
  {
    var tmp = Path.GetTempFileName();
    File.WriteAllText(tmp, "Line one\nTODO: add acceptance\nAnother line\n");
    var report = Analyzer.AnalyzeFile(tmp);
    Assert.Contains("Spec has", report.Summary);
    Assert.Single(report.Issues);
    Assert.Equal("SP-001", report.Issues[0].RuleId);
  }
}

Step 8 — run wrappers and permissions
Create addon/bin/run.sh (Unix wrapper):

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
PLATFORM_BIN=""
if [[ "$(uname -s)" == "Linux" ]]; then
PLATFORM_BIN="$ROOT/linux/MyFeatureRunner"
elif [[ "$(uname -s)" == "Darwin" ]]; then
PLATFORM_BIN="$ROOT/macos/MyFeatureRunner"
else
PLATFORM_BIN="$ROOT/windows/MyFeatureRunner.exe"
fi
exec "$PLATFORM_BIN" "$@"

Make it executable: chmod +x addon/bin/run.sh.

Windows wrapper addon/bin/run.ps1 (PowerShell):

param([Parameter(ValueFromRemainingArguments=$true)]$Args)
$root = Split-Path -Parent $MyInvocation.MyCommand.Path
$os = (Get-CimInstance -ClassName Win32_OperatingSystem).Caption
$exe = Join-Path $root "windows\MyFeatureRunner.exe"
& $exe @Args

Step 9 — installer scripts

install.sh:
#!/usr/bin/env bash
set -euo pipefail
EXT_ID="com.yourorg.myfeature"
DEST=".specify/extensions/$EXT_ID"
mkdir -p "$DEST"
cp -r addon "$DEST/"
cp extension.yml "$DEST/"
cp README.md "$DEST/"
echo "Installed extension to $DEST"

install.ps1 (PowerShell):
param([string]$Dest = ".specify/extensions/com.yourorg.myfeature")
New-Item -ItemType Directory -Force -Path $Dest | Out-Null
Copy-Item -Path "addon*" -Destination $Dest -Recurse -Force
Copy-Item -Path "extension.yml" -Destination $Dest -Force
Copy-Item -Path "README.md" -Destination $Dest -Force
Write-Host "Installed extension to $Dest"

Step 10 — test locally (step-by-step)

1. In a Spec Kit project:
   mkdir -p .specify/extensions
   cp -r com.yourorg.myfeature .specify/extensions/
2. Confirm files:
   ls .specify/extensions/com.yourorg.myfeature
3. Run the analyzer directly:
   dotnet run –project src/MyFeatureRunner — –spec examples/sample-spec.md Expected JSON printed or “Report written to ” if –output provided.
4. Trigger the after-plan hook via your normal Spec Kit flow (specify → plan) and confirm:
   • Hook runs and writes latest-report.json in the extension folder (or check STDOUT in logs).
   • If hook failed, inspect agent logs or the extension’s stderr captured by the CLI.

Step 11 — publishing & packaging with CI (GitHub Actions)
A sample workflow .github/workflows/publish.yml that:

• Builds and publishes single-file binaries for multiple runtimes
• Packages the extension folder into a zip
• Uploads the zip as an artifact (or creates a release)

Sample YAML (abridged for clarity):

name: Build and Package Extension
on:
push:
tags:
- 'v*..'
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
runtime: [linux-x64, linux-arm64, osx-arm64, win-x64]
steps:
- uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v3
with:
dotnet-version: '8.0.x'
- name: Publish ${{ matrix.runtime }}
run: |
dotnet publish src/MyFeatureRunner -c Release -r ${{ matrix.runtime }}
-p:PublishSingleFile=true -p:PublishTrimmed=true -o ./addon/bin/${{ matrix.runtime }}
- name: Organize binaries
run: |
# move to the platform folder expected by the extension, e.g. linux->linux, osx->macos, win->windows
mkdir -p addon/bin/linux addon/bin/macos addon/bin/windows
if [[ "${{ matrix.runtime }}" == linux* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner ./addon/bin/linux/MyFeatureRunner; fi
if [[ "${{ matrix.runtime }}" == osx* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner ./addon/bin/macos/MyFeatureRunner; fi
if [[ "${{ matrix.runtime }}" == win* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner.exe ./addon/bin/windows/MyFeatureRunner.exe; fi
- name: Zip extension
if: ${{ matrix.runtime == 'linux-x64' }}
run: |
zip -r com.yourorg.myfeature-${{ github.ref_name }}.zip extension.yml addon README.md
- name: Upload package
uses: actions/upload-artifact@v4
with:
name: extension-zip
path: com.yourorg.myfeature-${{ github.ref_name }}.zip

Notes:

• This workflow demonstrates building multiple runtimes and packaging into a zip during the linux-x64 job; you can centralize packaging in a separate job that depends on build artifacts.
• For production, consider signing artifacts and publishing to GitHub Releases or a private artifact store.

Step 12 — catalog entry & checksum
Create a catalog JSON entry referencing the ZIP URL and a checksum.

Example catalog entry:

{
"id": "com.yourorg.myfeature",
"name": "My Feature",
"version": "0.1.0",
"url": "https://example.com/com.yourorg.myfeature-0.1.0.zip",
"checksum": "sha256:abcdef123456..."
}

Generate a checksum:

• Unix: sha256sum com.yourorg.myfeature-0.1.0.zip | awk ‘{print $1}’
• PowerShell: (Get-FileHash .\com.yourorg.myfeature-0.1.0.zip -Algorithm SHA256).Hash

Step 13 — troubleshooting and debugging checklist

• Hook not executed:
  • Confirm extension.yml lists the hook and was installed to .specify/extensions//.
  • Confirm hook file path is correct and marked executable if it’s a script.
• Binary fails on host:
  • Ensure correct platform binary published or require dotnet runtime and use wrapper scripts to run dotnet MyFeatureRunner.dll.
  • Check file permissions: chmod +x on Unix binaries.
• Placeholder expansion:
  • Verify your Spec Kit installation supports placeholders like {{spec.path}}; consult your Spec Kit version docs and update hook args.
• Inspect logs:
  • Check Spec Kit or agent logs; hooks often have stdout/stderr captured — look for error messages and exit codes.
• Test locally:
  • Run the wrapper or the CLI directly with the same args the hook would send to reproduce failures.

Security & governance checklist

• Do not embed secrets inside the extension. Use environment variables or configuration files that the consumer supplies.
• Document any network calls or telemetry the extension performs.
• Prefer offline, deterministic tools; minimize external dependencies.
• Provide checksums and consider signing releases for consumers to verify integrity.
• Encourage consumers to review source before installing; keep the extension small and source-available.

Best practices & gotchas

• Use JSON for structured output; it’s easier for agents and hooks to parse than free text.
• Keep the CLI deterministic and non-interactive. Hooks execute noninteractively — no prompts.
• If you can’t ship native executables for all platforms, ship a single DLL and small launcher scripts that call dotnet MyRunner.dll; document runtime requirements.
• Consider a self-test command or endpoint (e.g., /speckit.extn.myfeature.selftest) that the user can run after install to verify everything works.

Complete end-to-end checklist (before publishing)

• extension.yml exists and maps files correctly.
• addon/commands contains command files with examples and output schema.
• addon/hooks reference run wrappers and include correct placeholders.
• addon/bin contains published artifacts for supported OSes or a DLL + run wrappers.
• README documents requirements, install, usage, and troubleshooting.
• install scripts work for Unix and Windows for local testing.
• Example spec exists and tests validate analyzer logic.
• CI builds and packages artifacts and uploads ZIP to release/host.
• Catalog entry (if publishing) includes correct URL and checksum.

Note: The initial draft of this post (and all the code) was written by BlogWriter and then
edited by Jesse Liberty. Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

• A preset is a versioned package that supplies template files, CLI prompts/companion prompt text, small scripts, and tiny content changes (terminology, defaults, localization). Presets are layered at runtime; when Spec Kit resolves a template or prompt, it walks the stack, and the highest-priority “winning” file is used.
• Presets are intended for content/style/localization changes. Avoid heavy runtime logic—use Bundles or Extensions if you need stateful automation.

Step 1—design: decide scope, naming, and conventions

• Pick exactly what you will override:
  • templates/—spec, plan, or task templates (Markdown).
  • commands/—CLI command prompt text or companion .prompt.md files visible to users.
  • scripts/—shell/PowerShell scripts used by templates or lifecycle hooks.
  • small localized wording changes, default values, or doc snippets.
• Keep presets focused. One preset should do one job (branding, Spanish localization, trimmed plan structure, etc.).
• Choose an ID, version, and a default priority. Example: id = com.example.my-company-style, version = 0.1.0, priority = 8. Lower priority number = higher precedence (default is 10).
• Record author name/email and a short description in the manifest. These fields help consumers and catalogs list and audit presets.

Step 2—create the folder structure and the manifest

• Create a folder for the preset. Example:
  my-company-style/
• At the root, create a manifest file named preset.yml and add subfolders for overrides:
  • templates/
  • commands/
  • scripts/
  • README.md

Minimal example preset.yml (place at my-company-style/preset.yml)
name: my-company-style
id: com.example.my-company-style
version: 0.1.0
description: “Company wording, trimmed plan structure, and Spanish localization.”
author:
name: Example Corp
email: infra@example.com
priority: 8
tags:

• style
• localization

Notes about the manifest:

• Spec Kit reads preset.yml to register the preset.
• The important required fields are id, name, and version; add description, author, priority, and tags for usability.
• You can extend the manifest with catalog metadata if you plan to publish.

Step 3—place overrides in the correct locations

• templates/: copy the exact core template filename you want to override (for example, plan-template.md) and edit it. The runtime resolution uses filenames/paths to match.
• commands/: put files that replace command prompt text or companion prompts. For example, speckit.constitution.md or .prompt.md files.
• scripts/: put helper scripts referenced by templates or lifecycle hooks.
• README.md: explain what the preset does, installation implications, and any migration guidance.

Important: keep the same filenames and relative paths used by the core Spec Kit repository (you can inspect core templates in the Spec Kit repo to find correct names). During installation, preset files are copied to .specify/presets// and spec resolution walks the stack automatically, so you don’t manually merge templates.

Example: override the plan template to add a C# code sample

• Create templates/plan-template.md and include a fenced C# block in the example section: …in the template’s code example area include: // Example using our company logging convention public class AccountService { private readonly ILogger _log; public AccountService(ILogger log) => _log = log; }

(Templates are plain Markdown — using C# samples inside them is fine.)

Step 4 — local testing during development (fast feedback loop)

• Install your preset into a local project while developing:
  specify preset add –dev /path/to/my-company-style
• Run generation commands that exercise the templates or prompts you modified:
  specify plan –input spec=”Add user login”
• Inspect the generated output to verify your overrides took effect.
• Use Spec Kit helper commands to debug resolution:
  specify preset resolve
  specify artifact (or whichever command your Spec Kit provides to inspect which file “wins”)
• Iterate: change files in your local preset directory and re-run the generation command. The –dev install mode points to your local copy for quick iteration.

Step 5—validate the manifest (quick programmatic check)

• A simple validation ensures required fields are present and helps catch YAML typos. Below is a tiny C# example using YamlDotNet that reads preset.yml and errors if id/name/version are missing.

Commands:

• Add the YamlDotNet package (run in your dotnet project directory):
  dotnet add package YamlDotNet

C# Program (Program.cs):

using System;
using System.IO;
using System.Collections.Generic;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

var yaml = File.ReadAllText("preset.yml");
var deserializer = new DeserializerBuilder()
.WithNamingConvention(CamelCaseNamingConvention.Instance)
.Build();
var preset = deserializer.Deserialize<Dictionary<string, object>>(yaml);

string[] required = new[] { "id", "name", "version" };
foreach (var r in required)
{
  if (!preset.ContainsKey(r))
  {
    Console.Error.WriteLine($"Missing required manifest field: {r}");
    Environment.Exit(2);
  }
}
Console.WriteLine($"Preset OK: {preset["name"]} v{preset["version"]}");

• dotnet run (or dotnet build + dotnet run) in the project containing Program.cs and preset.yml.
• Exit codes: 0 for OK, non-zero for missing required fields. Integrate this into CI to fail fast on manifest mistakes.

Step 6—tests and CI

• Unit or integration tests: create tests that run specify commands in a controlled workspace (temp directory), generate artifacts, and assert expected strings or structural pieces exist.
• Snapshot testing: store small canonical generated files in tests and compare outputs after generation.
• Linting: run your YAML validator and any custom checks (e.g., disallow certain words, ensure semantic versioning).
• CI: run the validation and generation tests for pull requests. If your preset includes scripts, run them in CI to ensure cross-platform behavior or provide both shell and PowerShell variants.

Step 7—package and publish

• Options for sharing:
  • Publish the preset repository on GitHub/GitLab and reference it from a catalog.
  • Host a catalog.json or catalog.yaml listing your preset metadata and URL. Consumers can add presets from catalogs.
  • Use community tooling (e.g., presetify) to generate catalog entries and help with validation/publishing to community catalogs.
• For internal distribution, your team can host the preset repo or a catalog on an internal server and point projects at it.
• Ensure you tag releases using semantic versioning so consumers can pin versions: e.g., v0.1.0.

Step 8—installation and lifecycle for consumers

• Install from a catalog or URL:
  specify preset add
  specify preset add –version
  specify preset add –from
• Install locally for development:
  specify preset add –dev <path/to/preset>
• Remove:
  specify preset remove
• Upgrading a preset is a matter of updating the version and having consumers run an upgrade or specify preset add with a version.

Best practices & warnings

• Keep presets limited to content/formatting/localization. Don’t use presets to implement complex runtime automation.
• Follow semantic versioning. Document changes in README and changelog.
• Prefer small, focused presets over large monolithic presets; it’s easier to compose and upgrade.
• Security: don’t blindly trust third-party catalogs. Inspect preset contents before install and ensure your project policy permits external presets.
• Avoid breaking template API contracts. If you change placeholders or required variables in a template, document the change and bump major version.
• Use meaningful tags in preset.yml so consumers (and catalog tools) can filter presets: tags: [style, spanish, onboarding]
• Provide README.md with examples: “How this preset changes plan-template.md” and sample generated output.
• If you want to supply per-command prompts, include companion .prompt.md files under commands/ with clear naming.

Note: The initial draft of this post was written by BlogWriter and then
edited by Jesse Liberty. Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

Spec Kit exposes four primitives that solve these problems in a structured, maintainable way:

• Presets fix content and wording (make docs consistent).
• Extensions add behavior and integrations (run code, call Jira/CI).
• Workflows orchestrate multi-step, resumable pipelines (add gates and state).
• Bundles package and version a curated set of the above (one-command onboarding).

This post explains each primitive plainly, shows concrete manifests and examples (CLI + Visual Studio Code), and gives authoring, troubleshooting, and operational guidance so you can pick the right tool for the job.

At-a-glance summary

• Preset — content & prompt overrides (templates/command text). Use to change wording, templates, or organization-wide conventions without changing core code.
• Extension — new capabilities (commands, integrations, hooks). Use to add Jira, git automation, quality gates, or domain-specific behaviors.
• Workflow — a resumable, multi-step YAML pipeline that orchestrates Spec Kit commands, shell steps and human gates.
• Bundle — a versioned, shareable package that installs a curated set of presets, extensions, workflows, and steps together for a team/role.

What they change and when to pick them

• Need different wording, templates, or company style? → Preset.
• Need new integrations, commands, or hooks that run code? → Extension.
• Need to automate a repeatable multi-step process (with gates and state)? → Workflow.
• Need to ship a set of the above to teammates as one installable artifact? → Bundle.

Deep dive: Presets — change what the agent writes
What a preset does

• Presets override templates and prompt text used by Spec Kit’s agent. They are focused on content: wording, section structure, localization, default fields and the text the CLI uses when creating specs/plans/tasks.
• Presets do not (normally) run code, call external services, or change engine behavior.

When to use a preset

• Enforce company style, legal or compliance wording.
• Provide localized templates (Spanish, Japanese).
• Change default structure (one-pager vs full SDD).
• Adjust agent prompt wording for tone/conciseness.

Concrete preset manifest (example)
File path: .specify/presets/company-style.yaml

priority: 10
name: company-style
description: "Company legal & style overrides; Spanish localization for Latin America teams"

templates:
  spec.summary: "Propósito corto (1–2 oraciones)"
  spec.description: |
    Descripción:
    - Objetivo: {{ inputs.goal }}
    - Stakeholders: {{ inputs.stakeholders | join(', ') }}
  spec.security: |
    Consideraciones de seguridad:
    - Autenticación: se requiere 2FA para nuevos endpoints
    - Datos sensibles: cifrado en tránsito y en reposo

How presets stack

• Multiple presets can be active. They stack by numeric priority: lower number = higher precedence. A global company preset (priority 10) can be overridden by a repo-level preset with priority 5.
• When a template ID is present in multiple presets, the lowest-numbered preset wins for that template only.

Authoring and publishing a preset — step-by-step

1. Create a local preset file in .specify/presets/ (YAML or JSON).
2. Test locally by running a generate command that would use the template. Example:
   • CLI: specify plan –input spec=”Add login”
   • Check the generated text for your new wording.
3. If satisfied, publish the preset to your Spec Kit catalog (your org’s registry) so teams can add it with specify preset add company-style@1.0.0.
4. When updates are needed, bump the manifest version and publish a new release. Consumers can upgrade with specify preset update company-style.

VS Code: how to install and test a preset

• Terminal:
  1. Open your workspace in VS Code.
  2. Open integrated terminal (Ctrl+`).
  3. Run: specify preset add company-style
• UI (Spec Kit Companion):
  1. Open the Spec Kit sidebar.
  2. Select Presets → Search → company-style → Install.
  3. Use the “Preview” or “Generate” action in the sidebar to see the template applied.

Troubleshooting common preset issues

• Preset not taking effect: check priorities (lower wins), ensure the preset ID and version installed, and confirm the template ID you modified matches the agent’s template ID (typos happen).
• Conflicting overrides: list installed presets and remove/adjust the one you don’t want (specify preset list; specify preset remove ).

Deep dive: Extensions — add behavior and integrations
What an extension does

• Extensions are plugins that can register new CLI commands, provide templates, offer hooks, and run code. They can call external services (Jira, test runners), enforce checks, or modify repository state (branch creation, commits).
• Use extensions when you need logic beyond textual overrides.

Example extension manifest (minimal)
File: extension.yaml

id: git-jira
version: 0.1.0
name: "Git + Jira integration"
description: "Creates branches, creates Jira tickets, and wires plan acceptance to ticket creation."

commands:
  - id: git.create-branch
    command: specify git branch-for-spec
  - id: jira.create-issue
    command: specify jira create-issue --input summary="{{ inputs.summary }}"

hooks:
  onPlanAccepted: jira.create-issue

permissions:
  network:
    - "jira.example.com"
filesystem:
  read:
    - ".git"
  write:
    - ".git/refs/heads"

Authoring an extension — quick guide

1. Scaffold an extension (your preferred runtime: Node, shell scripts, or compiled binary). Keep it small and well-scoped.
2. Register commands in the manifest and map them to your executable or script.
3. Implement and mock external calls for local testing.
4. Test in a local repo:
   • Install locally: specify extension add ./path/to/extension
   • Run the new command: specify git create-branch –input spec=”…”
5. Publish to catalog once reviewed.

Example behavior: create branch + Jira ticket when a plan is accepted

• Extension registers a hook onPlanAccepted.
• When a workflow step marks the plan accepted, the extension is invoked to create a Jira ticket and a branch.
• Because extensions can run code or call networks, follow security practices (see Security section).

VS Code: installing and using an extension

• Terminal:
  1. Open integrated terminal (Ctrl+`).
  2. Run: specify extension add git-jira
• UI (Spec Kit Companion):
  1. Presets/Extensions view → Search “git-jira” → Install.
  2. The extension’s commands will show up in the Command Palette (Ctrl+Shift+P) under Spec Kit commands; or the companion UI exposes buttons like “Create Jira issue”.

Troubleshooting extensions

• Network permissions denied: check the extension manifest’s network permission and your environment firewall.
• Command missing after install: ensure the extension installed successfully and restart the terminal/VS Code if necessary.

Deep dive: Workflows — orchestrate multi-step, resumable pipelines
What a workflow does

• A workflow is a YAML pipeline that composes agent steps, shell steps, and human gates. Workflows persist run state so you can pause for review and resume later.
• Use workflows to enforce reproducible processes: assess → plan → implement → test → sign-off.

Expanded example workflow (detailed)
File: sdd-pipeline.yml

name: sdd-pipeline
inputs:
  spec:
    type: string
    required: true

steps:
  - id: assess
    type: agent
    command: specify assess --input spec="{{ inputs.spec }}"
    outputs:
      summary: string

  - id: plan
    type: agent
    command: specify plan --input spec="{{ steps.assess.summary }}"
    outputs:
      branch: string
      plan_url: string

  - id: create-branch
    type: shell
    command: |
      git checkout -b "{{ steps.plan.branch }}"
      git push -u origin "{{ steps.plan.branch }}"
    continueOnError: false

  - id: run-tests
    type: shell
    command: |
      ./run-tests.sh --report results.json
    outputs:
      test_report: results.json
    continueOnError: false

  - id: review
    type: gate
    approvers:
      - "team-lead@example.com"
    timeout: "72h"

Key workflow features demonstrated

• Inputs and typed outputs — later steps can reference earlier outputs (templating with {{ }}).
• Mix of agent and shell steps.
• Human gate with approvers and timeout.
• Persisted run state to allow resumption.

Run workflows — CLI and VS Code

• Install catalog workflow:
  specify workflow add sdd-pipeline
• Run from catalog:
  specify workflow run sdd-pipeline –input spec=”Add user authentication”
• Run a local workflow YAML:
  specify workflow run ./sdd-pipeline.yml –input spec=”Add payment flow”

VS Code:

• Terminal: run the same specify workflow commands.
• UI (Spec Kit Companion):
  1. Open Workflows in the sidebar.
  2. Choose a catalog workflow or point to a local YAML.
  3. Click “Start run” and follow the run UI to see step outputs and approve gates.

Authoring a workflow — best practices

• Validate inputs: declare required inputs and types.
• Make steps idempotent where possible (re-running a branch creation should be safe or fail cleanly).
• Persist minimal but useful outputs for later steps (e.g., branch name, plan URL).
• Add clear error handling: use continueOnError judiciously and provide logs for shell steps.
• Test locally by running the workflow with small inputs and stepping through the UI or CLI.

Troubleshooting workflows

• Workflow fails at shell step: open the run’s step logs, reproduce the commands locally in the terminal, fix failing command or environment.
• Gate never approved: ensure approvers are reachable emails and the companion UI sends notifications; approvers can resume runs from VS Code or CLI.

Deep dive: Bundles — package and share a curated stack
What a bundle does

• A bundle is a versioned artifact that declares a set of presets, extensions, workflows, and steps to install together. Bundles don’t create new primitives — they package and pin existing ones so teams get a tested configuration with one command.
• Bundles record provenance of what they installed for clean removal and upgrades.

Example bundle manifest
File: .specify/bundles/backend-team.yaml

id: backend-team
version: 1.0.0
name: "Backend Team Starter"
description: "Preset, extensions, and workflows for backend engineers."

presets:
  - company-style@10
  - backend-layout@5

extensions:
  - git@2.3.0
  - jira@1.1.0

workflows:
  - sdd-pipeline@1.0.0

metadata:
  installedBy: "bundle-maintainer@example.com"
  date: "2026-10-01"

Install / lifecycle commands

• Install a bundle:
  specify bundle install backend-team
  (alias: specify bundle add backend-team)
• List installed bundles:
  specify bundle list
• Upgrade a bundle:
  specify bundle update backend-team –version 1.1.0
• Uninstall/remove a bundle:
  specify bundle remove backend-team

What bundles actually do in a repo

• Install referenced presets, extensions, and workflows into the project.
• Create metadata in .specify/bundles/ to record installed components and pinned versions.
• Allow a single remove command to uninstall everything the bundle introduced.

When to use a bundle

• Onboarding new hires or new projects with a single command.
• Ensuring consistent, pinned tooling across teams.
• Distributing proven configurations for compliance or role-specific setups.

Bundles: VS Code experience

• Terminal:
  1. Open integrated terminal (Ctrl+`).
  2. Run: specify bundle install backend-team
• UI (Spec Kit Companion):
  1. Bundles view → Search → backend-team → Install.
  2. The UI shows progress and created files; it lists the installed components in a panel.

Security, testing, and operational guidance
Vetting extensions

• Treat extensions like any plugin: require code review, run static analysis, and audit network permissions.
• Use least-privilege: only grant network access to specific hosts used by the extension.
• Use CI sandboxing: run untrusted extensions in CI jobs with restricted tokens and ephemeral credentials.

Testing workflows and presets

• Presets: test by generating artifacts locally and comparing before/after outputs. Use a diff tool to confirm only intended changes.
• Workflows: dry-run where possible. Validate inputs and run with small, safe inputs. Test gate behavior by simulating approvals.
• Extensions: unit tests and integration tests against mocked APIs. Provide a local test harness script.

Bundles and provenance

• Always pin versions in bundle manifests to avoid unexpected breaking changes.
• Use bundle metadata to record who installed the bundle and when to enable audits and rollbacks.

Programmatic integration: invoking specify from C#
If you need to call the specify CLI from other tools or CI, capture stdout/stderr. Example (async):

using System.Diagnostics;

var psi = new ProcessStartInfo {
    FileName = "specify",
    Arguments = "workflow run sdd-pipeline --input spec=\"Build login\" --json",
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    UseShellExecute = false,
    CreateNoWindow = true
};

using var proc = Process.Start(psi);
string stdout = await proc.StandardOutput.ReadToEndAsync();
string stderr = await proc.StandardError.ReadToEndAsync();
proc.WaitForExit();
// stdout contains run result (or --json output); stderr contains errors.

In VS Code, run this same program from the integrated terminal or incorporate it into a task that runs on save or during CI.

VS Code practical steps — exact actions users will see

• Open Command Palette (Ctrl+Shift+P). Search “Spec Kit: Install Preset” or “Spec Kit: Run Workflow”.
• Spec Kit Companion sidebar panels:
  • Presets: search, preview, install.
  • Extensions: list, view commands, install.
  • Workflows: catalog view, run, see run state and step logs.
  • Bundles: browse, install, view installed metadata.
• Terminals use standard CLI commands; the UI calls the same CLI under the hood.

Authoring tutorials (concise walkthroughs)
Preset authoring walkthrough (quick)

1. Create file: .specify/presets/company-style.yaml with your overrides.
2. Test: specify plan –input spec=”Add login” and confirm the summary and security sections are replaced.
3. Publish to catalog and instruct teams: specify preset add company-style@1.0.0.

Extension authoring walkthrough (quick)

1. Scaffold a small Node or shell extension and manifest (extension.yaml).
2. Add a command that runs a script to call Jira’s API (use environment tokens).
3. Test by installing locally: specify extension add ./my-extension.
4. Publish after security review.

Workflow authoring walkthrough (quick)

1. Start from sdd-pipeline.yml example above.
2. Run locally: specify workflow run ./sdd-pipeline.yml –input spec=”…”
3. Step through the run in VS Code and fix templating issues.
4. Publish and add to a bundle for distribution.

Bundle authoring walkthrough (quick)

1. Create bundle manifest listing pinned components.
2. Run: specify bundle install ./backend-team.yaml locally to validate the install process.
3. Publish the bundle to the catalog. Team members then run specify bundle install backend-team.

Migration patterns and practical advice

• Start with presets when you only need wording changes (low risk).
• When you find repeating scripts or ad-hoc tools across repos, move them into an extension.
• When a sequence of steps becomes common and should be reproducible, author a workflow.
• When multiple teams need the same combination, wrap all pieces into a bundle.

FAQ / Troubleshooting quick hits

• Preset not applied? Check priority: specify preset list shows installed presets and priority.
• Workflow step failed — how to debug? View step logs in the CLI run output or VS Code run panel; reproduce the shell step locally.
• How do I remove a bundle? specify bundle remove will uninstall components that bundle recorded.
• An extension requires network access — is it safe? Review its permissions in the manifest and audit its code. Use least-privilege credentials.

Glossary

• Preset: content and prompt overrides for templates and text.
• Extension: plugin that adds commands, hooks, and runtime behavior.
• Workflow: a persisted YAML pipeline combining steps, shell commands, and gates.
• Bundle: a versioned package that installs presets, extensions, and workflows together.

Quick CLI reference

• Add preset: specify preset add
• Add extension: specify extension add
• Add workflow from catalog: specify workflow add
• Run workflow: specify workflow run –input spec=”…”
• Run local workflow YAML: specify workflow run ./my-workflow.yml –input spec=”…”
• Install bundle: specify bundle install
• List bundles: specify bundle list

Closing and next steps
Presets, extensions, workflows, and bundles complement each other:

• Presets shape content and tone.
• Extensions implement behavior and integrations.
• Workflows orchestrate repeatable, resumable processes.
• Bundles distribute curated stacks and keep provenance.

Note: The initial draft of this post was written by BlogWriter and then
edited by Jesse Liberty.
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

Prompts allow you to manage the exact instructions your chat models receive and let apps pick those instructions at runtime.

That’s the core value of “prompts” in the Model Context Protocol (MCP). MCP prompts let a server publish reusable, argument‑driven prompt templates that clients (including Microsoft Agent Framework agents) can discover, retrieve, and use in LLM chat calls—so behavior, UX, and auditing are consistent across apps.

Key terms (quick definitions)

• MCP server: a service that implements the Model Context Protocol and exposes tools, prompts, and resources to clients.
• Prompt template (MCP “prompt”): a server‑hosted, reusable instruction template that can accept named arguments and return one or more chat messages.
• Prompt arguments: named values (e.g., url, language, timeframe) supplied by the client when calling prompts/get.
• Prompt response messages: the chat messages (roles like system/user/assistant) returned by prompts/get that are ready to be appended to a model call.
• Resource messages: special messages in a prompt response that contain URIs or attachments (files, repo links) the model should consider.

Why MCP prompts matter for developers and product teams

• Central control: product teams can update a prompt template on the server and clients will automatically get the new behavior the next time they fetch it.
• Consistency: multiple agents and apps use the same instructions and checklists (e.g., compliance templates, code‑review checklists).
• Reusability: prompts are parameterized. One server prompt can cover many scenarios by taking arguments.
• Discoverability & UX: prompts/list lets clients surface available commands (slash menus, command palettes) rather than hardcoding instructions into each client.
• Auditability: when agents log which prompt and which arguments were used, teams can trace model behavior back to a server‑controlled template.

How prompts fit into the Microsoft Agent Framework
The Microsoft Agent Framework can connect to MCP servers at runtime. That allows an agent to:

1. Call prompts/list to discover server prompts and show them to the user (for example, as a slash‑command menu).
2. Prompt the user for required arguments (URL, code snippet, language).
3. Call prompts/get (name + arguments) to fetch the populated template as chat messages.
4. Append the returned messages to the chat history and send them to the LLM client (e.g., Azure OpenAI).
   Because the prompt is server‑hosted, the server controls wording, embedded resources, and any instruction to call tools—clients only provide arguments and deliver the resulting messages to the model.

Typical flow (concise)

1. Discover: prompts/list → display options.
2. Select & collect args: user picks a prompt → agent collects required fields.
3. Retrieve: prompts/get(name, args) → server returns promptContent.Messages and optionally resource messages.
4. Use: append returned messages to your chat request and send to the model.

Sample prompts/get JSON (small example)
This is a minimal illustration of what prompts/get might return.
{
“messages”: [
{ “role”: “system”, “content”: “You are an expert summarizer. Focus on key findings and risks.” },
{ “role”: “user”, “content”: “Summarize the document at: https://example.com/report.pdf” }
],
“resources”: [
{ “type”: “uri”, “uri”: “https://example.com/report.pdf“, “description”: “Source PDF” }
]
}

C# examples (illustrative, practical, with error handling)
Notes: the exact MCP SDK namespace and method names vary by SDK version. The examples below follow common patterns used in the MCP quickstart and show how to map MCP messages into a chat client call. Replace transport/creation code with the actual constructors in your MCP SDK.

Install (example)

• Add an MCP client package (example package id: ModelContextProtocol.Client)
• Add your LLM client package (example: Azure.AI.OpenAI)

Example 1 — Summarize document (argument: url)
This example lists prompts, finds summarize-document, calls get with a URL, and sends returned messages to an Azure OpenAI chat client.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using ModelContextProtocol.Client; // example package
using Azure.AI.OpenAI;
using Azure;

async Task SummarizeDocumentAsync(string documentUrl, CancellationToken cancellationToken = default)
{
try
{
// 1) Create MCP client (transport creation is SDK-specific)
var transport = /* create transport per your SDK: HTTP, WebSocket, etc. */;
var mcpClient = await McpClient.CreateAsync(transport, cancellationToken); // 2) List prompts
    var prompts = await mcpClient.ListPromptsAsync(cancellationToken);
    var summarize = prompts.FirstOrDefault(p => p.Name == "summarize-document");
    if (summarize == null)
        throw new InvalidOperationException("Prompt 'summarize-document' not available.");

    // 3) Call prompts/get with required arguments
    var args = new Dictionary<string, object> { ["url"] = documentUrl };
    var promptContent = await summarize.GetAsync(args, cancellationToken);

    // 4) Map MCP messages to OpenAI chat messages
    var openAiClient = new OpenAIClient(new Uri("https://your-azure-endpoint/"), new AzureKeyCredential("AZURE_KEY"));
    var chatOptions = new ChatCompletionsOptions();
    foreach (var m in promptContent.Messages)
    {
        chatOptions.Messages.Add(MapMcpMessageToChatMessage(m));
    }

    // Optional: append follow-up instructions from the user
    chatOptions.Messages.Add(new ChatMessage(ChatRole.User, "Please keep the summary under 200 words."));

    var response = await openAiClient.GetChatCompletionsAsync("deployment-name", chatOptions, cancellationToken);
    Console.WriteLine(response.Value.Choices[0].Message.Content);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.Error.WriteLine("Prompt not found: " + ex.Message);
}
catch (Exception ex)
{
    Console.Error.WriteLine("Error fetching prompt or calling model: " + ex.Message);
    throw;
}}

static ChatMessage MapMcpMessageToChatMessage(McpMessage m)
{
var role = m.Role switch
{
  system" => ChatRole.System,
  "assistant" => ChatRole.Assistant,
  _ => ChatRole.User
};
  return new ChatMessage(role, m.Content);
}

Example 2 — Code review (arguments: code, optional language)
This example demonstrates sending a code snippet and language argument to a code_review prompt. The server might return a checklist system message plus resource URIs pointing to related files.

async Task CodeReviewAsync(string codeSnippet, string language = "csharp", CancellationToken cancellationToken = default)
{
var transport = /* create transport */;
var mcpClient = await McpClient.CreateAsync(transport, cancellationToken);
var prompts = await mcpClient.ListPromptsAsync(cancellationToken);
var codePrompt = prompts.FirstOrDefault(p => p.Name == "code_review");
if (codePrompt == null) throw new InvalidOperationException("code_review not available");

var args = new Dictionary<string, object> { ["code"] = codeSnippet, ["language"] = language };
var promptContent = await codePrompt.GetAsync(args, cancellationToken);

var openAiClient = new OpenAIClient(new Uri("https://your-azure-endpoint/"), new AzureKeyCredential("KEY"));
var chatOptions = new ChatCompletionsOptions();
foreach (var m in promptContent.Messages)
{
    chatOptions.Messages.Add(MapMcpMessageToChatMessage(m));
}

var response = await openAiClient.GetChatCompletionsAsync("deployment-name", chatOptions, cancellationToken);
Console.WriteLine(response.Value.Choices[0].Message.Content);
}

Practical tips (concrete, actionable)

• Validate arguments on the client: whitelist allowed languages, enforce URL schemes (https), and check length limits. Refuse or sanitize inputs that look like secrets.
• Prefer proxying or previewing third‑party resources instead of sending raw URIs to external servers. If you must share URIs, use signed, time‑limited links.
• Handle common error codes: 404 = prompt not found, 400 = missing/invalid args, 429 = rate limit; implement exponential backoff and circuit breakers.
• Cache prompt metadata: calls to prompts/list are relatively cheap but cache names/descriptions and refresh periodically to avoid UI delays.
• UI recommendations: present prompts in a command palette or slash‑menu; show required arguments and a small template preview before fetching; allow an editable preview so users can tweak arguments before sending.
• Embedded resources: if the prompt returns resource messages, decide whether to fetch the resource text (and include it in the chat) or attach a link. If fetching, enforce size limits and sanitize content.
• Versioning & breaking changes: because prompts are server‑controlled, add an ability to pin a prompt version (if the server supports it) or keep integration tests that validate prompt behavior after server updates.
• Audit and tracing: log prompt name + non‑sensitive args and add trace IDs/headers when calling MCP servers so you can correlate user actions and prompt outputs for debugging and compliance.

Security & operational specifics

• Redact secrets: never send API keys, passwords, or PII to a third‑party MCP server. Run argument sanitization and redaction on the client.
• Signed URLs: use expiring signed URLs when providing attachments to external servers; this limits exposure.
• Policy & approval: treat server‑hosted prompts as part of your product’s compliance surface. Establish a governance process for who can change server prompts.
• Headers & audit: follow the Agent Framework guidance for adding audit headers and tracing to MCP calls. Store logs of prompt usage (prompt name, timestamp, actor) with care for privacy.

Error handling & retries (short patterns)

• Use CancellationToken for timeouts.
• Retry transient errors (HTTP 5xx, 429) with an exponential backoff and jitter.
• Surface user‑friendly messages for 400/422 responses (missing args or invalid input) and guide the user to correct inputs.

Where to read next

• Model Context Protocol prompts spec: modelcontextprotocol.io (prompts/list and prompts/get shapes).
• Microsoft Agent Framework docs: on integrating MCP prompts and security guidance.
• .NET quickstart and MCP C# SDK samples: for precise types and SDK usage in production.

An agent in the Microsoft Agent Framework (MAF) talks to an LLM whenever it needs to:
(1) decide what to do or generate text (initial planning/response generation),
(2) decide whether to call a tool and provide its arguments (function/tool calling), and
(3) incorporate tool outputs and continue reasoning or synthesize the final reply.

A single agent run commonly produces multiple model calls in a loop: planning → tool call(s) → synthesis → (repeat if needed).

MAF implements a layered agent pipeline. Calling agent.RunAsync (or equivalent) starts a run that flows down middleware and context providers before ever hitting a model client (the LLM), and the run’s responses flow back up. That orchestration is why an agent doesn’t “just call the LLM once” by default—the framework determines when and how many model requests are required based on the agent’s instructions, tools, and middleware.

Three middleware layers you can hook in

• Agent-run middleware: wraps the entire run (fires once per run). Good for run-level telemetry or cancellation.
• Function/tool middleware: wraps each tool invocation (fires for each tool call). Useful for gating tool execution, approvals, or stubbing tools for tests.
• Chat / IChatClient middleware: wraps every underlying model/chat client call (fires every time the framework calls the model). Useful for logging prompts, redaction, or cost measurement.

Typical sequence that triggers LLM calls

1. Request received → pipeline and context providers populate run context (no model call yet).
2. Initial reasoning/plan → LLM call to decide plan (generate response or choose a tool). This is typically the first chat call.
3. If the model chooses a tool → framework executes function middleware and runs the tool (tool execution itself may be non-LLM code).
4. After tool returns → agent calls LLM again to integrate tool output and produce/synthesize the final response.
5. If needed, the LLM may ask to call another tool and the loop continues. Each cycle can add one (or more, depending on provider semantics) model calls.

C# examples

1. Minimal agent run (RunAsync typically triggers at least one LLM call)
   This follows the quick-start pattern; RunAsync goes through the pipeline and will call the model as needed.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var agent = new AIProjectClient(
new Uri("https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"),
new AzureCliCredential()
).AsAIAgent(
model: "gpt-5.4-mini",
instructions: "You are a helpful assistant. Keep answers brief."
);

var result = await agent.RunAsync("What is the largest city in France?");
Console.WriteLine(result);

2. Tool/function call flow (model decides to call a tool → tool executes → model synthesizes)
   Sketch of registering a tool; the run will typically perform model → tool → model:

// sketch
var myTool = new FunctionTool(
name: "get-weather",
description: "Get weather for a city",
handler: async (args) => {
return await GetWeatherAsync(args); // actual non-LLM work
}
);

var agent = new ChatClientAgentBuilder()
.UseModel("gpt-5.x")
.RegisterTool(myTool)
.Build();

// This RunAsync will likely:
// 1) call model to decide plan (may return "call get-weather")
// 2) execute myTool (no LLM)
// 3) call model to synthesize the final reply
var response = await agent.RunAsync("What's the weather in Seattle tomorrow?");
Console.WriteLine(response);

3. Chat middleware: intercept every LLM call (log each model invocation)
   Chat-level middleware runs on every model/chat client request:

async Task LoggingChatMiddleware(
IEnumerable messages,
ChatOptions? options,
IChatClient innerClient,
CancellationToken cancellationToken)
{
  Console.WriteLine($"[ChatMiddleware] Sending {messages.Count()} messages to model...");
  var resp = await innerClient.GetResponseAsync(messages, options, cancellationToken);
  Console.WriteLine($"[ChatMiddleware] Model returned {resp.Messages.Count} messages.");
  return resp;
}

// Register this middleware when configuring IChatClient / ChatClientAgent (see docs for exact APIs).

4. Agent-run and function middleware (brief sketches)

• Agent-run middleware: wrap whole run for telemetry or per-run constraints.
• Function middleware: intercept each tool invocation (e.g., require approval):

// Function middleware sketch
async Task ApproveThenExecuteMiddleware(
ToolInvocation invocation,
Func<ToolInvocation, Task> next,
CancellationToken ct)
{
  if (!IsApproved(invocation)) throw new Exception("Tool call not approved.");
    return await next(invocation); // proceed to actual tool handler
}

Practical caveats and best practices

• Multiple LLM calls per run are normal. Instrument chat middleware to measure API usage and cost.
• Tool execution is non-LLM work; function middleware can gate, mock, or log tool runs.
• Providers differ: function-calling semantics, streaming behavior, and limits can change how often or how responses are streamed.
• Use concise instructions and tool schemas so the model makes fewer unnecessary tool calls.
• If you need strict accounting of model usage, intercept at chat middleware (every model call passes there).

• MCP (Model Context Protocol) is an open protocol that standardizes how AI hosts (models/ or agents) discover and call external “tools” and contextual data sources. Instead of building bespoke integrations for every service, an AI host can discover tools exposed by MCP servers and invoke them using a single, consistent API (tool list + function invocation/streaming).
• MCP server: a service that publishes tools (callable functions, data endpoints, long-running operations) via MCP over supported transports (stdio for local child processes, HTTP + SSE for remote/streamable). Servers are the canonical place to register capabilities agents can discover. *SSE is an HTTP‑based streaming mechanism where the server keeps an HTTP connection open and continuously pushes events to the client
• MCP client: the client-side runtime your agent uses to discover and call tools exposed by one or more MCP servers. The MCP C# SDK provides transports and helpers to produce AIFunctions that integrate with Microsoft’s Agent Framework function-calling model.
  
  

This post explains what MCP is, how servers and clients work, and how to connect MCP tools into the Microsoft Agent Framework with short, practical C# examples (stdio client, converting tools to AIFunctions, and a minimal ASP.NET Core MCP server). It assumes you already know the Microsoft Agent Framework and are familiar with adding AIFunctions to an agent.

Why MCP matters for Agent Framework users

• Decoupling: your agent doesn’t need every skill embedded. Publish skills centrally on MCP servers and let agents discover them at runtime.
• Reuse & governance: maintain a canonical set of tools, centralize auth, logging, quotas, and policy.
• Transport flexibility: local tools as child processes (stdio) during development, HTTP + SSE for remote production services with streaming and sessions.
• Function-calling integration: the MCP C# SDK exposes helpers that translate MCP tools to AIFunction instances you can pass directly to the Agent Framework. That means the model’s function-calling flow can choose and invoke remote MCP tools as if they were local functions.

Core concepts

• Tool: a callable capability. Each tool includes metadata (name, description, JSON schema for arguments, and optional streaming semantics). LLMs use this metadata to select and call appropriate tools.
• Transport: how a client talks to a server. Common transports: stdio (spawned child), HTTP + SSE (remote streaming).
• Session & long-running tasks: MCP supports sessions and resumable/streamable operations so agents can work with long-running processes.
• Security: MCP servers are APIs—protect them with OAuth, validate scopes/claims, and apply standard API hardening.

C# examples — preface and dependencies

• The examples use the Model Context Protocol C# SDK and the Agent Framework integration helpers. Replace placeholders (endpoints, credentials, model clients) with your configuration.
• NuGet packages you’ll typically use (check exact package names/versions for your environment): ModelContextProtocol.Client, ModelContextProtocol.AspNetCore (server-side), Microsoft.Extensions.AI (AIFunction types), and your Agent Framework package (the one you already use). The exact package names and APIs may evolve; consult the MCP C# SDK docs and Agent Framework docs for up-to-date guidance.

Example 1 — Minimal MCP client (stdio) that lists tools
Purpose: quickly launch a local MCP server as a child process and list the tools it exposes. Useful for local dev or verifying a server.

C# (minimal)

using System;
using System.Threading.Tasks;
using ModelContextProtocol.Client;
using ModelContextProtocol.Client.Transports;

class Program
{
    static async Task Main()
    {
        // Start a local MCP server as a child process. Adjust command/arguments.
        var transport = new StdioClientTransport(new StdioClientTransportOptions
        {
            Command = "dotnet",
            Arguments = new[] { "run", "--project", "../MyMcpServer" },
            Name = "LocalMcp"
        });

        using var mcpClient = await McpClient.CreateAsync(transport);

        var tools = await mcpClient.ListToolsAsync();
        Console.WriteLine("Tools available from MCP server:");
        foreach (var t in tools)
        {
            Console.WriteLine($"- {t.Name}: {t.Description}");
        }
    }
}

What this does

• It spawns your server project (via dotnet run) and uses the stdio transport to speak MCP to it.
• ListToolsAsync fetches the catalog of published tools (names, descriptions, and parameter schemas).

Notes

• Use stdio for development, local tooling, or launching untrusted tools in a sandboxed child process. For production remote servers use HTTP + SSE.
• Always handle cancellation tokens and process lifecycle (timeouts, crashes) robustly in production code.

Example 2 — Convert MCP tools to AIFunctions and add them to an Agent
Purpose: let your agent use discovered remote tools via the Agent Framework’s function-calling mechanism (the model sees tools as functions it can call).

C# (sketch)

using System;
using System.Threading;
using System.Threading.Tasks;
using ModelContextProtocol.Client;
using ModelContextProtocol.Client.Transports;
using Microsoft.Extensions.AI;                // AIFunction types
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Agents.AI;                    // your Agent Framework types

class Program
{
    static async Task Main()
    {
        // 1) Create an MCP client (stdio example)
        var transport = new StdioClientTransport(new StdioClientTransportOptions
        {
            Command = "dotnet",
            Arguments = new[] { "run", "--project", "../MyMcpServer" }
        });

        using var mcpClient = await McpClient.CreateAsync(transport);

        // 2) Convert discovered tools to AIFunctions using the SDK helper
        // The SDK exposes an extension/method that returns IEnumerable<AIFunction>
        var aiFunctions = await mcpClient.GetAIFunctionsAsync(cancellationToken: CancellationToken.None);
        // aiFunctions are ready to pass into the Agent Framework.

        // 3) Build your ChatClient (your existing model client). Pseudocode below.
        IChatClient chatClient = BuildYourChatClientWithFunctionInvocation(); // use OpenAI/AzureOpenAI etc.

        // 4) Create an agent with the discovered functions available to the model
        var agent = chatClient.AsAIAgent(instructions: "You may call MCP tools as needed.", tools: aiFunctions);

        var result = await agent.RunAsync("Check invoice 12345 and return the payment date.");
        Console.WriteLine(result.Text);
    }

    static IChatClient BuildYourChatClientWithFunctionInvocation()
    {
        // Build your model client with function-calling enabled. This is highly dependent
        // on which model SDK you use; use the Agent Framework pattern you already have.
        throw new NotImplementedException();
    }
}

Key points and gotchas

• The MCP SDK returns AIFunction-compatible objects (or adapters) for MCP tools; you can pass them straight into the agent constructor/options used by the Agent Framework. No manual JSON schema translation usually required.
• Pay attention to parameter schemas: MCP tool parameter schemas are JSON Schema-based. The AIFunction adapter will present these to the model, but ensure you validate arguments server-side as well.
• Streaming/long-running tools: if a tool supports streaming or sessions, the adapter may offer streaming bindings or expose session tokens that the Agent Framework can handle. Check the SDK docs for streaming APIs and how they map to your chat client’s streaming model.

Example 3 — Minimal ASP.NET Core MCP server (HTTP + SSE)
Purpose: expose tools over HTTP + SSE so remote agents can discover and invoke them. This is a minimal Program.cs sketch; register and implement your tools separately.

Program.cs

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.AspNetCore; // server integration

var builder = WebApplication.CreateBuilder(args);

// Add MCP server services (package provides extension methods)
builder.Services.AddModelContextProtocol();

var app = builder.Build();

// Map the MCP endpoints. This registers the endpoints the MCP HTTP transport expects (e.g. /sse, /messages).
app.MapMcp(); // extension method from ModelContextProtocol.AspNetCore

app.Run();

Registering tools

• The SDK provides APIs to register tools (stateless tools, session-aware tools, or long-running handlers). Implement each tool as a class or function and register it with the MCP server service registration API (see SDK docs for registration patterns). Tools are described with name, description, and input schema.

Security

• Protect MCP endpoints with OAuth 2.1 / bearer tokens (Microsoft Entra ID recommended). Validate scopes and claims before allowing tool invocation. Don’t expose privileged tools without strict auth checks.
• Apply standard API hardening: CORS restrictions, host filtering, rate limiting, input validation, logging/auditing, and parameter sanitization. Treat tool execution as code execution—apply sandboxing, denylisting, and runtime quotas where appropriate.

Example: minimal tool registration sketch (pseudocode)

// Pseudocode - consult the SDK for exact API names
builder.Services.AddModelContextProtocol()
    .AddTool<MyTool>("CheckInvoice", options => { /* metadata, schema */ });

Practical notes when connecting MCP and Agent Framework

1. Discovery vs. shipping tools
   • You can ship a few “core” tools inside the agent and discover more via MCP at startup or dynamically during a session. Consider caching the tool catalog to avoid repeated network calls.
2. Function invocation flow
   • The Agent Framework’s function-calling flow is typically: model chooses a function, agent runtime serializes arguments according to the function schema, calls the function, and returns results to the model. MCP adapters wire that call to an MCP server invocation. Handle timeouts and partial results for long-running operations.
3. Streaming & sessions
   • For streaming outputs (SSE), ensure your chat client and agent can accept streamed partial results or forward them as incremental responses to the model. For session-based tools (long-running jobs), the server will usually hand back a session ID or event stream you can poll or subscribe to. Map session lifecycle into your agent’s state model.
4. Error handling & observability
   • Log tool discovery, invocation arguments, responses, and errors. Capture correlation IDs. Consider returning sanitized error messages to the model while logging full details internally.
5. Security & governance checklist
   • Require OAuth bearer tokens and validate tokens on every request.
   • Use scoped permissions: separate discovery (tool list) vs. execution scopes.
   • Limit which apps/users can call elevated tools.
   • Rate-limit and quota tools to reduce abuse.
   • Validate input against declared JSON schema server-side (never trust client input).
   • Sanitize logs to avoid leaking sensitive data.
   • Audit tool invocations with user identity and request context.
   • Consider a per-tool approval workflow for sensitive operations (human-in-the-loop).

Debugging tips

• If ListToolsAsync returns nothing: check transport connectivity, server process logs (stdio), firewall/CORS (HTTP), and version compatibility between client/server SDKs.
• For JSON schema mismatches: ensure server-published tool schemas are valid JSON Schema and that the client SDK version understands the schema features used.
• For streaming issues: check that the server pushes SSE frames and that the client transport is configured to read/forward events incrementally.
• For auth issues: inspect token audience (resource indicator), scopes, and clock skew. Entra ID configuration examples are in Microsoft docs.

Real-world use cases (short)

• Integrating Teams / Copilot: expose an MCP server that can send messages, create approvals, or read group context—agents discover these tools to orchestrate workflows.
• Enterprise services: expose CRM, ERP, or Dynamics 365 actions via MCP so Copilot/agents can act on domain data without embedding connectors in every agent.
• IDE tooling: expose project or infra operations (build, deploy, ticket lookup) as MCP tools so in-editor agents can perform actions safely and auditable.

Where to go from here

• Official docs and samples:
  • Model Context Protocol (overview): Microsoft Learn MCP overview.
  • MCP C# SDK repo and samples: modelcontextprotocol/csharp-sdk on GitHub.

Appendix — runnable minimal project tips and csproj hints

• Minimal dependencies you’ll likely need (adjust exact package IDs to match the SDK versions you pick):
  • ModelContextProtocol.Client
  • ModelContextProtocol.AspNetCore (server)
  • Microsoft.Extensions.AI
  • Your Agent Framework package (the one you already use)

Example csproj snippet (replace versions and package names with exact ones you choose)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="ModelContextProtocol.Client" Version="x.y.z" />
    <PackageReference Include="ModelContextProtocol.AspNetCore" Version="x.y.z" />
    <PackageReference Include="Microsoft.Extensions.AI" Version="x.y.z" />
    <!-- Add your Agent Framework package here -->
  </ItemGroup>
</Project>

Note: The initial draft of this post was written by BlogWriter and then
edited by Jesse Liberty.
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

TL;DR

• Learn the simple C# steps to wire Retrieval-Augmented Generation (RAG) into Microsoft Agent Framework (MAF).
• Includes a runnable, self-contained console stub that chunks documents, stores them in-memory with metadata, runs a demo similarity search, and returns answers plus source citations.
• Swap the demo token-overlap search for real embeddings + a vector DB in production and then pass the search delegate into MAF’s TextSearchProvider.

Overview

1. Chunk documents and record metadata (Id, SourceName, SourceLink).
2. Compute embeddings for each chunk and store (vector DB or in-memory for prototype).
3. Implement a search delegate: query → embedding → nearest neighbors → map to TextSearchResult-like results.
4. Attach the search delegate to MAF via TextSearchProvider. Choose between injecting passages (BeforeAIInvoke) or exposing search as a callable tool (OnDemandFunctionCalling).
5. Run the agent; show model response and the underlying source metadata for traceability.

Notes on packages and API names

• The relevant MAF package is typically Microsoft.Agents.AI (check the exact package and namespace for your MAF version on NuGet and the MAF docs).
• Typical using directives you might need:
  using Microsoft.Agents.AI;
  using Microsoft.Agents.AI.TextSearchProvider;
• API names and enum names (e.g., TextSearchBehavior.BeforeAIInvoke) may vary by MAF version—verify your installed NuGet version and adjust namespaces accordingly.

Quick actionable steps

1. Prepare documents

• Split long content into chunks (500–1000 chars recommended) with some overlap (50–100 chars) to preserve context.
• For each chunk, store:
  • Id (unique)
  • SourceName (file name)
  • SourceLink (URL)
  • Text (chunk text)
  • Optional metadata (section title, date)
• Compute an embedding for each chunk (production) and store the embedding vector alongside metadata.

2. Implement the search delegate

• Signature MAF expects (canonical shape you should adapt to your MAF version):
  Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>>
• Implementation steps:
  • Convert query → embedding (same embedding model used for docs).
  • Query vector DB for top-K neighbors (approx. nearest neighbor).
  • Map each hit to TextSearchResult (Text, SourceName, SourceLink, RawRepresentation).

3. Create and configure a TextSearchProvider

• Instantiate a TextSearchProvider with your search delegate and options (behavior, top_k).
• Add to ChatClientAgentOptions.AIContextProviders so the agent can use it.

4. Run the agent and surface metadata

• Decide the mode:
  • BeforeAIInvoke—passages injected into prompt before model call (simpler, higher token usage).
  • OnDemandFunctionCalling—model invokes search explicitly (more control/cost saving).
• Return the model response, and surface SourceName/SourceLink/RawRepresentation to the user for verification.

Scoring and thresholds

• Use cosine similarity on embeddings—normalized between -1 and 1. Typical positive ranges near 0.7–0.95 indicate high similarity depending on your model and vector dims.
• Prototype token-overlap scores are uncalibrated. Use a minScore cutoff (e.g., 0.05–0.2) to filter noise and avoid returning unrelated passages.
• Top-K: usually 3–5 passages works well to balance context and token cost.

Troubleshooting quick tips

• If queries return nothing: check chunking (too small chunks can lose context) and tokenization differences (embedding model vs. tokenization used in your search).
• If irrelevant results: increase overlap, reduce chunk size, or switch to a stronger embedding model.
• If costs are high: use OnDemandFunctionCalling and caching of query embeddings.

Runnable, self-contained C# console stub

• Purpose: demonstrate chunking, adding documents with metadata, a demo token-overlap similarity search, returning top-K hits, and showing source metadata.
• This demo is intentionally self-contained and uses a simple token-overlap scoring (NOT production quality). Replace the demo search and Tokenize with real embeddings + vector DB.

Create a new console app:
dotnet new console -n SimpleRagDemo
Replace Program.cs with the code below and run dotnet run.

Code (runnable stub)

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using System.Text;

// Simple Document chunk container with metadata
record DocumentChunk(string Id, string SourceName, string SourceLink, string Text);

// Result shape similar to TextSearchProvider.TextSearchResult
record SearchResult(string Text, string SourceName, string SourceLink, double Score, string RawRepresentation);

class SimpleRagStore
{
    private readonly List<DocumentChunk> _chunks = new();

    // Add a chunk (in production you'd also persist an embedding vector here)
    public void AddChunk(DocumentChunk chunk) => _chunks.Add(chunk);

    // Demo-only: token-overlap similarity (replace with embeddings + vector DB in production)
    // Returns topK search results (and ignores zero-score results by default)
    public Task<IEnumerable<SearchResult>> SearchAsync(string query, int topK = 3, double minScore = 0.0, CancellationToken ct = default)
    {
        ct.ThrowIfCancellationRequested();

        var qTokens = Tokenize(query);
        if (qTokens.Count == 0) return Task.FromResult(Enumerable.Empty<SearchResult>());

        var scored = _chunks.Select(c =>
        {
            var dTokens = Tokenize(c.Text);
            var overlap = qTokens.Intersect(dTokens).Count();
            // Simple normalized score for demo (not cosine)
            var score = overlap == 0 ? 0.0 : overlap / Math.Sqrt(qTokens.Count * dTokens.Count);
            return new SearchResult(
                Text: c.Text,
                SourceName: c.SourceName,
                SourceLink: c.SourceLink,
                Score: score,
                RawRepresentation: $"chunk:{c.Id}"
            );
        })
        .Where(r => r.Score > minScore)
        .OrderByDescending(r => r.Score)
        .Take(topK);

        return Task.FromResult(scored.AsEnumerable());
    }

    // Demo tokenization: extract word-like tokens, lower-case, remove short stop-words.
    // Production: keep consistent tokenization with embedding model or skip and use vector similarity.
    private static HashSet<string> Tokenize(string text)
    {
        var matches = Regex.Matches(text.ToLowerInvariant(), @"\w+"); // letters/digits/underscore
        var set = new HashSet<string>();
        foreach (Match m in matches)
        {
            var tok = m.Value;
            if (tok.Length <= 2) continue; // skip tiny tokens in this demo
            set.Add(tok);
        }
        return set;
    }
}

static class ChunkingHelper
{
    // Split a long document into chunks with overlap.
    // chunkSize characters and overlap characters.
    public static IEnumerable<string> ChunkText(string text, int chunkSize = 800, int overlap = 100)
    {
        if (string.IsNullOrEmpty(text)) yield break;
        if (chunkSize <= overlap) throw new ArgumentException("chunkSize must be greater than overlap");

        int start = 0;
        while (start < text.Length)
        {
            int len = Math.Min(chunkSize, text.Length - start);
            yield return text.Substring(start, len);
            start += (chunkSize - overlap);
        }
    }
}

class Program
{
    // Placeholder: in production you'd call your embedding model here.
    // Keep this method so it's clear where to swap in real embeddings.
    static Task<double[]> GetEmbeddingAsync(string text, CancellationToken ct = default)
    {
        // Demo does not use embeddings. Return a dummy vector for shape.
        return Task.FromResult(new double[0]);
    }

    static async Task Main(string[] args)
    {
        var store = new SimpleRagStore();

        // Example long document (will be chunked)
        var longDoc = @"This document explains how to reset your password. You can reset your password
by visiting /account/reset and following the instructions. Reset tokens last 1 hour.
If you don't receive an email, check your spam folder and contact support at support@example.com.";

        // 1) Chunk the long document and add chunks with metadata
        int chunkSize = 200; // small for demo visibility
        int overlap = 40;
        int chunkIndex = 0;
        foreach (var chunkText in ChunkingHelper.ChunkText(longDoc, chunkSize, overlap))
        {
            var id = $"pwd-doc-{chunkIndex++}";
            store.AddChunk(new DocumentChunk(
                Id: id,
                SourceName: "AccountFAQ.md",
                SourceLink: "https://example/docs/account-faq",
                Text: chunkText.Trim()
            ));
        }

        // Add a few short docs (already small)
        store.AddChunk(new DocumentChunk("install-1", "GettingStarted.md", "https://example/docs/getting-started",
            "To install the product, run dotnet tool install -g Example.Tool and then run example init."));
        store.AddChunk(new DocumentChunk("rn-1", "ReleaseNotes.md", "https://example/docs/releases",
            "Version 2.1 adds RAG support via a TextSearchProvider and includes an in-memory connector."));

        Console.WriteLine("Simple RAG demo. Ask a question about the docs (type 'exit' to quit).");

        while (true)
        {
            Console.Write("> ");
            var question = Console.ReadLine();
            if (string.IsNullOrWhiteSpace(question)) continue;
            if (question.Trim().Equals("exit", StringComparison.OrdinalIgnoreCase)) break;

            // 2) Search (this mimics the search delegate you'd pass into TextSearchProvider)
            var results = await store.SearchAsync(question, topK: 3, minScore: 0.0, CancellationToken.None);

            // 3) Synthesize a simple grounded answer (demo-only)
            if (!results.Any())
            {
                Console.WriteLine("No grounded passages found. (In production you might still call your LLM but mark as 'no sources found')");
                continue;
            }

            var best = results.First();
            var outBuilder = new StringBuilder();
            outBuilder.AppendLine("Answer (grounded):");
            outBuilder.AppendLine($" - {best.Text}");
            outBuilder.AppendLine();
            outBuilder.AppendLine("Sources:");
            foreach (var r in results)
            {
                outBuilder.AppendLine($" - {r.SourceName} ({r.SourceLink})  [score={r.Score:F3}] raw={r.RawRepresentation}");
            }

            Console.WriteLine(outBuilder.ToString());
        }
    }
}

How to swap the demo for real production components

• Replace Tokenize + token-overlap similarity with:
  • Embeddings: call your embeddings model (Azure OpenAI or OpenAI), get float[] vectors for each chunk and for the query.
  • Vector store: persist chunk vectors + metadata to Qdrant, Redis, Azure Cognitive Search (vector-capable) or pgvector and query via nearest-neighbor search (cosine or dot-product).
  • Map DB hits to TextSearchProvider.TextSearchResult and return top-K.
• Ensure consistent embedding model between document and query vectors.

Mapping the search delegate into Microsoft Agent Framework (sketch)

• Search delegate signature (adapt to MAF version):
  Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>>
• Example wiring (pseudo):

// Adapt namespaces & types for your MAF version
async Task<IEnumerable<TextSearchProvider.TextSearchResult>> MySearchAsync(string q, CancellationToken ct)
{
    var qVec = await MyEmbeddingClient.GetEmbeddingAsync(q, ct);
    var hits = await MyVectorDb.SearchAsync(qVec, topK: 4, ct);
    return hits.Select(h => new TextSearchProvider.TextSearchResult
    {
        Text = h.Text,
        SourceName = h.Metadata["sourceName"],
        SourceLink = h.Metadata.TryGetValue("link", out var l) ? l : null,
        RawRepresentation = h.Id
    });
}

var textSearchProvider = new TextSearchProvider(MySearchAsync, new TextSearchProviderOptions
{
    // Behavior = TextSearchBehavior.BeforeAIInvoke or OnDemandFunctionCalling
});
var agentOptions = new ChatClientAgentOptions
{
    Name = "MyRagAgent",
    AIContextProviders = new[] { textSearchProvider }
};

• Note: check MAF docs for exact type/namespace names for your NuGet version.

Practical tuning checklist

• Chunk size: 500–1000 chars is common. Use overlaps of 50–150 chars.
• Top-K: start with 3–5. Increase if model still hallucinates.
• Min score: filter out low similarity hits.
• Mode: BeforeAIInvoke for reliability; OnDemandFunctionCalling for cost control.

Security and cost considerations

• Embeddings and model calls cost money—cache embeddings and reuse them.
• Remove/obfuscate PII before storing embeddings if required by privacy rules.
• Log and surface source metadata for auditability.

Sample console output (what to expect)

• User: “How do I reset my password?”
• Output:
  Answer (grounded):
  • This document explains how to reset your password. You can reset your password by visiting /account/reset and following the instructions.
    Sources:
  • AccountFAQ.md (https://example/docs/account-faq) [score=0.62] raw=chunk:pwd-doc-0
  • AccountFAQ.md (https://example/docs/account-faq) [score=0.45] raw=chunk:pwd-doc-1

Note: The initial draft of this post was written by BlogWriter and then edited by Jesse Liberty.
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

In this guide you’ll get a working quickstart (Windows .NET 7 + WinML and a cross-platform Python example), exact commands to install and download a model, copy‑and‑paste code, hardware/driver tips, observability and troubleshooting checks, CI/CD advice, and production‑ready recommendations.

What you’ll accomplish

• Install Foundry Local (runtime + SDK) and pick/download a local model from the Foundry catalog.
• Create a minimal MAF agent that uses Foundry Local as the model provider.
• Run the agent locally in C# (.NET 7 on Windows using WinML) and in Python (cross-platform).
• Diagnose common problems (OOM, slow inference, missing model) and tune model choices.

Quick overview (high-level steps)

1. Install Foundry Local SDK/CLI for your OS.
2. Use the Foundry CLI or SDK to list and download a model alias.
3. Add MAF + Foundry provider packages to your project (dotnet or pip).
4. Configure the client (FOUNDRY_LOCAL_MODEL env var or pass at construction).
5. Run the agent — Foundry Local will load the optimized model and MAF will call it for inference.

Prerequisites

• OS: Windows, macOS, or Linux
• .NET SDK: dotnet 7+ (if using C#)
• Python: 3.8+ (if using Python)
• Disk space: model downloads vary (see catalog); first download requires internet
• Hardware: CPU-only works, but GPU/NPU provides much faster inference. Ensure GPU drivers & runtimes are installed (see GPU section below).
• Command-line familiarity, ability to set environment variables

Quickstart (10–15 commands)
This is a condensed path from zero to a running agent (Windows example for .NET then Python). If you prefer a single OS, follow that section below in full.

Windows (.NET 7 + WinML quick path)

1. Install dotnet 7 SDK (if not installed).
2. Create a new console app and add packages:
   • dotnet new console -n FoundryAgentDemo
   • cd FoundryAgentDemo
   • dotnet add package Microsoft.Agents.AI
   • dotnet add package Microsoft.Agents.AI.Foundry –prerelease
   • dotnet add package Microsoft.AI.Foundry.Local.WinML
3. Set model alias (PowerShell):
   • $env:FOUNDRY_LOCAL_MODEL = “phi-4-mini”
4. Build & run:
   • dotnet build
   • dotnet run
     (On first run Foundry Local will download the chosen model. Expect time for the initial download.)

Cross-platform Python quick path

1. Create virtualenv and install (adjust package names if necessary — see details below):
   • python -m venv venv && source venv/bin/activate
   • pip install agent-framework foundry-local-sdk
2. Set model alias (bash):
   • export FOUNDRY_LOCAL_MODEL=”phi-4-mini”
3. Run main.py (see Python example below)

Important note: package and CLI names evolve. If a command fails, consult the Foundry Local docs and the official sample repos (foundry-samples and agent-framework) which contain tested examples and exact package/namespace names.

Part A — Install Foundry Local and download a model (details)

1. Install options
   Foundry Local can be consumed via:

• NuGet packages for .NET (recommended for C# apps)
• PyPI packages (for Python)
• npm packages (for JS)
• Native installers or a platform-specific CLI where available

Where to get the right installer/packages

• Microsoft Learn Foundry Local get-started (follow the platform-specific instructions)
• Official GitHub samples: microsoft-foundry/foundry-samples and microsoft/agent-framework

2. Example .NET installation (project-level)
   You don’t usually “install” the runtime globally for .NET; add the Foundry Local package(s) to your project:

• dotnet add package Microsoft.AI.Foundry.Local (Linux/macOS/CPU/GPU)
• On Windows to use WinML/DirectML acceleration:
  • dotnet add package Microsoft.AI.Foundry.Local.WinML

3. Example Python installation

• pip install foundry-local-sdk
• pip install agent-framework
  (Exact pip package names may vary across releases; the sample repo shows exact names. If pip cannot find the package, clone/from-source in the foundry-samples repo.)

4. The Foundry CLI (catalog management)
   Foundry exposes a catalog of local model aliases and (often) a CLI for listing/downloading models. CLI names vary by release (examples you may see in docs: foundryctl, foundry). Typical CLI flow:

• foundryctl catalog list
• foundryctl catalog inspect phi-4-mini
• foundryctl model download phi-4-mini –path /path/to/foundry/models

If your platform’s docs show a different CLI name, use that. The initial model download can be large; download location and cache are configurable in the runtime docs.

5. Choosing a model

• Check alias metadata for VRAM/disk estimates and license.
• If you have limited VRAM, pick smaller or quantized variants.
• Common small aliases: phi-4-mini, phi-2-mini, qwen-7b-quant (names change — check the catalog).

Part B — Copy‑paste ready C# example (Windows .NET 7 + WinML)

Important: package names and API surfaces can change between SDK releases. The commands below use package names commonly seen in the Microsoft samples. If NuGet packages change, run the dotnet add package commands without versions to get the latest packages, and refer to the foundry-samples repo for exact Program.cs if you encounter API differences.

1. Project setup (commands)

• dotnet new console -n FoundryAgentWinML
• cd FoundryAgentWinML
• dotnet add package Microsoft.Agents.AI
• dotnet add package Microsoft.Agents.AI.Foundry –prerelease
• dotnet add package Microsoft.AI.Foundry.Local.WinML
• (optional) dotnet add package Microsoft.Extensions.Hosting

2. Example Program.cs (copy into Program.cs)
   (This example shows the pattern: create Foundry local client, wrap in MAF chat agent, and run a prompt. Adjust namespaces if your SDK version uses slightly different names.)

using System;
using System.Threading.Tasks;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

class Program
{
static async Task Main(string[] args)
{
// Read model alias from environment or use a default
var modelAlias = Environment.GetEnvironmentVariable(“FOUNDRY_LOCAL_MODEL”) ?? “phi-4-mini”;

    Console.WriteLine($"Using Foundry local model: {modelAlias}");

    // Create a FoundryLocalClient (provider glue). Exact constructor may vary by SDK version.
    var foundryClient = new FoundryLocalClient(model: modelAlias);

    // Create agent wrapper using a ChatClientAgent helper (example API)
    var agentOptions = new ChatClientAgentOptions
    {
        SystemPrompt = "You are a helpful assistant that summarizes text concisely."
    };

    var agent = ChatClientAgent.FromChatClient(foundryClient, agentOptions);

    var input = "Summarize the plan for the project in one sentence.";
    Console.WriteLine($"Sending prompt: {input}");

    var result = await agent.RunAsync(input);
    Console.WriteLine("Agent response:");
    Console.WriteLine(result);
}
}

3. Build and run

• Open PowerShell and set the model alias:
  • $env:FOUNDRY_LOCAL_MODEL = “phi-4-mini”
• dotnet build
• dotnet run

Notes

• On first run, Foundry Local will download and prepare model artifacts. Check the console logs for model download progress.
• If you want to pass the model explicitly instead of using an env var, call the FoundryLocalClient constructor with the desired alias (see SDK docs).

Part C — Copy‑paste ready Python example (cross-platform)

1. Create virtual environment and install (adjust if package names differ)

• python -m venv venv
• source venv/bin/activate (macOS/Linux)
• venv\Scripts\Activate.ps1 (Windows PowerShell)
• pip install agent-framework foundry-local-sdk

If PyPI names differ or packages aren’t present, clone the sample repo and install from source.

2. requirements.txt (example)
   agent-framework
   foundry-local-sdk
3. main.py (copy into your project)
   import os
   import asyncio

from agent_framework import Agent
from agent_framework.foundry import FoundryLocalClient

async def main():
model_alias = os.environ.get(“FOUNDRY_LOCAL_MODEL”, “phi-4-mini”)
print(f”Using Foundry local model: {model_alias}”)

# Create Foundry client (constructor may vary)
client = FoundryLocalClient(model=model_alias)

# Create a simple agent wrapper — adjust arguments to match the library you installed
agent = Agent(chat_client=client, instructions="You are a brief assistant that summarizes text.")

response = await agent.run("Explain Docker in one sentence.")
print("Agent response:", response)

if name == “main“:
asyncio.run(main())

4. Run

• export FOUNDRY_LOCAL_MODEL=”phi-4-mini” (macOS/Linux)
• $env:FOUNDRY_LOCAL_MODEL = “phi-4-mini” (Windows PowerShell)
• python main.py

Notes

• Use the sample repo’s Python examples to get exact import paths if the package you installed exposes different modules.
• On first run the Foundry runtime will download the model. Monitor logs.

Part D — Configure Foundry Local without env var (programmatic control)
Instead of environment variables, pass the model alias when you create the client:

• C#:
  var foundryClient = new FoundryLocalClient(model: “qwen2.5-1.5b-instruct”);
• Python:
  client = FoundryLocalClient(model=”qwen2.5-1.5b-instruct”)

This is useful for runtime selection, multi-agent scenarios, or when you want config inside your app.

Hardware, drivers and model sizing (practical guidance)

• NVIDIA GPUs: install NVIDIA drivers + CUDA toolkit compatible with the Foundry runtime. Many ONNX/WinML optimizations target CUDA 11.x; check Foundry docs for the exact CUDA/cuDNN versions required for a given release. Verify installation with:
  • nvidia-smi
• AMD GPUs: ROCm support varies by OS and GPU generation. Check ROCm compatibility guide.
• Windows DirectML / WinML: WinML provides DirectML acceleration; keep Windows and GPU drivers up-to-date. For Intel GPUs, install the latest Graphics drivers.
• VRAM and disk: model sizes and VRAM requirements are model-specific. Smaller models and quantized variants (4-bit/8-bit) are recommended for constrained devices. Use the Foundry catalog to inspect model metadata (size and suggested device types).
• If GPU memory is insufficient, pick (a) a smaller model, (b) a quantized variant, or (c) fall back to CPU execution (slower).

What to look for in the Foundry catalog

• Alias name
• Disk size and estimated VRAM
• Quantization variants offered (4-bit/8-bit)
• License and usage restrictions

Observability and logging

• Enable MAF OpenTelemetry integration to capture agent spans (system prompt, tool calls, model inference).
• Foundry Local logs (model download, provider selection, errors) appear in the runtime output. If you start Foundry as a background service, logs typically go to console files or a configured log directory — check the Foundry docs for the exact log file location on your OS.
• Example telemetry flow (conceptual):
  • Start tracing in your app (OpenTelemetry SDK).
  • Agent spans: pre-processing (prompt assembly), model inference (Foundry span), post-processing (tool calls).
  • Use traces to identify slow stages (model load vs. token-by-token decoding).

Troubleshooting checklist (concrete remedies)

1. Model not found / invalid alias

• Confirm alias with the Foundry catalog CLI:
  • foundryctl catalog list
  • foundryctl catalog inspect
• Ensure FOUNDRY_LOCAL_MODEL is set correctly.

2. First run stalls on download

• Check network connectivity and disk space.
• Watch Foundry log lines showing download progress.
• Consider pre-downloading models on CI machines to avoid repeated downloads.

3. Slow inference

• Confirm GPU provider selection: check Foundry logs for “selected execution provider” lines.
• Ensure GPU drivers and runtimes are properly installed (nvidia-smi, rocminfo).
• Use a smaller or quantized model if GPU not available.

4. Out-of-memory / VRAM errors

• Use smaller model alias or quantized variant.
• Use CPU execution for lower memory devices.
• If running multiple models concurrently, reduce concurrency or run only one model at a time.

5. API/namespace mismatches

• If compilation fails due to missing types/namespaces, check the sample repo for the exact package and API names for your SDK version. The foundry-samples and agent-framework samples are the definitive, copy‑paste-ready references.

6. Tooling and hosted features unavailable

• Foundry Local is a local chat client. Some hosted Foundry tools (hosted web search, hosted code interpreter) are not available locally. Build local replacements or use Foundry hosted services when you need managed tools.

Forensics & logs: where to look

• Application logs (your process) — model client creation and errors.
• Foundry runtime logs — download progress, execution provider selection.
• OS and GPU driver logs (nvidia-smi, dxdiag on Windows).
• CI logs for model download step (cache model artifacts to speed repeated runs).

CI/CD and production considerations

• Avoid repeated large downloads in ephemeral CI runners by caching the model artifacts. Use a build cache or artifact store with pre-downloaded model files.
• For smoke tests, use small local models or mocked chat clients to validate agent logic without heavy downloads.
• Memory budgeting: if multiple agents or other services use the same GPU, coordinate startup to avoid OOM.
• Hybrid deployment: run smaller on-device models for latency/privacy, and use hosted Foundry for heavy tooling or when you need managed, up-to-date models and scalable inference.

Security and licensing checklist

• Check model license in the Foundry catalog — confirm commercial usage terms if applicable.
• Store no secrets in code. Foundry Local does not require cloud API keys for local inference, but MAF or other integrations might — use secure stores.
• Limit permissions on model cache directories and follow OS best practices for process isolation.

Performance tuning tips

• Batch inference when possible (if the agent supports multiple concurrent requests).
• Use quantized model variants for lower memory and faster CPU inference; be conscious of potential accuracy trade-offs.
• Prefer GPU acceleration when available — it typically reduces latency per request significantly.
• Warm-up the model after download by running a small inference to optimize runtime caches.

Appendix: Useful command snippets (summary)

Set env var

• Windows PowerShell:
  • $env:FOUNDRY_LOCAL_MODEL = “phi-4-mini”
• macOS / Linux:
  • export FOUNDRY_LOCAL_MODEL=”phi-4-mini”

Dotnet project (example)

• dotnet new console -n FoundryAgentDemo
• dotnet add package Microsoft.Agents.AI
• dotnet add package Microsoft.Agents.AI.Foundry –prerelease
• dotnet add package Microsoft.AI.Foundry.Local
• dotnet run

Python virtualenv

• python -m venv venv && source venv/bin/activate
• pip install -r requirements.txt
• python main.py

Foundry CLI (example patterns — CLI name may vary)

• foundryctl catalog list
• foundryctl catalog inspect phi-4-mini
• foundryctl model download phi-4-mini –path /path/to/models

Where to get canonical examples

• Foundry-samples on GitHub: microsoft-foundry/foundry-samples (C# and platform-specific samples)
• Agent Framework repo: microsoft/agent-framework (sample projects for C# and Python)
• Microsoft Learn Foundry Local docs: (Foundry Local get-started & SDK reference)
  If any command or API fails, consult those repos for exact, copy-paste-ready Program.cs and main.py.

Foundry Local + MAF gives you an approachable path to local agents that respect privacy and latency constraints. The main friction is model selection and the first-time download/optimization. Start with the official sample repos (foundry-samples and agent-framework) for exact API versions, try a small model (phi-4-mini) for initial experiments, and iterate to larger/quantized models as your hardware allows

Note: The initial draft of this post was written by BlogWriter and then edited by Jesse Liberty
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

Why this matters
Choosing between a Responses client and a Chat Completion client in Microsoft Agent Framework affects which provider API and hosted tools your agent can use, how easy it is to migrate, and what models/back ends you can target. That can influence development effort, feature availability (hosted code execution, file search, image generation, structured outputs), and runtime portability.

High-level comparison

• Responses client: wraps the newer Responses API (recommended). Exposes a broad hosted-tool surface (hosted code interpreter, hosted file & web search, image generation, hosted model-completion-providers (MCP), structured/typed outputs, and long-running or background/stateful responses). It is best for modern, full-featured agents and Foundry/Azure OpenAI deployments.
• Chat Completion client: wraps the classic Chat Completions API surface. Supports a smaller set of integrations (function-like tools, web search integrations, and local MCPs) and offers broader model/back-end compatibility today. Useful for legacy integrations, older runtimes, or when Go-only support is required.

Agent-level parity
From the Agent Framework developer perspective, both client types can be wrapped into an agent (for example, ChatClientAgent/ChatAgent or AIAgent wrappers). The agent programming model—adding middleware and tools, streaming behavior, sessions, and calling agent.RunAsync—looks the same. The practical differences are primarily the underlying provider API and which tools and structured responses the agent can use.

Feature differences (what you get with Responses vs. Chat Completion)

• Responses client (richer feature set)
  • Hosted tools: hosted code execution (Hosted Code Interpreter), hosted file search, hosted web search, hosted MCPs, image generation. This is what we do in the demo program BlogWriter.
  • Structured and typed outputs: direct support for structured response formats and schema-like outputs.
  • Long-lived or background/stateful responses: support for tasks that can run/continue beyond a single request (callbacks, async background work, persistent contexts).
  • Better integration with Foundry/Azure OpenAI advanced features.
• Chat Completion client (compatibility-focused)
  • Classic chat-completions features and function-style tools.
  • Local MCP integrations and web search via function/tools.
  • Broader compatibility with older models and provider runtime implementations.

Compatibility and portability

• Choose Chat Completion client when you must target older models or runtimes that do not yet expose the Responses API, or when you need the broadest cross-provider compatibility. Agent Framework’s current Go path is aligned to the Chat Completion client, making it the practical choice for Go-only environments.
• Choose Responses client when you deploy to providers that support the Responses API (Foundry, Azure OpenAI) and when you need hosted tools and structured outputs.

Tiny runnable examples

Responses client (recommended pattern)

• Required using statements:
  using Azure.AI.OpenAI;
  using Microsoft.Agents.AI; // (conceptual; align with your Agent Framework namespaces)
• Pattern:
  var client = new OpenAIClient(“”);
  var responsesClient = client.GetResponsesClient();
  AIAgent agent = responsesClient.AsAIAgent(model: “gpt-4o-mini”, instructions: “You are a helpful coding assistant.”);
  var result = await agent.RunAsync(“Write a Python function to sort a list.”);
  Console.WriteLine(result);
• Expected behavior: prints a Python function that sorts a list. The agent can also invoke hosted tools (if enabled) for code execution, file search, etc.

C# — Chat Completion client

• Pattern:
  var client = new OpenAIClient(“”);
  var chatClient = client.GetChatClient(“gpt-4o-mini”);
  AIAgent agent = chatClient.AsAIAgent(instructions: “You are good at telling jokes.”);
  var result = await agent.RunAsync(“Tell me a joke about a pirate.”);
  Console.WriteLine(result);
• Expected behavior: prints a joke about a pirate. Tooling is limited to chat-completions-style integrations.

Migration and practical gotchas

• Feature parity is not 1:1. If you migrate from Chat Completion to Responses, confirm the hosted tools you need exist and behave the same (especially structured outputs and background tasks).
• Streaming and rate limits: Responses may differ in streaming semantics and rate limits per provider; test streaming handlers and error handling.
• Tool availability: Not all providers expose the same hosted tools. Verify Foundry/Azure OpenAI capabilities in your deployment target.
• Structured outputs: If your app relies on function-like JSON outputs, test parsing and schema enforcement under Responses.

Conclusion / recommendation
For new projects, prefer the Responses client: it unlocks hosted tools, structured outputs, and modern provider features. Use the Chat Completion client when backward compatibility, legacy models, or Go-only constraints dictate it. Because both client types integrate under the same agent abstraction, migrating is mostly about swapping the client and validating tool-specific behaviors