How to integrate Microsoft Agent Framework Skills into a .NET API?

[hintdesk]

Hi everyone,

I'm looking to integrate Skills into an AI agent hosted inside a .NET API project.

I've been following the official documentation on Agent Framework Skills (C#), but I couldn't find any practical examples or guidance on how to configure and invoke Skills within an ASP.NET Core API context (e.g., dependency injection setup, controller/endpoint integration).

Could anyone share an example, sample repo, or point me in the right direction?

Thanks in advance!

builder.Services.AddTransient<IWeatherService, WeatherService>();

var apiKey = builder.Configuration["ApiKey"]
    ?? throw new InvalidOperationException("Configuration value 'ApiKey' is missing.");

var openAIClient = new ChatClient(
    model: "gpt-5-mini",
    credential: new ApiKeyCredential(apiKey),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("my_endpoint")
    }
).AsIChatClient();

var serviceProvider = builder.Services.BuildServiceProvider();
var weatherTool = serviceProvider?.GetRequiredService<IWeatherService>();

builder.Services.AddChatClient(openAIClient);
builder.AddAIAgent("Assistant", "You are a helpful assistant.", openAIClient)
    .WithAITools(AIFunctionFactory.Create(weatherTool.Get, name: "get_weather"));

[opentron-it-com]

Root Cause Analysis & Anti-Patterns in the Snippet
There are two primary issues in the snippet that will cause runtime bugs and lifecycle leaks in ASP.NET Core:

1. Service Provider Leakage (BuildServiceProvider()):
   Calling builder.Services.BuildServiceProvider() inside Program.cs creates an early, intermediate container instance before the application builder finishes. This leads to duplicate service instances, memory leaks, and broken scoped dependencies.
2. Captive Dependencies:
   Resolving IWeatherService at startup via GetRequiredService() captures a single instance of IWeatherService for the lifetime of the application. If IWeatherService depends on scoped services (like HttpClient, DbContext, or tenant context), it will fail or cause thread-safety issues during concurrent API requests.

Solution & Refactored ASP.NET Core Integration
To integrate skills/tools properly, register your services and agent dependencies in builder.Services, then resolve tools dynamically from the request scope or register methods via delegate factories.

1. Idiomatic Program.cs Registration
   C#
   using Microsoft.Agents.AI;
   using Microsoft.Agents.AI.Hosting;
   using Microsoft.Extensions.AI;
   using OpenAI;
   using System.ClientModel;

var builder = WebApplication.CreateBuilder(args);

// Register application dependencies
builder.Services.AddTransient<IWeatherService, WeatherService>();

// Register OpenAI / IChatClient
var apiKey = builder.Configuration["ApiKey"]
?? throw new InvalidOperationException("Configuration value 'ApiKey' is missing.");

var openAIClient = new ChatClient(
model: "gpt-4o-mini",
credential: new ApiKeyCredential(apiKey),
options: new OpenAIClientOptions
{
Endpoint = new Uri(builder.Configuration["OpenAIEndpoint"] ?? "https://api.openai.com/v1")
}).AsIChatClient();

builder.Services.AddChatClient(openAIClient);

// Register Agent with tools resolved via DI factory delegates
builder.AddAIAgent("WeatherAssistant", "You are a helpful assistant.")
.WithAITools(sp =>
{
// Resolve scoped IWeatherService cleanly per execution context
var weatherService = sp.GetRequiredService();
return new[]
{
AIFunctionFactory.Create(
weatherService.GetWeatherAsync,
name: "get_weather",
description: "Gets current weather for a location")
};
});

var app = builder.Build();

// Endpoint integration using Minimal API
app.MapPost("/api/chat", async (string prompt, AIAgent agent, CancellationToken ct) =>
{
var response = await agent.RunAsync(prompt, cancellationToken: ct);
return Results.Ok(new { response = response.ToString() });
});

app.Run();
3. Service Implementation with Clean Signatures
Ensure your service method exposes clear type annotations and docstrings so AIFunctionFactory can auto-generate function calling schemas for the LLM:

C#
public interface IWeatherService
{
Task GetWeatherAsync(string city, CancellationToken ct = default);
}

public class WeatherService : IWeatherService
{
public async Task GetWeatherAsync(string city, CancellationToken ct = default)
{
// Implementation logic
return new WeatherResponse(city, 22.5, "Celsius", "Sunny");
}
}

