Connect a Microsoft Agent Framework Agent to an MCP Server

In the previous post, we added a function tool to a Microsoft Agent Framework agent. The function was implemented inside our .NET application, which works well when the capability belongs to the application itself.

But what if the capability is provided by another service? This is where the Model Context Protocol (MCP) is useful. An MCP server can expose tools and their descriptions through a standard protocol. Our agent can discover those tools at runtime and invoke them without us writing a separate integration for every tool.

In this post, we are going to connect our Agent Framework agent to the public Microsoft Learn MCP Server. The agent will discover the available documentation tools and use them to answer a Microsoft Graph question with current information from Microsoft Learn.

What we are building

• Create a .NET console application.
• Connect an MCP client to a remote MCP server.
• Discover the tools exposed by the server.
• Make those tools available to an Agent Framework agent.
• Ask a question that requires current Microsoft documentation.
• Let Agent Framework handle the MCP tool call and its result.

Before you start

You will need:

• .NET 10 SDK. Agent Framework supports .NET 8 or later; I am using .NET 10 for this example.
• An Azure subscription.
• A Microsoft Foundry project.
• A model deployment that supports function calling.
• An identity with permission to use the Foundry project and model.

We will use the public Microsoft Learn MCP Server at https://learn.microsoft.com/api/mcp. It uses Streamable HTTP and does not require authentication.

1) Create the .NET project

Create a new console application:

dotnet new console -n AgentWithMCP --framework net10.0
cd AgentWithMCP

2) Install the required packages

Install the Agent Framework Foundry integration, Azure authentication, and the official MCP C# SDK:

dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.Identity
dotnet add package ModelContextProtocol

ModelContextProtocol provides the MCP client and transports. The MCP tools it discovers are compatible with the AITool abstraction from Microsoft.Extensions.AI.

3) Where MCP fits

The request in this example follows this path:

User
  -> Microsoft Agent Framework agent
      -> MCP client
          -> Microsoft Learn MCP Server
              -> Microsoft Learn content

The agent still decides when a tool is needed. The difference from our previous post is where the tool comes from. Instead of defining the function in our application, we discover it from an MCP server.

MCP is the capability boundary. The agent does not need custom code for the Microsoft Learn search, fetch, and code sample operations.

4) Connect to the MCP server

Create an HttpClientTransport with the MCP endpoint, then use it to create an McpClient:

const string mcpEndpoint = "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000";

await using McpClient mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(new()
    {
        Endpoint = new Uri(mcpEndpoint),
        Name = "Microsoft Learn MCP"
    }));

The Microsoft Learn MCP Server uses Streamable HTTP. The C# SDK negotiates the connection and handles the MCP protocol messages for us.

I have also added maxTokenBudget=2000 to limit the amount of content returned by search operations. This is useful when tools are called inside an agent loop because tool results consume context tokens.

5) Discover the MCP tools

MCP tools should be discovered at runtime rather than hardcoded. Call ListToolsAsync after connecting:

IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();

Console.WriteLine("MCP tools available:");
foreach (McpClientTool tool in mcpTools)
{
    Console.WriteLine($"- {tool.Name}: {tool.Description}");
}

At the time of writing, the server returns these tools:

• microsoft_docs_search
• microsoft_docs_fetch
• microsoft_code_sample_search

The important part is that our application does not define this list. The MCP server supplies each tool's name, description, and input schema. If the server adds or changes tools, the client can discover the current contract the next time it connects.

6) Make the MCP tools available to the agent

Convert the discovered tools to AITool and pass them to the agent:

AIAgent agent = projectClient.AsAIAgent(
    model: modelDeployment,
    instructions: instructions,
    name: "MicrosoftLearnAssistant",
    tools: [.. mcpTools.Cast<AITool>()]);

This is the bridge between MCP and Agent Framework. The model sees the tool descriptions discovered from the server and can decide which tool to call based on the user's question.

We will use the following instructions:

const string instructions = """
    You help developers find current information in Microsoft Learn.
    Always use the available Microsoft Learn tools before answering.
    Base the answer on the tool results and include relevant Microsoft Learn links.
    """;

7) Complete working example

Here is the complete Program.cs:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string modelDeployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

const string mcpEndpoint = "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000";

Console.WriteLine($"Connecting to MCP server at {mcpEndpoint} ...");

await using McpClient mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(new()
    {
        Endpoint = new Uri(mcpEndpoint),
        Name = "Microsoft Learn MCP"
    }));

IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();

Console.WriteLine("MCP tools available:");
foreach (McpClientTool tool in mcpTools)
{
    Console.WriteLine($"- {tool.Name}: {tool.Description}");
}

