Skip to content
MfC#

Microsoft Agent Framework (.NET) — Advanced Patterns

Workflows exposed as agents, agents exposed as chat clients and tools, and pointers to Foundry-defined agents and agent middleware in Microsoft.Agents.AI.

Checked against Microsoft.Agents.AI 1.28.0 on 2026-11-19; every C# block compiles against that release. Deployment, resilience and security are on the production guide.

Everything in the framework converts to and from AIAgent, which is what makes the pieces compose. This page collects the conversions:

FromToHowCovered
An IChatClient or provider clientAIAgentAsAIAgent(...), new ChatClientAgent(...)Providers
A Foundry agent definitionAIAgentproject.AsAIAgent(agentVersion) → FoundryAgentProviders
An AIAgentA wrapped AIAgentagent.AsBuilder().Use(...), DelegatingAIAgentMiddleware
An AIAgentA toolagent.AsAIFunction()Tools
An AIAgentAn MCP toolMcpServerTool.Create(agent.AsAIFunction())MCP
An AIAgentAn IChatClientagent.AsIChatClient() (experimental)below
A workflowAIAgentworkflow.AsAIAgent(...)below

Microsoft.Agents.AI.Foundry (preview) gives you two kinds of agent from an AIProjectClient: a ChatClientAgent over a model in the project, with the agent defined in your code, and a FoundryAgent over an agent defined and versioned in Foundry with its hosted tools. Both, the server-side conversation options, hosted-agent sessions, and the deprecated classic Persistent Agents package, are covered on the providers page. Foundry’s hosted tools are on the tools page, Foundry Memory on the sessions and memory page, and running your own code as a Foundry hosted agent on the hosting page.

Agent-level middleware (agent.AsBuilder().Use(...) with run delegates, function-invocation callbacks, or a DelegatingAIAgent subclass) and chat-client middleware (ChatClientBuilder.Use(...)) are on the middleware page, with ordering, streaming, short-circuiting, retries and error handling.

agent.AsIChatClient() (experimental MAAI001) presents an agent as an IChatClient, for libraries and frameworks that accept only chat clients. By default it accepts only a ChatClientAgent (or a decorator around one), because only then is the mapping from ChatOptions well defined. Pass a session to keep the agent’s history across calls through the client; without one, each call stands alone and the caller sends the history. allowNonChatClientAgents: true wraps any agent (A2A, Copilot, a workflow agent), but then only ChatOptions.ResponseFormat reaches the agent; tools, instructions, temperature and the other options are silently ignored.

#pragma warning disable MAAI001
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;
AIAgent agent = new OpenAIClient(Environment.GetEnvironmentVariable("OPENAI_API_KEY")!)
.GetChatClient("gpt-6.1-sol")
.AsIChatClient()
.AsAIAgent(instructions: "You answer in one sentence.", name: "one-liner");
AgentSession session = await agent.CreateSessionAsync();
IChatClient asClient = agent.AsIChatClient(session); // history kept in the session
ChatResponse first = await asClient.GetResponseAsync("What is HTTP?");
ChatResponse second = await asClient.GetResponseAsync("And HTTPS?");
Console.WriteLine(first.Text);
Console.WriteLine(second.Text);
Console.WriteLine($"conversation id reported to the caller: {second.ConversationId}");

workflow.AsAIAgent(...) turns a workflow whose input is a list of chat messages (any AgentWorkflowBuilder workflow qualifies) into an AIAgent. A multi-agent pipeline can then be called, hosted or used as a tool exactly like a single agent.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;
public static class Pipeline
{
public static async Task<string> RunAsync(IChatClient chatClient, string topic)
{
AIAgent researcher = new ChatClientAgent(chatClient, instructions: "List the key facts about the topic.", name: "researcher");
AIAgent writer = new ChatClientAgent(chatClient, instructions: "Turn the facts into one paragraph.", name: "writer");
AIAgent pipeline = AgentWorkflowBuilder.BuildSequential(researcher, writer)
.AsAIAgent(name: "research-pipeline");
AgentResponse response = await pipeline.RunAsync(topic);
return response.Text;
}
}

Requests raised inside the workflow (a RequestPort waiting for a person, or a tool waiting for approval) come back on the agent’s response as user-input requests. The .NET feature tour covers request ports and checkpointing; the orchestration patterns (sequential, concurrent, handoff, group chat, Magentic) are in the comprehensive guide.