Table of Contents
When static prompts are no longer enough
Most agents are created with fixed system prompts and tools. But as we need more intelligent systems, we sometimes need to adapt them to the situation, user, or time.
The framework offers AIContextProviders for this purpose.
These provide context to AI agents and can be chained together to connect multiple sources.
Providers are executed in the order they are registered, allowing you to layer multiple context modifications in a predictable way. You can configure the sequence in your agent’s setup, ensuring that context from earlier providers is available to those that run later in the chain. This lets you hook into the pipeline before and after the LLM call, helping avoid unexpected behavior by keeping the flow transparent.
The Architecture of Context Providers
To create a custom provider, we inherit from the AIContextProvider class. The Microsoft Agents framework handles all the complex routing and pipeline management behind the scenes, leaving us with just two key methods to override for our custom logic:
ProvideAIContextAsync(Pre-Call): This method is called just before the request is sent. Here we have full access to the current session, the previous instructions, and the pending message.StoreAIContextAsync(Post-Call): This method fires after the LLM has generated the response, but before it is returned to the user. Here, we can analyze the final response or any errors that might have occurred.
Examples
Memory
Let’s say we are building a barista agent for the coffee junkies among us.
We want the AI to remember the user’s specific brewing habits and gear. For example, when the user says, “I just bought a V60 pour-over” or “I really don’t like acidic coffees.”
ProvideAIContextAsync fetches user facts from the database and appends them as context to the instructions for the call. E.g., “User brews with a V60, prefers a 1:15 ratio, and loves dark, chocolatey roasts.”
StoreAIContextAsync passes the user request to a cheap extractor agent, which finds new facts to save for future use, enabling the barista to learn over time.
public class BaristaMemoryProvider : AIContextProvider
{
private const string UserIdStateKey = "UserId";
private readonly ICoffeeDatabase _db;
private readonly IExtractorAgent _extractor;
public BaristaMemoryProvider(ICoffeeDatabase db, IExtractorAgent extractor)
{
_db = db;
_extractor = extractor;
}
protected override async ValueTask<AIContext> ProvideAIContextAsync(
AIContextProvider.InvokingContext context,
CancellationToken cancellationToken = default)
{
string userId = GetUserId(context.Session);
var userPrefs = await _db.GetPreferencesAsync(userId, cancellationToken);
if (userPrefs is null)
{
return new AIContext();
}
return new AIContext
{
Instructions =
$"User Coffee Profile: Brewer: {userPrefs.Brewer}, " +
$"Ratio: {userPrefs.Ratio}, Roast: {userPrefs.RoastType}."
};
}
protected override async ValueTask StoreAIContextAsync(
AIContextProvider.InvokedContext context,
CancellationToken cancellationToken = default)
{
var lastUserMessage = context.RequestMessages
.LastOrDefault(m => m.Role == ChatRole.User)?
.Text;
if (string.IsNullOrWhiteSpace(lastUserMessage))
{
return;
}
var extractedFact = await _extractor.ExtractNewFactsAsync(lastUserMessage, cancellationToken);
if (extractedFact is not null)
{
string userId = GetUserId(context.Session);
await _db.SaveNewPreferenceAsync(userId, extractedFact, cancellationToken);
}
}
private static string GetUserId(AgentSession? session) =>
session?.StateBag.TryGetValue<string>(UserIdStateKey, out var userId) == true
? userId
: "anonymous";
}
Optimize Tokens
Let’s now imagine a virtual Guitar Tech agent. This agent is equipped with many tools (ScaleGenerator, TabFetcher, AmpEQDialer, PedalBoardRouter, Metronome, etc.).
Now we need to send the schema for all tools with every request to the LLM. Even if the user just says, “Hey man”. This inevitably wastes hundreds or thousands of tokens per call.
This time, we use ProvideAIContextAsync to quickly pass the incoming user message to a fast, efficient agent whose primary task is to evaluate user intent. (Is this request about music theory, finding tabs, or dialing in a tone?)
If the user asks, “How do I get a dirty Hendrix tone on my Strat?”, the provider injects only the AmpEQDialer and PedalBoardRouter tools into the context just before the main LLM call.
The main agent receives a tailored and lean toolset. This approach saves input tokens and reduces the risk of the AI making unnecessary tool calls.
public class GuitarTechToolProvider : AIContextProvider
{
private readonly IRoadieAgent _roadieRouter;
private readonly IToolRegistry _tools;
public GuitarTechToolProvider(IRoadieAgent roadieRouter, IToolRegistry tools)
{
_roadieRouter = roadieRouter;
_tools = tools;
}
protected override async ValueTask<AIContext> ProvideAIContextAsync(
AIContextProvider.InvokingContext context,
CancellationToken cancellationToken = default)
{
var lastMsg = context.RequestMessages
.LastOrDefault(m => m.Role == ChatRole.User)?
.Text;
var intent = await _roadieRouter.DetermineIntentAsync(lastMsg, cancellationToken);
var selectedTools = new List<AITool>();
switch (intent)
{
case Intent.ToneAndGear:
selectedTools.Add(_tools.GetTool("AmpEQDialer"));
selectedTools.Add(_tools.GetTool("PedalBoardRouter"));
break;
case Intent.MusicTheory:
selectedTools.Add(_tools.GetTool("ScaleGenerator"));
break;
}
return new AIContext
{
Tools = selectedTools
};
}
}
Guardrails & Validation
For this example, we will use an agent that helps us build Lego models. Let’s ask it for a creative way to connect two Lego plates at a strange 45-degree angle. LLMs are eager to please and sometimes ignore existing rules. And though the agent might confidently suggest using superglue. Obviously, we need a strict safety net to avoid ruining our Lego set because of a wrong answer.
Via ProvideAIContextAsync, we inject a strict boundary condition right alongside the user’s prompt: “Constraint: You are a purist Lego Master Builder. Only reference legal, official connection techniques. Do not suggest modifying bricks, cutting, or using adhesives.”
But even with strict boundaries, the agent could give us the wrong answer.
StoreAIContextAsync grabs the generated response before it is returned to the user.
Again, we run the response through a fast, lightweight agent that looks for out-of-bounds keywords such as “glue”, “stress”, and “cut”.
If the validator detects an illegal technique, we can log the error immediately, strip the offending paragraph from the answer, or throw an exception to trigger a silent, automatic retry.
public class LegoGuardrailProvider : AIContextProvider
{
private readonly IValidatorAgent _validator;
public LegoGuardrailProvider(IValidatorAgent validator)
{
_validator = validator;
}
protected override ValueTask<AIContext> ProvideAIContextAsync(
AIContextProvider.InvokingContext context,
CancellationToken cancellationToken = default)
{
return ValueTask.FromResult(new AIContext
{
Instructions = "Constraint: Only reference legal Lego connection techniques."
});
}
protected override async ValueTask StoreAIContextAsync(
AIContextProvider.InvokedContext context,
CancellationToken cancellationToken = default)
{
var lastAssistantMsg = context.ResponseMessages?
.LastOrDefault()?
.Text;
var validation = await _validator.CheckForIllegalTechniquesAsync(
lastAssistantMsg,
cancellationToken);
if (!validation.IsSafe)
{
throw new AIValidationException($"Safety violation: {validation.Reason}");
}
}
}
Alternatives
In addition to the AIContextProvider, the framework also offers the MessageAIContextProvider. Instead of adjusting system instructions or tools in the background, this provider injects actual chat messages into the conversation.
You can register the MessageAIContextProvider as middleware. This is extremely helpful when working with agents we haven’t created ourselves and whose parameters we cannot directly configure (such as remote agents connected via the A2A (Agent-to-Agent) protocol). By using it as middleware, we can still dynamically inject additional messages into them without needing access to their internal configuration.
Conclusion
Context Providers are really helpful in many situations. Whether you need dynamic on-the-fly prompts, an intelligent background memory, or massive token optimization through tool injection.
We now know how to tame our chat histories, dynamically inject memory, and optimize our token budgets. But what happens when words are no longer enough, and our AI needs to interact with the real world?
In the next part of this series, we will explore Tools and Dependency Injection, and learn how to teach your AI to execute actual actions!