DefaultAzureCredential credential = new(new DefaultAzureCredentialOptions
{
    ExcludeManagedIdentityCredential = true
});
AIProjectClient projectClient = new(new Uri(endpoint), credential);

const string instructions = """
    You help developers find current information in Microsoft Learn.
    Always use the available Microsoft Learn tools before answering.
    Base the answer on the tool results and include relevant Microsoft Learn links.
    """;

AIAgent agent = projectClient.AsAIAgent(
    model: modelDeployment,
    instructions: instructions,
    name: "MicrosoftLearnAssistant",
    tools: [.. mcpTools.Cast<AITool>()]);

const string prompt = "How do I authenticate a .NET application to Microsoft Graph? Summarize the recommended options.";

Console.WriteLine($"\nUser: {prompt}\n");
Console.WriteLine($"Agent: {await agent.RunAsync(prompt)}");

8) Configure and run the application

The sample reads the Foundry project endpoint and model deployment name from environment variables. In PowerShell, set them like this:

$env:FOUNDRY_PROJECT_ENDPOINT="YOUR_FOUNDRY_PROJECT_ENDPOINT"
$env:FOUNDRY_MODEL="YOUR_MODEL_DEPLOYMENT_NAME"

The model must support function calling. The sample uses DefaultAzureCredential, so sign in with the Azure CLI for local development:

az login
dotnet run

The console first shows the tools discovered from the MCP server:

Connecting to MCP server at https://learn.microsoft.com/api/mcp?maxTokenBudget=2000 ...
MCP tools available:
- microsoft_docs_search: Search official Microsoft/Azure documentation...
- microsoft_code_sample_search: Search for code snippets and examples...
- microsoft_docs_fetch: Fetch a Microsoft Learn documentation webpage...

The agent then uses those tools and returns a summary with links to the relevant Microsoft Learn pages. The exact response and tools selected can vary based on the model and the current tool descriptions.

9) What happens during the MCP tool call

The request goes through the following steps:

1. The MCP client connects to the Microsoft Learn MCP Server.
2. ListToolsAsync retrieves the current tool names, descriptions, and parameter schemas.
3. The discovered tools are supplied to the Agent Framework agent.
4. The user asks a question about Microsoft Graph authentication.
5. The model selects a Microsoft Learn tool and supplies its arguments.
6. The MCP client sends the tool call to the remote server.
7. The server returns the tool result to the MCP client.
8. Agent Framework gives the result back to the model.
9. The model uses the result to produce the final answer.

We do not need to call microsoft_docs_search directly or parse its response in our application. The discovered McpClientTool handles the MCP invocation, and Agent Framework includes the result in the agent's function-calling loop.

Local and remote MCP servers

This example uses a remote server over Streamable HTTP. MCP also supports local servers over standard input and output, usually called stdio transport.

• Streamable HTTP: useful for remote services shared by multiple clients.
• stdio: useful when the client starts and communicates with a local server process.

The tools still reach the agent as AITool instances. Only the transport and connection configuration change.

Authentication and security

The Microsoft Learn MCP Server does not require authentication, which keeps this first example small. Business-system MCP servers commonly require OAuth, bearer tokens, API keys, or custom headers. The MCP C# SDK supports configuring authentication through the HTTP transport and a configured HttpClient.

Treat an MCP server like any other external integration. Only connect to servers you trust, expose only the tools the agent needs, validate sensitive tool arguments, and require approval before actions that create, update, delete, or send data. Never place access tokens directly in source code.

MCP standardizes discovery and invocation. It does not remove our responsibility to authenticate users, authorize operations, and protect data.

Wrapping up

In this post, we connected a Microsoft Agent Framework agent to a remote MCP server. The MCP client discovered the server's tools at runtime, Agent Framework exposed them to the model, and the model used the returned tool results to answer a question with current Microsoft Learn information.

This gives us a clean way to add capabilities that live outside our application. In the next post, we will connect an Agent Framework agent to Microsoft Graph and use Microsoft 365 data to answer a user request.

Hope this helps!

Add Functions and Tools to a Microsoft Agent Framework Agent

In the previous post, we created a Microsoft Agent Framework agent and ran the same agent definition against different models in Microsoft Foundry. The agent could answer questions using the model's existing knowledge, but it could not access any data or operations from our application.

In this post, we are going to give the agent a function tool. We will expose a normal C# function that searches a small meeting room directory, let the model decide when to call it, and return a structured result to the agent.

What we are building

• Create a .NET console application.
• Define a C# function that finds available meeting rooms.
• Describe the function and its parameters for the model.
• Expose the function as an Agent Framework tool.
• Ask the agent a question that requires the tool.
• Return structured room data for the agent to use in its response.