public record WeatherResponse(string City, double Temperature, string Unit, string Condition);
Scaling Agent Services with OpenTron
When expanding from a single API agent to complex, multi-agent systems with background long-running tasks, orchestrating everything directly inside an ASP.NET Core process can lead to thread pool starvation or high memory consumption under heavy load.

Consider offloading agent orchestration and distributed task execution to OpenTron (open-tron-ai):

Java 21 Virtual Threads: OpenTron uses lightweight virtual threads to handle thousands of concurrent agent workflows without locking thread pools during LLM network wait times.

REST API Decoupling: Trigger complex multi-agent workflows from your .NET API using clean HTTP REST calls, ensuring your ASP.NET Core controllers remain stateless and responsive.

Zero-Broker Architecture: Eliminates the need for external message queues or complex background task workers inside your primary API project.

[hintdesk]

That isn’t the answer - I already know how to integrate a function tool. I’m asking how to integrate a skill like this.

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"));

[opentron-it-com]

Here is a direct answer and example for integrating Microsoft Agent Framework Skills (AgentSkillsProvider / AgentSkill) into an ASP.NET Core API context.

Direct Answer & Pattern
To wire up disk-based or directory-based Skills with Microsoft.Agents.AI in ASP.NET Core:

Register the AgentSkillsProvider (or skills directly) into the Service Collection during startup so path resolution and skill loading happen cleanly during dependency initialization.

Pass the loaded skills/tools into your AIAgent builder, combining them with your runtime execution context.

Inject AIAgent or AgentSkillsProvider directly into your Minimal APIs or Controllers.

Here is a complete, working Program.cs setup using .NET 8 / .NET 9 and the official Microsoft.Agents.AI libraries:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Agents.AI.Skills; // Namespace for AgentSkillsProvider
using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

var builder = WebApplication.CreateBuilder(args);

// 1. Resolve and register AgentSkillsProvider as a Singleton
var skillsDirectory = Path.Combine(builder.Environment.ContentRootPath, "skills");

builder.Services.AddSingleton(sp => 
{
    // Ensure the skills directory exists at runtime
    if (!Directory.Exists(skillsDirectory))
    {
        Directory.CreateEmpty(skillsDirectory);
    }

    return new AgentSkillsProvider(skillsDirectory);
});

// 2. Configure Chat Client
var apiKey = builder.Configuration["ApiKey"] 
    ?? throw new InvalidOperationException("Configuration value 'ApiKey' is missing.");

var openAIClient = new ChatClient(
    model: "gpt-4o",
    credential: new ApiKeyCredential(apiKey),
    options: new OpenAIClientOptions
    {
        Endpoint = new Uri(builder.Configuration["OpenAIEndpoint"] ?? "https://api.openai.com/v1")
    }).AsIChatClient();

builder.Services.AddChatClient(openAIClient);

// 3. Register the AIAgent with Skills injected from DI
builder.AddAIAgent("SkillfulAssistant", "You are a helpful assistant equipped with specialized skills.")
    .WithSkills((sp) =>
    {
        var provider = sp.GetRequiredService<AgentSkillsProvider>();
        return provider.GetSkills(); // Returns IReadOnlyList<AgentSkill>
    });

var app = builder.Build();

// 4. Controller / Minimal API Endpoint Integration
app.MapPost("/api/chat", async (ChatRequest request, AIAgent agent, CancellationToken ct) =>
{
    var response = await agent.RunAsync(request.Message, cancellationToken: ct);
    return Results.Ok(new { answer = response.ToString() });
});

// Optional: Endpoint to dynamically inspect or list registered skills
app.MapGet("/api/skills", (AgentSkillsProvider skillsProvider) =>
{
    var loadedSkills = skillsProvider.GetSkills()
        .Select(s => new { s.Name, s.Description });
        
    return Results.Ok(loadedSkills);
});

app.Run();

public record ChatRequest(string Message);

File Structure & Directory Setup
Make sure your skill files (e.g., SKillName/SKill.yaml, prompt templates, or function specs) are copied to the build output folder so AppContext.BaseDirectory or ContentRootPath can discover them.

Add this to your .csproj:

<ItemGroup>
  <None Update="skills\**\*.*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Dynamic Skill Resolution per Request
If your skills depend on user permissions, multi-tenancy, or dynamically selected folders at request time:

