Foundry Agent Service

Think of Foundry as a production line for intelligent agents. The Foundry Agent Service brings together the core components of Foundry - models, tools, and frameworks - into a unified runtime. It handles conversations, coordinates tool execution, applies content safety controls, and integrates with identity, networking, and observability systems. Together, these capabilities ensure that agents are secure, scalable, and ready for production use.

---

Building your Foundry AI Agent

Start by installing the following NuGet packages:

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prereleased

Next, add your Foundry endpoint and model deployment name, as well as the agent's name and instructions:

var endpoint = "";
var model = "gpt-4.1-mini-itt";
const string AgentName = "ArchitectAgent";
const string AgentInstructions = "You are an Azure Solutions Architect that uses knowledge from the official Microsoft docs to answer questions.";

For MCP tools, we will use the official Microsoft Learn MCP Server, which you can find on the following GitHub repository.

Create an MCP tool definition by specifying the server label and URL:

var mcpTool = new MCPToolDefinition(
    serverLabel: "msdocs_mcp",
    serverUrl: "https://learn.microsoft.com/api/mcp");

For the tools, add the three available tools from the documentation:

// Currently, only three tools are available
mcpTool.AllowedTools.Add("microsoft_docs_search");
mcpTool.AllowedTools.Add("microsoft_docs_fetch");
mcpTool.AllowedTools.Add("microsoft_code_sample_search");

To create the agent in Microsoft Foundry, use the following code which creates a PersistentAgentsClient and calls the CreateAgentAsync.

var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());

var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: model,
    name: AgentName,
    instructions: AgentInstructions,
    tools: [mcpTool]);

The initial state of my Foundry is with zero agents:

After running the code, we can see the agent was successfully created.

Agents created through Foundry aren't monoliths. Each agent has a specific role, is powered by the right model, and is equipped with the right tools.

To get the agent and execute it:

var agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "msdocs_mcp")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};

AgentThread thread = agent.GetNewThread();
var response = await agent.RunAsync("What is Azure Key Vault?", thread, runOptions);
Console.WriteLine(response);

Notice that we can configure the tool resources with approval settings. The RequireApproval controls when user approval is needed for tool invocations:

• "never": Tools invocations don’t require user approval

• "always": All tool invocations require user approval

• Custom approval rules can also be configured

The response returned by the agent is the following:

Finally, to delete an agent we can run the following code:

await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);

---