Before you start

You will need:

• .NET 10 SDK. Agent Framework supports .NET 8 or later; I am using .NET 10 for this example.
• An Azure subscription.
• A Microsoft Foundry project.
• A model deployment that supports function calling.
• An identity with permission to use the Foundry project and model.

This post starts from the Foundry setup used in the previous article. If you already have a project endpoint and model deployment, you can reuse them.

1) Create the .NET project

Create a new console application:

dotnet new console -n AgentWithTools --framework net10.0
cd AgentWithTools

2) Install Microsoft Agent Framework packages

Install the Foundry integration and Azure authentication packages:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

The function tool APIs are provided through Microsoft.Extensions.AI, which is brought in by the Agent Framework packages.

3) Define the meeting room data

We will keep the data in memory so that we can focus on how tools work. In a real application, the same function could call Microsoft Graph, a database, or another business API.

First, define the records returned by our function:

record MeetingRoom(
    string Name,
    string City,
    int Capacity,
    bool HasTeamsRoom,
    bool IsAvailable,
    string Location);

record RoomSearchResult(
    string City,
    int MinimumCapacity,
    bool RequiresTeamsRoom,
    IReadOnlyList<MeetingRoom> Rooms);

Then add a few sample rooms:

MeetingRoom[] meetingRooms =
[
    new("Thames", "London", 6, true, true, "2nd floor"),
    new("Regent", "London", 10, true, true, "3rd floor"),
    new("Windsor", "London", 12, false, true, "3rd floor"),
    new("Harbour", "Sydney", 10, true, true, "5th floor"),
    new("Cascade", "Redmond", 8, true, false, "1st floor")
];

4) Create the function tool

A function tool starts as a normal C# function. It can receive strongly typed parameters, execute application code, and return a normal .NET object.

[Description("Find available meeting rooms that match a city, minimum capacity, and Microsoft Teams requirement.")]
RoomSearchResult FindAvailableMeetingRooms(
    [Description("The city where the meeting room must be located.")] string city,
    [Description("The minimum number of people the room must accommodate.")] int minimumCapacity,
    [Description("Whether the room must have Microsoft Teams meeting equipment.")] bool requiresTeamsRoom)
{
    Console.WriteLine($"[Tool] Searching for rooms in {city} for {minimumCapacity} people.");

    MeetingRoom[] matches = meetingRooms
        .Where(room => room.City.Equals(city, StringComparison.OrdinalIgnoreCase))
        .Where(room => room.Capacity >= minimumCapacity)
        .Where(room => room.IsAvailable)
        .Where(room => !requiresTeamsRoom || room.HasTeamsRoom)
        .ToArray();

    return new RoomSearchResult(city, minimumCapacity, requiresTeamsRoom, matches);
}

The Description attributes are important. Agent Framework uses the function signature and descriptions to build the tool schema sent to the model. This tells the model what the tool does and what values it should provide for city, minimumCapacity, and requiresTeamsRoom.

The descriptions do not contain the implementation. The model only sees the tool contract. The C# function itself continues to run inside our application.

5) Make the tool available to the agent

Use AIFunctionFactory.Create to turn the C# function into an AIFunction. We can then pass it to the agent using the tools parameter:

AIAgent agent = projectClient.AsAIAgent(
    model: modelDeployment,
    instructions: instructions,
    name: "MeetingRoomAssistant",
    tools: [AIFunctionFactory.Create(FindAvailableMeetingRooms)]);

We are not calling FindAvailableMeetingRooms directly. We give the model a description of the tool, and the model decides whether it needs the tool based on the user's request.

The instructions also tell the agent when it should use the tool and prevent it from recommending rooms that were not returned by our application:

const string instructions = """
    You help employees find meeting rooms.
    Always use the meeting room tool when the user asks for a room.
    Only recommend rooms returned by the tool and briefly explain why they match.
    """;

6) Complete working example

Here is the complete Program.cs:

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

string endpoint = "YOUR_FOUNDRY_PROJECT_ENDPOINT";
string modelDeployment = "YOUR_MODEL_DEPLOYMENT_NAME";

MeetingRoom[] meetingRooms =
[
    new("Thames", "London", 6, true, true, "2nd floor"),
    new("Regent", "London", 10, true, true, "3rd floor"),
    new("Windsor", "London", 12, false, true, "3rd floor"),
    new("Harbour", "Sydney", 10, true, true, "5th floor"),
    new("Cascade", "Redmond", 8, true, false, "1st floor")
];