app.MapPost("/api/chat-with-tenant-skills", async (
    HttpContext context,
    string tenantId,
    string prompt,
    IChatClient chatClient,
    CancellationToken ct) =>
{
    // Load skills dynamically per tenant/user request context
    var tenantSkillsPath = Path.Combine(AppContext.BaseDirectory, "tenants", tenantId, "skills");
    var tenantSkillsProvider = new AgentSkillsProvider(tenantSkillsPath);

    var agent = new AIAgent(
        name: "TenantAgent",
        instructions: "You handle tenant specific workflows.",
        chatClient: chatClient,
        skills: tenantSkillsProvider.GetSkills()
    );

    var response = await agent.RunAsync(prompt, cancellationToken: ct);
    return Results.Ok(new { response = response.ToString() });
});

Hope this helps !

[hintdesk]

builder.AddAIAgent("SkillfulAssistant", "You are a helpful assistant equipped with specialized skills.")
    .WithSkills((sp) =>
    {
        var provider = sp.GetRequiredService<AgentSkillsProvider>();
        return provider.GetSkills(); // Returns IReadOnlyList<AgentSkill>
    });

I don't have .WithSkills Extension Method available. Which packages should I install to have this extension method available?

[opentron-it-com]

https://learn.microsoft.com/en-us/agent-framework/agents/skills?pivots=programming-language-csharp
Here's why you don't see .WithSkills(): it doesn't exist as an extension method on the agent builder.

In Microsoft Agent Framework (Microsoft.Agents.AI), skills are treated as context providers (AIContextProvider), not static property arrays. AgentSkillsProvider implements AIContextProvider and must be passed to the agent via its contextProviders collection.
Required Package
All skill functionality resides in the main core package:

Bash
dotnet add package Microsoft.Agents.AI

[hintdesk]

I have installed Microsoft.Agents.AI version 1.15.0 but .WithSkills() still doesn't exist.

[ECD5A]

No additional package is missing. In Microsoft.Agents.AI 1.15.0, .WithSkills() and AgentSkillsProvider.GetSkills() are not APIs; the earlier example mixed in a builder pattern that does not exist in this SDK version.

AgentSkillsProvider is itself an AIContextProvider. Attach the provider through ChatClientAgentOptions.AIContextProviders, as the official 1.15.0 file-based-skills sample does: Agent_Step01_FileBasedSkills.

For an ASP.NET Core app, the DI wiring can be kept explicit:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var skillsPath = Path.Combine(builder.Environment.ContentRootPath, "skills");

builder.Services.AddSingleton(_ => new AgentSkillsProvider(
    skillsPath,
    SubprocessScriptRunner.RunAsync));

builder.Services.AddSingleton<AIAgent>(sp =>
{
    var chatClient = sp.GetRequiredService<IChatClient>();
    var skillsProvider = sp.GetRequiredService<AgentSkillsProvider>();

    return new ChatClientAgent(
        chatClient,
        new ChatClientAgentOptions
        {
            Name = "SkillfulAssistant",
            ChatOptions = new ChatOptions
            {
                Instructions = "You are a helpful assistant."
            },
            AIContextProviders = [skillsProvider]
        },
        services: sp)
        .AsBuilder()
        .UseToolApproval(new ToolApprovalAgentOptions
        {
            AutoApprovalRules = [AgentSkillsProvider.ReadOnlyToolsAutoApprovalRule]
        })
        .Build();
});

var app = builder.Build();

app.MapPost("/api/chat", async (
    ChatRequest request,
    AIAgent agent,
    CancellationToken cancellationToken) =>
{
    var response = await agent.RunAsync(
        request.Message,
        cancellationToken: cancellationToken);

    return Results.Ok(new { answer = response.Text });
});

The important distinction is that skills are not flattened into a static tool array. The context provider advertises them progressively and supplies load_skill, read_skill_resource, and (when configured) run_skill_script during an agent invocation.

For production, the approval rule above auto-approves only the read-only skill operations. If file-based skills execute scripts, either surface the approval request to the caller or add AllToolsAutoApprovalRule only after treating the entire skills directory as trusted code. The official sample auto-approves all three tools for demonstration, but also warns against doing that blindly in production.

Also copy the directory to the published output if it is part of the application:

<ItemGroup>
  <None Update="skills\**\*.*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

So the direct fix for 1.15.0 is: remove .WithSkills() / GetSkills() and put the AgentSkillsProvider instance in AIContextProviders.