// Build .NET AI agents and multi-agent workflows with Microsoft Agent Framework using the right agent type, threads, tools, workflows, hosting protocols, and enterprise guardrails.
Build provider-agnostic .NET AI integrations with `Microsoft.Extensions.AI`, `IChatClient`, embeddings, middleware, structured output, vector search, and evaluation.
Build or review distributed .NET applications with Orleans grains, silos, persistence, streaming, reminders, placement, testing, and cloud-native hosting.
Design or refine CI/CD workflows, quality gates, release flow, and safe AI-assisted pipeline authoring. Use when adding or changing build pipelines, release stages, IaC-driven environments, or deployment rollback policy.
Set up or refine solution-level governance for MCAF repositories: root and project-local `AGENTS.md`, rule precedence, solution topology, skill routing, and maintainability-limit policy placement. Use when bootstrapping a repo, restructuring a multi-project solution, or tightening agent rules.
Add or update automated tests for a change using the repository’s verification rules in `AGENTS.md`. Use when implementing a feature, bugfix, refactor, or regression test; prefer stable integration/API/UI coverage and pull deeper test strategy from the bundled references.
| name | dotnet-microsoft-agent-framework |
| version | 1.4.0 |
| category | AI |
| description | Build .NET AI agents and multi-agent workflows with Microsoft Agent Framework using the right agent type, threads, tools, workflows, hosting protocols, and enterprise guardrails. |
| compatibility | Requires preview-era Microsoft Agent Framework packages and a .NET application that truly needs agentic or workflow orchestration. |
.NET code that uses Microsoft.Agents.*, Microsoft.Extensions.AI, AIAgent, AgentThread, or Agent Framework hosting packagesChatClientAgent, Responses agents, hosted agents, custom agents, workflows, or durable agentsAIAgent, explicit Workflow, Azure Functions durable agent, ASP.NET Core hosted agent, AG-UI remote UI, or DevUI local debugging.AgentThread. Treat serialized threads as opaque provider-specific state.flowchart LR
A["Task"] --> B{"Deterministic code is enough?"}
B -->|Yes| C["Write normal .NET code or a plain workflow"]
B -->|No| D{"One dynamic decision-maker is enough?"}
D -->|Yes| E["Use an `AIAgent` / `ChatClientAgent`"]
D -->|No| F["Use a typed `Workflow`"]
F --> G{"Needs durable Azure hosting or week-long execution?"}
G -->|Yes| H["Use durable agents on Azure Functions"]
G -->|No| I["Use in-process workflows"]
E --> J{"Need a remote protocol or UI?"}
F --> J
J -->|OpenAI-compatible HTTP| K["ASP.NET Core Hosting.OpenAI"]
J -->|Agent-to-agent protocol| L["A2A hosting"]
J -->|Web UI protocol| M["AG-UI"]
J -->|Local debug shell| N["DevUI (dev only)"]
AIAgent is the common runtime abstraction. It should stay mostly stateless.AgentThread holds conversation identity and long-lived interaction state. Treat serialized thread payloads as opaque provider-owned data.AgentResponse and AgentResponseUpdate are not just text containers. They can include tool calls, tool results, structured output, reasoning-like updates, and response metadata.ChatClientAgent is the safest default when you already have an IChatClient and do not need a hosted-agent service.Workflow is an explicit graph of executors and edges. Use it when the control flow must stay inspectable, typed, resumable, or human-steerable.| If you need | Default choice | Why |
|---|---|---|
| One model-backed assistant with normal .NET composition | ChatClientAgent or chatClient.AsAIAgent(...) | Lowest friction, middleware-friendly, works with IChatClient |
| OpenAI-style future-facing APIs, background responses, or richer response state | Responses-based agent | Better fit for new OpenAI-compatible integrations |
| Simple client-managed chat history | Chat Completions agent | Keeps request/response simple |
| Service-hosted agents and service-owned threads/tools | Azure AI Foundry Agent or other hosted agent | Managed runtime is the requirement |
| Typed multi-step orchestration | Workflow | Control flow stays explicit and testable |
| Week-long or failure-resilient Azure execution | Durable agent on Azure Functions | Durable Task gives replay and persisted state |
| Agent-to-agent interoperability | A2A hosting or A2A proxy agent | This is protocol-level delegation, not local inference |
| Browser or web UI protocol integration | AG-UI | Designed for remote UI sync and approval flows |
AgentThread, stores, or workflow state.IChatClient agents as if they share the same thread and tool guarantees.AgentThread lifecycle, serialization, and compatibility boundaries are explicitWhen a decision depends on exact wording, long-tail feature coverage, or a less-common integration, check the local official docs snapshot before relying on summaries.
AgentThread, chat history storage, reducers, context providers, and thread serializationIChatClient middleware with guardrail patterns