[Description("Find available meeting rooms that match a city, minimum capacity, and Microsoft Teams requirement.")]
RoomSearchResult FindAvailableMeetingRooms(
    [Description("The city where the meeting room must be located.")] string city,
    [Description("The minimum number of people the room must accommodate.")] int minimumCapacity,
    [Description("Whether the room must have Microsoft Teams meeting equipment.")] bool requiresTeamsRoom)
{
    Console.WriteLine($"[Tool] Searching for rooms in {city} for {minimumCapacity} people.");

    MeetingRoom[] matches = meetingRooms
        .Where(room => room.City.Equals(city, StringComparison.OrdinalIgnoreCase))
        .Where(room => room.Capacity >= minimumCapacity)
        .Where(room => room.IsAvailable)
        .Where(room => !requiresTeamsRoom || room.HasTeamsRoom)
        .ToArray();

    return new RoomSearchResult(city, minimumCapacity, requiresTeamsRoom, matches);
}

DefaultAzureCredential credential = new(new DefaultAzureCredentialOptions
{
    ExcludeManagedIdentityCredential = true
});
AIProjectClient projectClient = new(new Uri(endpoint), credential);

const string instructions = """
    You help employees find meeting rooms.
    Always use the meeting room tool when the user asks for a room.
    Only recommend rooms returned by the tool and briefly explain why they match.
    """;

AIAgent agent = projectClient.AsAIAgent(
    model: modelDeployment,
    instructions: instructions,
    name: "MeetingRoomAssistant",
    tools: [AIFunctionFactory.Create(FindAvailableMeetingRooms)]);

const string prompt = "Find an available meeting room in London for 8 people. It must have Microsoft Teams equipment.";
Console.WriteLine(await agent.RunAsync(prompt));

record MeetingRoom(
    string Name,
    string City,
    int Capacity,
    bool HasTeamsRoom,
    bool IsAvailable,
    string Location);

record RoomSearchResult(
    string City,
    int MinimumCapacity,
    bool RequiresTeamsRoom,
    IReadOnlyList<MeetingRoom> Rooms);

Change these values:

• YOUR_FOUNDRY_PROJECT_ENDPOINT: the project endpoint from Microsoft Foundry.
• YOUR_MODEL_DEPLOYMENT_NAME: the deployment name of a model that supports function calling.

7) Authenticate and run the application

The sample uses DefaultAzureCredential. For local development, sign in with the Azure CLI:

az login

Then run the console application:

dotnet run

The console first shows the line written by our C# function, followed by the agent's response:

[Tool] Searching for rooms in London for 8 people.

The Regent room is available on the 3rd floor. It seats 10 people and has Microsoft Teams equipment.

The exact wording of the final response can vary. The room itself comes from our function result rather than the model's training data.

8) What happens during the tool call

The request goes through the following steps:

1. The user asks for a room in London for eight people with Teams.
2. The model sees that the meeting room tool can answer the request.
3. The model selects the tool and supplies London, 8, and true as arguments.
4. Agent Framework invokes the C# function in our application.
5. The function returns a structured RoomSearchResult.
6. The model uses that result to create the final response.

The model decides when to request a tool call, but our application remains responsible for executing the function and controlling what it can do.

Why return a structured result?

Our function returns RoomSearchResult instead of a preformatted sentence. This keeps business data separate from presentation. The tool supplies facts such as room name, capacity, equipment, and location, while the agent turns those facts into a useful answer.

This also makes the tool easier to extend later. We could add:

• A room identifier.
• Available time slots.
• Accessibility information.
• A booking URL.

The same pattern works when the function calls a real service. We can replace the in-memory array with Microsoft Graph or an internal API without changing how the agent invokes the tool.

A note about tool safety

This example only reads sample data. Tools that create, update, delete, send, or approve something need additional safeguards. Validate every argument in application code, authorize the current user, and require human approval for sensitive actions.

We will cover human approval and tool interception later in this series. For now, keeping the first tool read-only lets us concentrate on the core function calling flow.

More information

The Microsoft Agent Framework documentation has more details about using function tools with an agent.

Wrapping up

In this post, we turned a normal C# function into a Microsoft Agent Framework tool. The model used the function description and parameters to decide when to call it, Agent Framework executed it locally, and the structured result was used to produce the final answer.

This is the basic pattern for connecting an agent to capabilities owned by your application. In the next post, we will move the integration boundary outside the application and connect the agent to tools exposed by an MCP server.

Hope this helps!

Create a model agnostic Agent using Microsoft Foundry and Microsoft Agent Framework

Microsoft Agent Framework is the evolution of Microsoft's earlier AI orchestration work, bringing together ideas from projects such as Semantic Kernel and AutoGen into a unified framework for building agentic applications. It gives us a common AIAgent abstraction while letting us choose and switch which AI model powers the agent.

