Jesse Liberty

This guide assumes you already understand what Spec Kit and presets are and focuses on the who/what/where/how of authoring, testing, and publishing a preset. The instructions are concrete and practical — including a minimal manifest example, the recommended folder layout, local test workflow, a tiny C# validation snippet, and packaging/publishing notes.

Your design docs look different across teams. Some repos forget the QA gate. Integrations (Jira, CI) are half-baked and duplicated as bash scripts. Onboarding a new engineer requires five manual steps to wire the same set of templates, commands, and pipelines.

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.

When working with agents (e.g., in Microsoft Agent Framework) it is easy to be confused as to when the LLM is called. Since calling the LLM (and getting responses) costs money (in the form of expended tokens) it is important to understand this relationship.

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).

tl;dr

• 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.
  
  

Run a full Microsoft Agent Framework (MAF) agent entirely on-device to eliminate round trips to the cloud, reduce latency, avoid egress costs, and keep sensitive data private. With Foundry Local you can run optimized local model variants (ONNX/WinML) and wire them directly into MAF.

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.

TL;DR
Use the Responses client for new projects if you want the newest, richest hosted tools and structured outputs; use the Chat Completion client when you need maximum backward compatibility or are constrained to the Chat-completions API (for example, Go-only paths or older models).

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.

BlogWriter uses the Responses API which can help with state maintenance. BlogWriter, however, implements important state (context) using a session object, and manages long-term memory by writing to a Cosmos Database.

I’m reusing this image because (a) it is apt and (b) he’s so cute!

In a previous blog post I promised to take apart the BlogWriter architecture and implementation. I thought today I’d start with the architecture.

The original design was to have 4 agents:
* BlogWriter (orchestrates the other agents)
* Researcher (searches the web and Microsoft Learn)
* Author (writes the blog post)
* Reviewer (either accepts the post or sends back fixes to the author)

Subsequently we moved the agents to Foundry (see this video and the diagram above). Critical to this new architecture is that the four Foundry-based agents are fully independent, and each lives in its own project. All the work is done by these agents.