Microsoft Agent Framework

Microsoft Agent Framework

Trigger On

• building or reviewing .NET code that uses Microsoft.Agents.*, Microsoft.Extensions.AI, AIAgent, HarnessAgent, AgentThread, AgentSession, or Agent Framework hosting packages
• choosing between ChatClientAgent, Responses agents, hosted agents, custom agents, Anthropic agents, workflows, or durable agents
• adding the batteries-included Microsoft.Agents.AI.Harness surface for planning, todos, compaction, file memory/access, tool approvals, skills, shell execution, or background agents
• authoring preview-era Microsoft.Agents.AI.Workflows.Declarative* packages or wrapping a workflow with workflow.AsAIAgent()
• adding tools, MCP, A2A, OpenAI-compatible hosting, AG-UI, DevUI, background responses, or OpenTelemetry
• migrating from Semantic Kernel agent APIs or aligning AutoGen-style multi-agent patterns to Agent Framework
• using Anthropic Claude models (haiku, sonnet, opus) via AnthropicClient or through Azure Foundry with AnthropicFoundryClient

Workflow

1. Decide whether the problem should stay deterministic. If plain code or a typed workflow without LLM autonomy is enough, do that instead of adding an agent.
2. Choose the execution shape first: single AIAgent, batteries-included HarnessAgent, explicit programmatic Workflow, workflow-as-agent wrapper, declarative workflow when YAML portability is explicitly required, Azure Functions durable agent, ASP.NET Core hosted agent, AG-UI remote UI, or DevUI local debugging.
3. Choose the agent type and provider intentionally. Prefer the simplest agent that satisfies the threading, tooling, and hosting requirements.
4. Keep agents stateless and keep conversation or long-lived state in provider-owned session objects. Most persistence guidance still centers on AgentThread, while newer middleware and background-response examples may surface AgentSession. Treat both as opaque provider-specific state.
5. Add only the tools and middleware that the scenario needs. Narrow the tool surface, require approval for side effects, and treat MCP, A2A, and third-party services as trust boundaries.
6. For workflows, model executors, edges, typed RequestPort boundaries, checkpoints, shared state, and human-in-the-loop explicitly rather than hiding control flow in prompts.
7. Prefer Responses-based protocols for new remote/OpenAI-compatible integrations unless you specifically need Chat Completions compatibility.
8. Use durable agents only when you truly need Azure Functions serverless hosting, durable thread storage, or deterministic long-running orchestrations.
9. Verify preview status, package maturity, docs recency, and provider-specific limitations before locking a production architecture.

Current Upstream Notes

• dotnet-1.15.0 adds public OpenAI Responses protocol helpers, session deletion, and hosted workflow state. The application still owns routing, authorization, and durable storage.
• dotnet-1.14.0 graduates the core Harness API but keeps its package and advanced options prerelease or experimental. It also makes file access opt-in, binds approvals to surfaced requests, and splits AG-UI packages and server registration. See harness.md and hosting.md.
• Current AG-UI hosting uses Microsoft.Agents.AI.Hosting.AGUI.AspNetCore with AddAGUIServer() and MapAGUIServer(...); the client uses AGUI.Client, and conversation state flows through AgentSession. Do not copy older AddAGUI/MapAGUI or AgentThread hosting examples into current applications.
• The August 2026 documentation set is mirrored as 172 current markdown pages and now treats middleware, function tools and approvals, sessions, multimodal input, background responses, Azure Functions durable agents, AG-UI frontend and backend tools, MCP-hosted agents, observability, support, upgrades, and Semantic Kernel or AutoGen migration as first-class paths. Load the matching reference file before implementation and verify package maturity plus exact signatures against the linked official page; the expanded documentation does not make every provider or preview feature interchangeable.

Architecture

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| O{"Needs a packaged long-task runtime?"}
  O -->|No| E["Use an `AIAgent` / `ChatClientAgent`"]