In this post, we are going to build a model-agnostic agent in .NET using Microsoft Agent Framework and Microsoft Foundry. We’ll run the same agent definition against two different model providers, OpenAI and DeepSeek, without introducing provider-specific code into our agent.

At a high level, we’ll:

• Create a .NET console application.
• Connect Microsoft Agent Framework to a Microsoft Foundry project.
• Deploy models from two different providers: OpenAI and DeepSeek.
• Run the same agent definition against both models.
• Use Foundry and Agent Framework to keep provider-specific plumbing away from the application.

Prerequisites

You will need:

• .NET 10 SDK. Agent Framework supports .NET 8 or later; I am using .NET 10 for this example.
• An Azure subscription.
• A Microsoft Foundry project.
• An OpenAI model deployment. We’ll use gpt-5.6-terra as the example.
• A DeepSeek model deployment. We’ll use DeepSeek-V3.2 as the example.
• An identity with permission to use the Foundry project and its model deployments.

1) Create the .NET project

Create a new console application:

dotnet new console -n ModelAgnosticAgent --framework net10.0
cd ModelAgnosticAgent

2) Install Microsoft Agent Framework packages

Install the Foundry integration and Azure authentication packages:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

3) Deploy two models from different providers

This is the key part of the example.

We are deliberately not building our application around an OpenAI-specific SDK or model client.

Instead, we’ll deploy two models in Microsoft Foundry:

• OpenAI: gpt-5.6-terra
• DeepSeek: DeepSeek-V3.2

These come from completely different model providers, but our application will access both through the same Foundry project and use the same Agent Framework programming model.

Our application knows how to work with an AIAgent. Foundry handles access to the underlying model deployments.

If we later decide that another model gives us better quality, latency, cost, or capabilities, we don't want that decision to require redesigning the application.

Deploy the OpenAI model

Use:

Microsoft Foundry > Discover > Models > gpt-5.6-terra > Deploy > Default settings

Give the deployment a recognizable name, for example:

gpt-5-6-terra

Deploy the DeepSeek model

Now deploy the second model:

Microsoft Foundry > Discover > Models > DeepSeek-V3.2 > Deploy > Default settings

For example:

deepseek-v3-2

We now have models from two different providers available through the same Foundry project.

4) Configure the Foundry connection

Open your Foundry project and copy its project endpoint.

Microsoft Foundry > <your project> > Overview

It should look similar to:

https://<resource>.services.ai.azure.com/api/projects/<project>

One Foundry project endpoint gives our application access to both model deployments. We are not configuring a different endpoint for each model.

Switching the model therefore becomes a configuration decision rather than an architecture decision.

5) Authenticate to Microsoft Foundry

The sample uses DefaultAzureCredential, so it does not need an API key in the source code. For local development, the easiest option is to sign in with the Azure CLI:

az login

Make sure the signed-in identity has access to the Foundry project and its model deployments. The Azure AI User role is typically enough to run this sample. Depending on your organization, an administrator may need to assign this role for you.

The sample excludes managed identity because it is designed to run locally. For an application hosted in Azure, you can enable managed identity and assign the same required access to that identity.

6) Minimal working example

Here is the minimal console application that consumes our models and provides us with a common abstraction:

Change these values:

• YOUR_FOUNDRY_PROJECT_ENDPOINT: the project endpoint copied in the previous step.
• YOUR_OPENAI_MODEL_DEPLOYMENT_NAME: the name of your OpenAI deployment.
• YOUR_DEEPSEEK_MODEL_DEPLOYMENT_NAME: the name of your DeepSeek deployment.

These must be the deployment names from your Foundry project, not necessarily the underlying model names shown in the model catalog.

7) How the model abstraction works

The important part is the CreateAgent function:

AIAgent CreateAgent(string modelDeployment) =>
    projectClient.AsAIAgent(
        model: modelDeployment,
        instructions: instructions,
        name: "M365Assistant");

It receives a deployment name but returns the same AIAgent abstraction in both cases. The instructions, prompt, and code used to run the agent remain unchanged. We only select a different model deployment.

Both agents are then invoked through the same RunAsync method:

Console.WriteLine(await openAiAgent.RunAsync(prompt));
Console.WriteLine(await deepSeekAgent.RunAsync(prompt));

There is no OpenAI-specific client for one call and a DeepSeek-specific client for the other. That is the value of keeping the application centered on the Agent Framework abstraction.

8) Run the application

Run the console application:

dotnet run

The application sends the same prompt to both agents and prints each response separately. The exact wording will vary because the responses are generated independently by the two models.

