Using Agent Skills with Azure AI Foundry Agent

[Vonny0123]

I've followed the example here: https://learn.microsoft.com/en-us/agent-framework/agents/skills?pivots=programming-language-csharp to create a MAF agent with skills - I've been trying to work out how to use these with an AI Foundry Agent to benefit from versioning and agent traces, but I can't work out if there's a way to do this. None of the existing overloads for creating a Foundry Agent seem to accept ChatClientAgentOptions, and I can't see any other way to provide an AgentSkillsProvider.

Is there something I'm missing, or is this just currently not supported?

[jluocsa]

Your reading of the API surface is correct. On the versioned AsAIAgent overloads — AIProjectClient.AsAIAgent(ProjectsAgentVersion, …), AsAIAgent(ProjectsAgentRecord, …), and AsAIAgent(AgentReference, …) in AzureAIProjectChatClientExtensions — the only customization parameter today is IList<AITool>? tools. None of them accept ChatClientAgentOptions, so there is no direct slot for AIContextProviders or an AgentSkillsProvider.

You are not missing a documented feature; it is a real gap on the versioned path. That said, there are two supported workarounds that get you a working integration today, depending on which Foundry capability you most want to preserve.

Option 1 — Compose skills client-side via clientFactory (preserves versioning and traces)

Every versioned AsAIAgent overload exposes a clientFactory: Func<IChatClient, IChatClient> hook. This is the seam to wrap the underlying AzureAIProjectChatClient with AIContextProviderChatClient, which the framework exposes via the ChatClientBuilder.UseAIContextProviders(...) extension:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Azure.AI.Projects;

var skillsProvider = new AgentSkillsProvider(
    new BlobAgentSkillsSource(blobContainer),
    new AgentSkillsProviderOptions { DisableCaching = true });

FoundryAgent agent = aiProjectClient.AsAIAgent(
    agentVersion,
    tools: null,
    clientFactory: inner => inner
        .AsBuilder()
        .UseAIContextProviders(skillsProvider)
        .Build());

On each invocation, AIContextProviderChatClient calls AgentSkillsProvider.InvokingAsync(...) under the ChatClientAgent's run context, merges the resulting AIContext (instructions + tools + messages) into the outgoing ChatOptions, then forwards to the Foundry chat client. Because the skill's contribution is added to the request payload that reaches the Foundry service, agent traces in the Foundry portal will reflect the augmented instructions and tool catalog for each run.

What you keep: the agent is a real FoundryAgent bound to a ProjectsAgentVersion/ProjectsAgentRecord/AgentReference. Versioning, server-side conversation sessions (CreateConversationSessionAsync), and run-level traces all work as documented.

Tradeoff: the skill's instructions and tools are client-injected, not part of the Foundry agent definition. If you change the skill content in Blob Storage, only the runtime payload changes — the server-side agent version in Foundry does not move. The lineage you see in the portal is "agent v3 + client-applied skill X" rather than "agent v4". For most observability scenarios this is acceptable; if regulatory or governance posture requires the skill to be versioned alongside the agent definition, see Option 3.

Option 2 — Use the Responses-API overload (full Skills support, no versioning)

AIProjectClient also exposes a non-versioned overload that takes a full ChatClientAgentOptions, and that overload does propagate AIContextProviders end-to-end:

ChatClientAgent agent = aiProjectClient.AsAIAgent(
    new ChatClientAgentOptions
    {
        Name = "support-bot",
        ChatOptions = new ChatOptions
        {
            ModelId = "gpt-4o",
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [new AgentSkillsProvider(skillsSource)],
    });

This path runs through the project's Responses API (AzureAIProjectResponsesChatClient), so calls are still attributed to your Foundry project and appear in project-level traces. What you lose is the versioned ProjectsAgentRecord lineage — there is no server-side agent definition for this agent, so the Foundry portal will not surface it under "Agents". Use this if traces matter more than agent versioning, or for environments where the agent definition lives in source control alongside the application.

Option 3 — File a feature request to close the gap

The private helpers in AzureAIProjectChatClientExtensions (AsChatClientAgent(...) → CreateChatClientAgent(...)) already accept and forward a full ChatClientAgentOptions. Adding three public overloads that take ChatClientAgentOptions alongside the existing versioned overloads is a small, additive API change that would let you write the natural form:

var agent = aiProjectClient.AsAIAgent(
    agentVersion,
    options: new ChatClientAgentOptions
    {
        AIContextProviders = [skillsProvider],
        ChatOptions = new ChatOptions { Tools = additionalTools },
    });

I'd suggest opening an Ideas discussion or a GitHub issue requesting this — the implementation cost on the framework side is minimal because the private wiring already exists.

Recommendation

For your scenario — Foundry agent with versioning + traces — start with Option 1. It works today, requires no API changes, and preserves both Foundry capabilities you called out. Reserve Option 2 for environments where you control the agent definition in code anyway. If you need the skill content itself to be versioned with the Foundry agent definition, that is a server-side modeling concern (agent versions today don't have a "linked skills bundle" concept), and Option 3 is the right place to lobby for first-class support.