Microsoft Agent Framework

Trigger On

• building or reviewing .NET code that uses Microsoft.Agents.*, Microsoft.Extensions.AI, AIAgent, AgentThread, AgentSession, or Agent Framework hosting packages
• choosing between ChatClientAgent, Responses agents, hosted agents, custom agents, Anthropic agents, workflows, or durable 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, 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, request-response ports, 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.

Deliver

• a justified architecture choice: agent vs workflow vs durable orchestration
• the concrete .NET agent type, provider, and package set
• an explicit thread, tool, middleware, and observability strategy
• hosting and protocol decisions for OpenAI-compatible APIs, A2A, AG-UI, or Azure Functions
• migration notes when replacing Semantic Kernel agent APIs or AutoGen-style orchestration

Validate

• the scenario really needs agentic behavior and is not better served by deterministic code
• the selected agent type matches the provider, thread model, and tool model
• AgentThread or AgentSession lifecycle, serialization, and compatibility boundaries are explicit for the chosen provider surface
• tool approval, MCP headers, and third-party trust boundaries are handled safely
• workflows define checkpoints, request-response, shared state, and HITL paths deliberately
• DevUI is treated as a development sample, not a production surface
• docs or packages marked preview are called out, and Python-only docs are not mistaken for guaranteed .NET APIs

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

References

Related skills

Related agents