We now have the same agent instructions and prompt running against models from two different providers, without changing the application’s programming model.

What “model agnostic” means here

Model agnostic does not mean that every model behaves identically. It means that the application depends on a common agent abstraction instead of a provider-specific client.

The following parts remain the same:

• The Foundry project endpoint.
• The AIAgent abstraction.
• The agent instructions and user prompt.
• The code used to invoke the agent.

Some model characteristics can still differ:

• Response quality and style.
• Latency and cost.
• Context window and token limits.
• Tool calling, structured output, and other model capabilities.

This abstraction makes it much easier to compare models or switch providers, but the selected model should still be tested against the capabilities your application requires.

Wrapping up

In this post, we created one agent definition and ran it against OpenAI and DeepSeek model deployments through the same Microsoft Foundry project. The application works with AIAgent, while the deployment name determines which model powers it.

This gives us a clean boundary for experimenting with different models. We can compare quality, latency, cost, and capabilities without redesigning the application each time we change providers.

Hope this helps!

Build a Custom UI for a Copilot Studio Agent using the Microsoft 365 Agents SDK

Copilot Studio gives you a great “out-of-the-box” chat experience in Teams and Microsoft 365 Copilot. But sometimes you need your own UI: your branding, your layout, your telemetry, and your app’s context. So in this post, let’s wire a Copilot Studio agent into a .NET console “custom UI” using the Microsoft 365 Agents SDK client library. This will help you get started when you want to surface Copilot Studio Agents in your own custom UIs.

Scope note: This is for calling a Copilot Studio agent from your own app UI (not the iframe embed).

On a high level, we’ll:

• Publish a Copilot Studio agent and copy its Microsoft 365 Agents SDK connection string.

• Create an Entra app registration with the CopilotStudio.Copilots.Invoke delegated permission.

• Use MSAL to sign in a user and get a token for the Power Platform API audience.

• Call the agent from a lightweight console “chat UI” using Microsoft.Agents.CopilotStudio.Client.

Prereqs

• A published Copilot Studio agent (and access to its settings).

• .NET SDK installed (any modern LTS is fine).

• Entra ID permission to create an app registration

1) Publish Your Agent And Copy The Agents SDK Connection String

In Copilot Studio:

• Open your agent

• Go to Channels → Web app (or Native app)

• Under Microsoft 365 Agents SDK, copy the connection string.

Note: If your agent uses “Authenticate with Microsoft” or “Authenticate manually”, you’ll see the connection string option (and not the iframe embed code). 

2) Create An Entra App Registration For User Interactive Sign-In

In Azure portal:

• Microsoft Entra ID → App registrations → New registration

• Platform: Public client/native (mobile & desktop)

• Redirect URI: http://localhost (HTTP, not HTTPS)

Then add the delegated permission:

• API permissions → Add a permission

• APIs my organization uses → search Power Platform API

• Delegated permissions → CopilotStudio → CopilotStudio.Copilots.Invoke

3) Create The “Custom UI” (A Console Chat)

This is the bare minimum idea:

• sign in the user (MSAL)

• get a token scoped to the Power Platform API audience (the SDK computes this for you)

• start a conversation

• send messages and stream responses back as activities 

Change these values:

• directConnectUrl = copied from Copilot Studio channel page (Microsoft 365 Agents SDK section).

• tenantId, clientId = from your Entra app registration.

Minimal Working Example

Create and run:

Troubleshooting

• 401/403: confirm delegated permission CopilotStudio.Copilots.Invoke is granted (and admin consent if your tenant requires it). 

• Redirect URI mismatch: make sure the app registration has http://localhost for public client. (The sample uses localhost.) 

• No response text: Copilot Studio responses arrive as a stream of activities—log the full activity payload if you suspect you’re filtering out the wrong activity types.

• Power Platform API missing in permissions picker: follow the sample guidance and tenant configuration notes in the repo.

Notes

• The console app is a clean “backend harness” you can keep as-is, then wrap with an HTTP API for your React front-end to call.

• If you need quick embed-only experiences, the iframe approach is simpler, but it’s not the same as a true custom UI.

Wrapping up

This pattern keeps your agent authored in Copilot Studio, while your product team owns the end-user experience in a custom UI. The key pieces are: connection info from Copilot Studio, Entra delegated permission, MSAL sign-in, then stream activities through the SDK client.

Hope this helps!

Get reasoning summaries from Azure OpenAI Reasoning Models using the Responses API (.NET)

Reasoning models are awesome for multi-step problems, but in real apps you also want some visibility into how the model got there—without exposing full chain-of-thought. In Azure OpenAI, the right pattern is to request a reasoning summary via the Responses API and log/print it next to the final answer.

On a high level, we’ll:

• Deploy or reuse an Azure OpenAI reasoning model deployment

• Call Azure OpenAI using the v1 base URL (/openai/v1/)

• Request a reasoning summary with a chosen reasoning effort

• Print reasoning summary + final answer in a minimal .NET console app

Prereqs

• Azure OpenAI resource + a deployed reasoning-capable model (e.g. GPT-5 reasoning variants)

• .NET 8+

• Latest OpenAI .NET SDK (OpenAI) that includes ResponsesClient and CreateResponseOptions

1) Create (Or Confirm) Your Reasoning Model Deployment

In Azure AI Foundry:

• Click path: Azure AI Foundry portal → OpenAI → Deployments → + Create deployment

• Pick a reasoning model and give it a deployment name (example: gpt-5-mini)

• Keep that deployment name handy (you’ll pass it to the client)

2) Create a Console App + Install the SDK

3) Call the Responses API and Print the Reasoning Summary

This sample is wired to Azure OpenAI’s v1 endpoint and Responses API.

Change these values:

• AZURE_OPENAI_ENDPOINT (your Azure OpenAI resource endpoint)

• AZURE_OPENAI_API_KEY

• AZURE_OPENAI_DEPLOYMENT (your deployment name, not the base model name)

Why “summary” (not full reasoning): Azure OpenAI’s model behavior is centered on reasoning summaries rather than returning raw reasoning_content.

4) Minimal working example

Expected output (example):

 

Troubleshooting

• 404 Not Found: your deployment name is wrong, or the deployment/region doesn’t support Responses API. Start by verifying deployment name in the portal.

• 400 Bad Request: most often you’re not using the v1 base URL (.../openai/v1/).

• No reasoning summary returned: your deployment might not be a reasoning model, or the model chose not to emit a summary. Confirm model capability and try ReasoningSummaryVerbosity = Concise/Detailed if available in your SDK/version.

• Compile errors for Responses types: upgrade the OpenAI .NET SDK class names have changed (e.g., CreateResponseOptions).

• 401 Unauthorized: API key doesn’t match the resource or is missing.

Notes

• Reasoning summaries are the “sweet spot”: better debugging/telemetry without leaking full internal chain-of-thought. Azure’s docs explicitly separate Azure OpenAI from providers that emit reasoning_content.

• If you’re building Copilot/agent experiences, this summary is exactly what you’d stash in app logs or a trace store for support cases. Keep the final answer user-facing.

Wrapping up

If you want a clean, production-friendly way to understand what a reasoning model did without capturing the full chain-of-thought, use the Responses API and print/log the reasoning summary next to the final answer. 

Hope this helps!

Custom AI Agents: Use the Copilot Retrieval API for grounding on SharePoint Content

If you’re building a custom AI agent (Copilot Studio, Agents SDK, or your own app) and you want permission-trimmed content from SharePoint without managing your own vector store, then the Microsoft 365 Copilot Retrieval API is a great solution. 

It’s part of the broader Copilot APIs surface in Microsoft Graph, designed to reuse the same “in-tenant” grounding behavior that Microsoft 365 Copilot uses. To know more about the Copilot APIs have a look at the Microsoft docs: Microsoft Learn

So in this post, lets deep dive into the Copilot Retrieval API:

On a high level, we’ll:

• Decide when to use Retrieval API vs “normal” Graph CRUD/search

• Configure the minimum delegated permissions for SharePoint grounding

• Call the Retrieval endpoint with dataSource=sharePoint

• Scope results to specific sites using KQL filterExpression

• Use the returned extracts + URLs as grounding context for your LLM

Prereqs

• A Microsoft 365 Copilot license for each user calling Copilot APIs (this is separate from standard Graph CRUD usage).

• Your app uses delegated auth (application permissions aren’t supported for this API).

• Microsoft Entra app registration with delegated Graph permissions: Files.Read.All + Sites.Read.All (required together for SharePoint/OneDrive retrieval).

• Familiarity with the Copilot APIs model (Copilot APIs are REST under Microsoft Graph and use standard Graph auth).

1) Pick The Right Tool: Retrieval vs Graph

Use Microsoft Graph CRUD when you need to read/update SharePoint data (lists, drives, items, etc.). 

Use the Copilot Retrieval API when you need ranked text content (snippets) to ground an LLM response, while keeping content in place and respecting permissions/sensitivity labels.

A good heuristic:

• “Give me the document metadata / file bytes” → Graph sites/drives/items

• “Answer using the most relevant parts of our HR policies” → Retrieval API

2) Set Delegated Permissions

The Retrieval API is delegated-only. That’s intentional: the service retrieves snippets from content the calling user can access, permission-trimmed at query time.

Minimum permissions for SharePoint grounding:

• Files.Read.All

• Sites.Read.All 

3) Test Quickly In Graph Explorer

Fastest way to validate your tenant + permissions is Graph Explorer.

Click path: Graph Explorer → Sign in → Modify permissions → Consent → Run query

4) Call Retrieval For SharePoint (With Site Scoping)

Here’s the core call. You provide:

• queryString (single sentence, up to 1,500 chars)

• dataSource = sharePoint

• optional filterExpression (KQL) to scope sites

• optional resourceMetadata

• maximumNumberOfResults (1–25) 

Change these values:

• queryString: the user’s natural-language question

• filterExpression: one site, or multiple sites using OR

• resourceMetadata: only the metadata fields you want returned

• maximumNumberOfResults: keep within 1–25

Minimal working example

Run the PowerShell call above and expect a response with retrievalHits[], each containing:

• webUrl

• extracts[] with text + relevanceScore

• optional resourceMetadata and sensitivityLabel

Troubleshooting

• 403 / access denied: confirm the signed-in user has a Copilot license (Copilot APIs require it).

• No results: remove filterExpression first, then add it back (KQL path scoping is easy to over-constrain).

• 400 bad request: maximumNumberOfResults must be 1–25, and queryString has constraints (single sentence, 1,500 chars).

• Trying application permissions: not supported—switch to delegated auth.

• Using /beta in production: move to v1.0 (beta can change and isn’t supported for production).

Notes

• The Retrieval API is built to avoid “DIY RAG plumbing” (export/crawl/index/vector DB) while still honoring Microsoft 365 security and compliance boundaries.

• Use filterExpression with path:"<site url>" to keep grounding tight (single site or multiple sites with OR).

• You typically pass the returned extracts.text + webUrl into your model prompt, and keep the URLs as citations in your UI.

Wrapping up

The Copilot Retrieval API is the most pragmatic way to pull permission-trimmed SharePoint grounding content into your own agents without building or hosting a parallel index. Once you can reliably retrieve relevant extracts, everything else becomes “just orchestration” around your model and UX.

Hope this helps!

Bring third party data into Declarative Agents for M365 Copilot (using TypeSpec)

In my previous post, Getting Started: Declarative Agents With TypeSpec for Microsoft 365 Copilot we saw the basics of Declarative Agents and how they are the sweet spot between no-code and pro-code agents. 

In this post, we will see how we can integrate third-party APIs in Declarative Agents. Declarative Agents can call third-party APIs through “actions” you describe in TypeSpec. The agent decides when to invoke your action, passes parameters, and you choose how the results render in chat (e.g Adaptive Cards). We’ll be plugging in a public weather API to show the end-to-end pattern.

On a high level, we’ll:

• Scaffold a Declarative Agent in VS Code.

• Add two actions: city → coords, then coords → weather.

• Bind results to Adaptive Cards for clean output.

• Test with natural prompts like “Weather in Paris, France”.

Prereqs

• Microsoft 365 tenant + VS Code with the Microsoft 365 Agents Toolkit extension.

• TypeSpec packages from the scaffold.

• Public APIs (no auth):

  • Geocoding: https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1

  • Weather: https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current=temperature_2m,wind_speed_10m

1) Scaffold a TypeSpec Declarative Agent

Click path: VS Code → Microsoft 365 Agents Toolkit (sidebar) → Create a New Agent/App → Declarative Agent (TypeSpec) → Finish. 

2) Add the TypeSpec files (agent + actions)

Update the main.tsp file:

And the actions.tsp file containing the action details

3) Add Adaptive Cards

Create adaptiveCards/ and add:

adaptiveCards/location-card.json

adaptiveCards/weather-card.json

4) Build & test

• In Agents Toolkit: Provision.

• Open the web test for your agent and try:

Prompts

• “What’s the weather in Seattle right now?”

• “Show me the weather in Paris, France.”

• “Get weather for latitude 40.7128 and longitude -74.0060.”

Expected

• The agent calls searchCity (shows Location card) → then getWeather (shows Weather card with °C, wind, time, timezone)

Minimal working example

Prompt: “Weather for Pune.”

Flow: searchCity(name="Pune") → top match → getWeather(latitude, longitude, current="temperature_2m,wind_speed_10m", location="Pune, IN")

Output: Two cards; final card shows temperature (°C), wind (km/h), time, and timezone.

Wrapping up

Declarative Agents make third-party API calls feel native: describe the action, let the agent orchestrate, and render the result with Adaptive Cards. 

Hope this helps!