agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into features/3768-devui-aspire-integration

Browse Source
This commit is contained in:
Tommaso Stocchi
2026-02-17 17:38:36 +01:00
committed by GitHub
Unverified
parent f38fbdf378 08275f657b
commit daba7a6122
357 changed files with 12595 additions and 7132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet/samples/AGUIClientServer/AGUIDojoServer/SharedState/SharedStateAgent.cs
+22 -1
View File
@@ -78,7 +78,7 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
var response = allUpdates.ToAgentResponse();
if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
{
byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
stateSnapshot,
@@ -103,4 +103,25 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
yield return update;
}
}
private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
{
try
{
T? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
if (result is null)
{
structuredOutput = default!;
return false;
}
structuredOutput = result;
return true;
}
catch
{
structuredOutput = default!;
return false;
}
}
}
dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs
+22 -1
View File
@@ -107,7 +107,7 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
var response = allUpdates.ToAgentResponse();
// Try to deserialize the structured state response
if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
{
// Serialize and emit as STATE_SNAPSHOT via DataContent
byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
@@ -134,4 +134,25 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
yield return update;
}
}
private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
{
try
{
T? deserialized = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
if (deserialized is null)
{
structuredOutput = default!;
return false;
}
structuredOutput = deserialized;
return true;
}
catch
{
structuredOutput = default!;
return false;
}
}
}
dotnet/samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Program.cs
+19 -21
View File
@@ -6,6 +6,7 @@
using System.Runtime.CompilerServices;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using SampleApp;
@@ -28,6 +29,8 @@ namespace SampleApp
{
public override string? Name => "UpperCaseParrotAgent";
public readonly ChatHistoryProvider ChatHistoryProvider = new InMemoryChatHistoryProvider();
protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
=> new(new CustomAgentSession());
@@ -38,11 +41,11 @@ namespace SampleApp
throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
}
return new(typedSession.Serialize(jsonSerializerOptions));
return new(JsonSerializer.SerializeToElement(typedSession, jsonSerializerOptions));
}
protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
=> new(new CustomAgentSession(serializedState, jsonSerializerOptions));
=> new(serializedState.Deserialize<CustomAgentSession>(jsonSerializerOptions)!);
protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
{
@@ -56,17 +59,14 @@ namespace SampleApp
// Get existing messages from the store
var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
// Clone the input messages and turn them into response messages with upper case text.
List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
// Notify the session of the input and output messages.
var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
{
ResponseMessages = responseMessages
};
await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
return new AgentResponse
{
@@ -88,17 +88,14 @@ namespace SampleApp
// Get existing messages from the store
var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
// Clone the input messages and turn them into response messages with upper case text.
List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
// Notify the session of the input and output messages.
var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
{
ResponseMessages = responseMessages
};
await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
foreach (var message in responseMessages)
{
@@ -140,15 +137,16 @@ namespace SampleApp
/// <summary>
/// A session type for our custom agent that only supports in memory storage of messages.
/// </summary>
internal sealed class CustomAgentSession : InMemoryAgentSession
internal sealed class CustomAgentSession : AgentSession
{
internal CustomAgentSession() { }
internal CustomAgentSession()
{
}
internal CustomAgentSession(JsonElement serializedSessionState, JsonSerializerOptions? jsonSerializerOptions = null)
: base(serializedSessionState, jsonSerializerOptions) { }
internal new JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
=> base.Serialize(jsonSerializerOptions);
[JsonConstructor]
internal CustomAgentSession(AgentSessionStateBag stateBag) : base(stateBag)
{
}
}
}
}
dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/Program.cs
+12 -7
View File
@@ -37,16 +37,21 @@ AIAgent agent = new AzureOpenAIClient(
{
ChatOptions = new() { Instructions = "You are good at telling jokes." },
Name = "Joker",
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new ChatHistoryMemoryProvider(
AIContextProviders = [new ChatHistoryMemoryProvider(
vectorStore,
collectionName: "chathistory",
vectorDimensions: 3072,
// Configure the scope values under which chat messages will be stored.
// In this case, we are using a fixed user ID and a unique session ID for each new session.
storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
// Configure the scope which would be used to search for relevant prior messages.
// In this case, we are searching for any messages for the user across all sessions.
searchScope: new() { UserId = "UID1" }))
// Callback to configure the initial state of the ChatHistoryMemoryProvider.
// The ChatHistoryMemoryProvider stores its state in the AgentSession and this callback
// will be called whenever the ChatHistoryMemoryProvider cannot find existing state in the session,
// typically the first time it is used with a new session.
session => new ChatHistoryMemoryProvider.State(
// Configure the scope values under which chat messages will be stored.
// In this case, we are using a fixed user ID and a unique session ID for each new session.
storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
// Configure the scope which would be used to search for relevant prior messages.
// In this case, we are searching for any messages for the user across all sessions.
searchScope: new() { UserId = "UID1" }))]
});
// Start a new session for the agent conversation.
dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/Program.cs
+10 -9
View File
@@ -34,20 +34,21 @@ AIAgent agent = new AzureOpenAIClient(
.AsAIAgent(new ChatClientAgentOptions()
{
ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(ctx.SerializedState.ValueKind is not JsonValueKind.Null and not JsonValueKind.Undefined
// If each session should have its own Mem0 scope, you can create a new id per session here:
// ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })
// In this case we are storing memories scoped by application and user instead so that memories are retained across threads.
? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" })
// For cases where we are restoring from serialized state:
: new Mem0Provider(mem0HttpClient, ctx.SerializedState, ctx.JsonSerializerOptions))
// The stateInitializer can be used to customize the Mem0 scope per session and it will be called each time a session
// is encountered by the Mem0Provider that does not already have Mem0Provider state stored on the session.
// If each session should have its own Mem0 scope, you can create a new id per session via the stateInitializer, e.g.:
// new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() }))
// In our case we are storing memories scoped by application and user instead so that memories are retained across threads.
AIContextProviders = [new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" }))]
});
AgentSession session = await agent.CreateSessionAsync();
// Clear any existing memories for this scope to demonstrate fresh behavior.
Mem0Provider mem0Provider = session.GetService<Mem0Provider>()!;
await mem0Provider.ClearStoredMemoriesAsync();
// Note that the ClearStoredMemoriesAsync method will clear memories
// using the scope stored in the session, or provided via the stateInitializer.
Mem0Provider mem0Provider = agent.GetService<Mem0Provider>()!;
await mem0Provider.ClearStoredMemoriesAsync(session);
Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/Program.cs
+35 -33
View File
@@ -36,7 +36,7 @@ ChatClient chatClient = new AzureOpenAIClient(
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
{
ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new UserInfoMemory(chatClient.AsIChatClient(), ctx.SerializedState, ctx.JsonSerializerOptions))
AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
});
// Create a new session for the conversation.
@@ -58,10 +58,10 @@ Console.WriteLine("\n>> Use deserialized session with previously created memorie
var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
Console.WriteLine("\n>> Read memories from memory component\n");
Console.WriteLine("\n>> Read memories using memory component\n");
// It's possible to access the memory component via the session's GetService method.
var userInfo = deserializedSession.GetService<UserInfoMemory>()?.UserInfo;
// It's possible to access the memory component via the agent's GetService method.
var userInfo = agent.GetService<UserInfoMemory>()?.GetUserInfo(deserializedSession);
// Output the user info that was captured by the memory component.
Console.WriteLine($"MEMORY - User Name: {userInfo?.UserName}");
@@ -69,12 +69,12 @@ Console.WriteLine($"MEMORY - User Age: {userInfo?.UserAge}");
Console.WriteLine("\n>> Use new session with previously created memories\n");
// It is also possible to set the memories in a memory component on an individual session.
// It is also possible to set the memories using a memory component on an individual session.
// This is useful if we want to start a new session, but have it share the same memories as a previous session.
var newSession = await agent.CreateSessionAsync();
if (userInfo is not null && newSession.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
if (userInfo is not null && agent.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
{
newSessionMemory.UserInfo = userInfo;
newSessionMemory.SetUserInfo(newSession, userInfo);
}
// Invoke the agent and output the text result.
@@ -88,29 +88,32 @@ namespace SampleApp
/// </summary>
internal sealed class UserInfoMemory : AIContextProvider
{
private readonly ProviderSessionState<UserInfo> _sessionState;
private readonly IChatClient _chatClient;
public UserInfoMemory(IChatClient chatClient, UserInfo? userInfo = null)
public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
: base(null, null)
{
this._sessionState = new ProviderSessionState<UserInfo>(
stateInitializer ?? (_ => new UserInfo()),
this.GetType().Name);
this._chatClient = chatClient;
this.UserInfo = userInfo ?? new UserInfo();
}
public UserInfoMemory(IChatClient chatClient, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
public override string StateKey => this._sessionState.StateKey;
public UserInfo GetUserInfo(AgentSession session)
=> this._sessionState.GetOrInitializeState(session);
public void SetUserInfo(AgentSession session, UserInfo userInfo)
=> this._sessionState.SaveState(session, userInfo);
protected override async ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default)
{
this._chatClient = chatClient;
var userInfo = this._sessionState.GetOrInitializeState(context.Session);
this.UserInfo = serializedState.ValueKind == JsonValueKind.Object ?
serializedState.Deserialize<UserInfo>(jsonSerializerOptions)! :
new UserInfo();
}
public UserInfo UserInfo { get; set; }
protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
{
// Try and extract the user name and age from the message if we don't have it already and it's a user message.
if ((this.UserInfo.UserName is null || this.UserInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
{
var result = await this._chatClient.GetResponseAsync<UserInfo>(
context.RequestMessages,
@@ -120,36 +123,35 @@ namespace SampleApp
},
cancellationToken: cancellationToken);
this.UserInfo.UserName ??= result.Result.UserName;
this.UserInfo.UserAge ??= result.Result.UserAge;
userInfo.UserName ??= result.Result.UserName;
userInfo.UserAge ??= result.Result.UserAge;
}
this._sessionState.SaveState(context.Session, userInfo);
}
protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
{
var userInfo = this._sessionState.GetOrInitializeState(context.Session);
StringBuilder instructions = new();
// If we don't already know the user's name and age, add instructions to ask for them, otherwise just provide what we have to the context.
instructions
.AppendLine(
this.UserInfo.UserName is null ?
userInfo.UserName is null ?
"Ask the user for their name and politely decline to answer any questions until they provide it." :
$"The user's name is {this.UserInfo.UserName}.")
$"The user's name is {userInfo.UserName}.")
.AppendLine(
this.UserInfo.UserAge is null ?
userInfo.UserAge is null ?
"Ask the user for their age and politely decline to answer any questions until they provide it." :
$"The user's age is {this.UserInfo.UserAge}.");
$"The user's age is {userInfo.UserAge}.");
return new ValueTask<AIContext>(new AIContext
{
Instructions = instructions.ToString()
});
}
public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
{
return JsonSerializer.SerializeToElement(this.UserInfo, jsonSerializerOptions);
}
}
internal sealed class UserInfo
dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs
+8 -4
View File
@@ -65,12 +65,16 @@ AIAgent agent = azureOpenAIClient
.AsAIAgent(new ChatClientAgentOptions
{
ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)),
// Since we are using ChatCompletion which stores chat history locally, we can also add a message removal policy
AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
// Since we are using ChatCompletion which stores chat history locally, we can also add a message filter
// that removes messages produced by the TextSearchProvider before they are added to the chat history, so that
// we don't bloat chat history with all the search result messages.
ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(ctx.SerializedState, ctx.JsonSerializerOptions)
.WithAIContextProviderMessageRemoval()),
// By default the chat history provider will store all messages, except for those that came from chat history in the first place.
// We also want to maintain that exclusion here.
ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
{
StorageInputMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
}),
});
AgentSession session = await agent.CreateSessionAsync();
dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs
+9 -2
View File
@@ -62,7 +62,7 @@ TextSearchProviderOptions textSearchOptions = new()
{
// Run the search prior to every model invocation.
SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
// Use up to 4 recent messages when searching so that searches
// Use up to 5 recent messages when searching so that searches
// still produce valuable results even when the user is referring
// back to previous messages in their request.
RecentMessageMemoryLimit = 5
@@ -74,7 +74,14 @@ AIAgent agent = azureOpenAIClient
.AsAIAgent(new ChatClientAgentOptions
{
ChatOptions = new() { Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions))
AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
// Configure a filter on the InMemoryChatHistoryProvider so that we don't persist the messages produced by the TextSearchProvider in chat history.
// The default is to persist all messages except those that came from chat history in the first place.
// You may choose to persist the TextSearchProvider messages, if you want the search output to be provided to the model in future interactions as well.
ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions()
{
StorageInputMessageFilter = msgs => msgs.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider)
})
});
AgentSession session = await agent.CreateSessionAsync();
dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/Program.cs
+1 -1
View File
@@ -32,7 +32,7 @@ AIAgent agent = new AzureOpenAIClient(
.AsAIAgent(new ChatClientAgentOptions
{
ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions))
AIContextProviders = [new TextSearchProvider(MockSearchAsync, textSearchOptions)]
});
AgentSession session = await agent.CreateSessionAsync();
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/AIAgentBuilderExtensions.cs
+49
View File
@@ -0,0 +1,49 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
namespace SampleApp;
/// <summary>
/// Provides extension methods for adding structured output capabilities to <see cref="AIAgentBuilder"/> instances.
/// </summary>
internal static class AIAgentBuilderExtensions
{
/// <summary>
/// Adds structured output capabilities to the agent pipeline, enabling conversion of text responses to structured JSON format.
/// </summary>
/// <param name="builder">The <see cref="AIAgentBuilder"/> to which structured output support will be added.</param>
/// <param name="chatClient">
/// The chat client used to transform text responses into structured JSON format.
/// If <see langword="null"/>, the chat client will be resolved from the service provider.
/// </param>
/// <param name="optionsFactory">
/// An optional factory function that returns the <see cref="StructuredOutputAgentOptions"/> instance to use.
/// This allows for fine-tuning the structured output behavior such as setting the response format or system message.
/// </param>
/// <returns>The <see cref="AIAgentBuilder"/> with structured output capabilities added, enabling method chaining.</returns>
/// <remarks>
/// <para>
/// A <see cref="ChatResponseFormatJson"/> must be specified either through the
/// <see cref="AgentRunOptions.ResponseFormat"/> at runtime or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
/// provided during configuration.
/// </para>
/// </remarks>
public static AIAgentBuilder UseStructuredOutput(
this AIAgentBuilder builder,
IChatClient? chatClient = null,
Func<StructuredOutputAgentOptions>? optionsFactory = null)
{
ArgumentNullException.ThrowIfNull(builder);
return builder.Use((innerAgent, services) =>
{
chatClient ??= services?.GetService<IChatClient>()
?? throw new InvalidOperationException($"No {nameof(IChatClient)} was provided and none could be resolved from the service provider. Either provide an {nameof(IChatClient)} explicitly or register one in the dependency injection container.");
return new StructuredOutputAgent(innerAgent, chatClient, optionsFactory?.Invoke());
});
}
}
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs
+143 -34
View File
@@ -8,11 +8,13 @@ using System.Text.Json.Serialization;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI.Chat;
using SampleApp;
using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
// Create chat client to be used by chat client agents.
// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
@@ -23,52 +25,159 @@ ChatClient chatClient = new AzureOpenAIClient(
new DefaultAzureCredential())
.GetChatClient(deploymentName);
// Create the ChatClientAgent with the specified name and instructions.
ChatClientAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
// Demonstrates how to work with structured output via ResponseFormat with the non-generic RunAsync method.
// This approach is useful when:
// a. Structured output is used for inter-agent communication, where one agent produces structured output
// and passes it as text to another agent as input, without the need for the caller to directly work with the structured output.
// b. The type of the structured output is not known at compile time, so the generic RunAsync<T> method cannot be used.
// c. The type of the structured output is represented by JSON schema only, without a corresponding class or type in the code.
await UseStructuredOutputWithResponseFormatAsync(chatClient);
// Set PersonInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke the agent with some unstructured input.
AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
// Demonstrates how to work with structured output via the generic RunAsync<T> method.
// This approach is useful when the caller needs to directly work with the structured output in the code
// via an instance of the corresponding class or type and the type is known at compile time.
await UseStructuredOutputWithRunAsync(chatClient);
// Access the structured output via the Result property of the agent response.
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {response.Result.Name}");
Console.WriteLine($"Age: {response.Result.Age}");
Console.WriteLine($"Occupation: {response.Result.Occupation}");
// Demonstrates how to work with structured output when streaming using the RunStreamingAsync method.
await UseStructuredOutputWithRunStreamingAsync(chatClient);
// Create the ChatClientAgent with the specified name, instructions, and expected structured output the agent should produce.
ChatClientAgent agentWithPersonInfo = chatClient.AsAIAgent(new ChatClientAgentOptions()
// Demonstrates how to add structured output support to agents that don't natively support it using the structured output middleware.
// This approach is useful when working with agents that don't support structured output natively, or agents using models
// that don't have the capability to produce structured output, allowing you to still leverage structured output features by transforming
// the text output from the agent into structured data using a chat client.
await UseStructuredOutputWithMiddlewareAsync(chatClient);
static async Task UseStructuredOutputWithResponseFormatAsync(ChatClient chatClient)
{
Name = "HelpfulAssistant",
ChatOptions = new() { Instructions = "You are a helpful assistant.", ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>() }
});
Console.WriteLine("=== Structured Output with ResponseFormat ===");
// Invoke the agent with some unstructured input while streaming, to extract the structured information from.
var updates = agentWithPersonInfo.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
// Create the agent
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
{
Name = "HelpfulAssistant",
ChatOptions = new()
{
Instructions = "You are a helpful assistant.",
// Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
}
});
// Assemble all the parts of the streamed output, since we can only deserialize once we have the full json,
// then deserialize the response into the PersonInfo class.
PersonInfo personInfo = (await updates.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);
// Invoke the agent with some unstructured input to extract the structured information from.
AgentResponse response = await agent.RunAsync("Provide information about the capital of France.");
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {personInfo.Name}");
Console.WriteLine($"Age: {personInfo.Age}");
Console.WriteLine($"Occupation: {personInfo.Occupation}");
// Access the structured output via the Text property of the agent response as JSON in scenarios when JSON as text is required
// and no object instance is needed (e.g., for logging, forwarding to another service, or storing in a database).
Console.WriteLine("Assistant Output (JSON):");
Console.WriteLine(response.Text);
Console.WriteLine();
// Deserialize the JSON text to work with the structured object in scenarios when you need to access properties,
// perform operations, or pass the data to methods that require the typed object instance.
CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(response.Text)!;
Console.WriteLine("Assistant Output (Deserialized):");
Console.WriteLine($"Name: {cityInfo.Name}");
Console.WriteLine();
}
static async Task UseStructuredOutputWithRunAsync(ChatClient chatClient)
{
Console.WriteLine("=== Structured Output with RunAsync<T> ===");
// Create the agent
AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
// Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
// Access the structured output via the Result property of the agent response.
CityInfo cityInfo = response.Result;
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {cityInfo.Name}");
Console.WriteLine();
}
static async Task UseStructuredOutputWithRunStreamingAsync(ChatClient chatClient)
{
Console.WriteLine("=== Structured Output with RunStreamingAsync ===");
// Create the agent
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
{
Name = "HelpfulAssistant",
ChatOptions = new()
{
Instructions = "You are a helpful assistant.",
// Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
}
});
// Invoke the agent with some unstructured input while streaming, to extract the structured information from.
IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Provide information about the capital of France.");
// Assemble all the parts of the streamed output.
AgentResponse nonGenericResponse = await updates.ToAgentResponseAsync();
// Access the structured output by deserializing JSON in the Text property.
CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(nonGenericResponse.Text)!;
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {cityInfo.Name}");
Console.WriteLine();
}
static async Task UseStructuredOutputWithMiddlewareAsync(ChatClient chatClient)
{
Console.WriteLine("=== Structured Output with UseStructuredOutput Middleware ===");
// Create chat client that will transform the agent text response into structured output.
IChatClient meaiChatClient = chatClient.AsIChatClient();
// Create the agent
AIAgent agent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
// Add structured output middleware via UseStructuredOutput method to add structured output support to the agent.
// This middleware transforms the agent's text response into structured data using a chat client.
// Since our agent does support structured output natively, we will add a middleware that removes ResponseFormat
// from the AgentRunOptions to emulate an agent that doesn't support structured output natively
agent = agent
.AsBuilder()
.UseStructuredOutput(meaiChatClient)
.Use(ResponseFormatRemovalMiddleware, null)
.Build();
// Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
// Access the structured output via the Result property of the agent response.
CityInfo cityInfo = response.Result;
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {cityInfo.Name}");
Console.WriteLine();
}
static Task<AgentResponse> ResponseFormatRemovalMiddleware(IEnumerable<ChatMessage> messages, AgentSession? session, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken)
{
// Remove any ResponseFormat from the options to emulate an agent that doesn't support structured output natively.
options = options?.Clone();
options?.ResponseFormat = null;
return innerAgent.RunAsync(messages, session, options, cancellationToken);
}
namespace SampleApp
{
/// <summary>
/// Represents information about a person, including their name, age, and occupation, matched to the JSON schema used in the agent.
/// Represents information about a city, including its name.
/// </summary>
[Description("Information about a person including their name, age, and occupation")]
public class PersonInfo
[Description("Information about a city")]
public sealed class CityInfo
{
[JsonPropertyName("name")]
public string? Name { get; set; }
[JsonPropertyName("age")]
public int? Age { get; set; }
[JsonPropertyName("occupation")]
public string? Occupation { get; set; }
}
}
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/README.md
+52
View File
@@ -0,0 +1,52 @@
# Structured Output with ChatClientAgent
This sample demonstrates how to configure ChatClientAgent to produce structured output in JSON format using various approaches.
## What this sample demonstrates
- **ResponseFormat approach**: Configuring agents with JSON schema response format via `ChatResponseFormat.ForJsonSchema<T>()` for inter-agent communication or when the type is not known at compile time
- **Generic RunAsync<T> method**: Using the generic `RunAsync<T>` method for structured output when the caller needs to work directly with typed objects
- **Structured output with Streaming**: Using `RunStreamingAsync` to stream responses while still obtaining structured output by assembling and deserializing the streamed content
- **StructuredOutput middleware**: Adding structured output support to agents that don't natively support it (like A2A agents or models without structured output capability) by transforming text output into structured data using a chat client
## Prerequisites
Before you begin, ensure you have the following prerequisites:
- .NET 10 SDK or later
- Azure OpenAI service endpoint and deployment configured
- Azure CLI installed and authenticated (for Azure credential authentication)
- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
**Note**: This sample uses Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
## Environment Variables
Set the following environment variables:
```powershell
$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini" # Optional, defaults to gpt-4o-mini
```
## Run the sample
Navigate to the sample directory and run:
```powershell
cd dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput
dotnet run
```
## Expected behavior
The sample will demonstrate four different approaches to structured output:
1. **Structured Output with ResponseFormat**: Creates an agent with `ResponseFormat` set to `ForJsonSchema<CityInfo>()`, invokes it with unstructured input, and accesses the structured output via the `Text` property
2. **Structured Output with RunAsync<T>**: Creates an agent and uses the generic `RunAsync<CityInfo>()` method to get a typed `AgentResponse<CityInfo>` with the result accessible via the `Result` property
3. **Structured Output with RunStreamingAsync**: Creates an agent with JSON schema response format, streams the response using `RunStreamingAsync`, assembles the updates using `ToAgentResponseAsync()`, and deserializes the JSON text into a typed object
4. **Structured Output with StructuredOutput Middleware**: Uses the `UseStructuredOutput` method on `AIAgentBuilder` to add structured output support to agents that don't natively support it
Each approach will output information about the capital of France (Paris) in a structured format.
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgent.cs
+88
View File
@@ -0,0 +1,88 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
namespace SampleApp;
/// <summary>
/// A delegating AI agent that converts text responses from an inner AI agent into structured output using a chat client.
/// </summary>
/// <remarks>
/// <para>
/// The <see cref="StructuredOutputAgent"/> wraps an inner agent and uses a chat client to transform
/// the inner agent's text response into a structured JSON format based on the specified response format.
/// </para>
/// <para>
/// This agent requires a <see cref="ChatResponseFormatJson"/> to be specified either through the
/// <see cref="AgentRunOptions.ResponseFormat"/> or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
/// provided during construction.
/// </para>
/// </remarks>
internal sealed class StructuredOutputAgent : DelegatingAIAgent
{
private readonly IChatClient _chatClient;
private readonly StructuredOutputAgentOptions? _agentOptions;
/// <summary>
/// Initializes a new instance of the <see cref="StructuredOutputAgent"/> class.
/// </summary>
/// <param name="innerAgent">The underlying agent that generates text responses to be converted to structured output.</param>
/// <param name="chatClient">The chat client used to transform text responses into structured JSON format.</param>
/// <param name="options">Optional configuration options for the structured output agent.</param>
public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient, StructuredOutputAgentOptions? options = null)
: base(innerAgent)
{
this._chatClient = chatClient ?? throw new ArgumentNullException(nameof(chatClient));
this._agentOptions = options;
}
/// <inheritdoc />
protected override async Task<AgentResponse> RunCoreAsync(
IEnumerable<ChatMessage> messages,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default)
{
// Run the inner agent first, to get back the text response we want to convert.
var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
// Invoke the chat client to transform the text output into structured data.
ChatResponse soResponse = await this._chatClient.GetResponseAsync(
messages: this.GetChatMessages(textResponse.Text),
options: this.GetChatOptions(options),
cancellationToken: cancellationToken).ConfigureAwait(false);
return new StructuredOutputAgentResponse(soResponse, textResponse);
}
private List<ChatMessage> GetChatMessages(string? textResponseText)
{
List<ChatMessage> chatMessages = [];
if (this._agentOptions?.ChatClientSystemMessage is not null)
{
chatMessages.Add(new ChatMessage(ChatRole.System, this._agentOptions.ChatClientSystemMessage));
}
chatMessages.Add(new ChatMessage(ChatRole.User, textResponseText));
return chatMessages;
}
private ChatOptions GetChatOptions(AgentRunOptions? options)
{
ChatResponseFormat responseFormat = options?.ResponseFormat
?? this._agentOptions?.ChatOptions?.ResponseFormat
?? throw new InvalidOperationException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but none was specified.");
if (responseFormat is not ChatResponseFormatJson jsonResponseFormat)
{
throw new NotSupportedException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but was '{responseFormat.GetType().Name}'.");
}
var chatOptions = this._agentOptions?.ChatOptions?.Clone() ?? new ChatOptions();
chatOptions.ResponseFormat = jsonResponseFormat;
return chatOptions;
}
}
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgentOptions.cs
+31
View File
@@ -0,0 +1,31 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
namespace SampleApp;
/// <summary>
/// Represents configuration options for a <see cref="StructuredOutputAgent"/>.
/// </summary>
#pragma warning disable CA1812 // Instantiated via AIAgentBuilderExtensions.UseStructuredOutput optionsFactory parameter
internal sealed class StructuredOutputAgentOptions
#pragma warning restore CA1812
{
/// <summary>
/// Gets or sets the system message to use when invoking the chat client for structured output conversion.
/// </summary>
public string? ChatClientSystemMessage { get; set; }
/// <summary>
/// Gets or sets the chat options to use for the structured output conversion by the chat client
/// used by the agent.
/// </summary>
/// <remarks>
/// This property is optional. The <see cref="ChatOptions.ResponseFormat"/> should be set to a
/// <see cref="ChatResponseFormatJson"/> instance to specify the expected JSON schema for the structured output.
/// Note that if <see cref="AgentRunOptions.ResponseFormat"/> is provided when running the agent,
/// it will take precedence and override the <see cref="ChatOptions.ResponseFormat"/> specified here.
/// </remarks>
public ChatOptions? ChatOptions { get; set; }
}
dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgentResponse.cs
+28
View File
@@ -0,0 +1,28 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
namespace SampleApp;
/// <summary>
/// Represents an agent response that contains structured output and
/// the original agent response from which the structured output was generated.
/// </summary>
internal sealed class StructuredOutputAgentResponse : AgentResponse
{
/// <summary>
/// Initializes a new instance of the <see cref="StructuredOutputAgentResponse"/> class.
/// </summary>
/// <param name="chatResponse">The <see cref="ChatResponse"/> containing the structured output.</param>
/// <param name="agentResponse">The original <see cref="AgentResponse"/> from the inner agent.</param>
public StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
{
this.OriginalResponse = agentResponse;
}
/// <summary>
/// Gets the original non-structured response from the inner agent used by chat client to produce the structured output.
/// </summary>
public AgentResponse OriginalResponse { get; }
}
dotnet/samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Program.cs
+8 -7
View File
@@ -1,5 +1,7 @@
// Copyright (c) Microsoft. All rights reserved.
#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
// This sample shows how to create and use a simple AI agent with a conversation that can be persisted to disk.
using System.Text.Json;
@@ -30,15 +32,14 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
// Serialize the session state to a JsonElement, so it can be stored for later use.
JsonElement serializedSession = await agent.SerializeSessionAsync(session);
// Save the serialized session to a temporary file (for demonstration purposes).
string tempFilePath = Path.GetTempFileName();
await File.WriteAllTextAsync(tempFilePath, JsonSerializer.Serialize(serializedSession));
// Load the serialized session from the temporary file (for demonstration purposes).
JsonElement reloadedSerializedSession = JsonElement.Parse(await File.ReadAllTextAsync(tempFilePath));
// In a real application, you would typically write the serialized session to a file or
// database for persistence, and read it back when resuming the conversation.
// Here we'll just write the serialized session to console (for demonstration purposes).
Console.WriteLine("\n--- Serialized session ---\n");
Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }) + "\n");
// Deserialize the session state after loading from storage.
AgentSession resumedSession = await agent.DeserializeSessionAsync(reloadedSerializedSession);
AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSession);
// Run the agent again with the resumed session.
Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
dotnet/samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Program.cs
+43 -36
View File
@@ -3,7 +3,7 @@
#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
// This sample shows how to create and use a simple AI agent with custom ChatHistoryProvider that stores chat history in a custom storage location.
// The state of the custom ChatHistoryProvider (SessionDbKey) is stored with the agent session, so that when the session is resumed later,
// The state of the custom ChatHistoryProvider (SessionDbKey) is stored in the AgentSession's StateBag, so that when the session is resumed later,
// the chat history can be retrieved from the custom storage location.
using System.Text.Json;
@@ -36,11 +36,8 @@ AIAgent agent = new AzureOpenAIClient(
{
ChatOptions = new() { Instructions = "You are good at telling jokes." },
Name = "Joker",
ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
// Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
// Each session must get its own copy of the VectorChatHistoryProvider, since the provider
// also contains the id that the chat history is stored under.
new VectorChatHistoryProvider(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions))
// Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
ChatHistoryProvider = new VectorChatHistoryProvider(vectorStore)
});
// Start a new session for the agent conversation.
@@ -66,80 +63,90 @@ AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSess
// Run the agent with the session that stores chat history in the vector store a second time.
Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
// We can access the VectorChatHistoryProvider via the session's GetService method if we need to read the key under which chat history is stored.
var chatHistoryProvider = resumedSession.GetService<VectorChatHistoryProvider>()!;
Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.SessionDbKey}");
// We can access the VectorChatHistoryProvider via the agent's GetService method
// if we need to read the key under which chat history is stored. The key is stored
// in the session state, and therefore we need to provide the session when reading it.
var chatHistoryProvider = agent.GetService<VectorChatHistoryProvider>()!;
Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.GetSessionDbKey(resumedSession)}");
namespace SampleApp
{
/// <summary>
/// A sample implementation of <see cref="ChatHistoryProvider"/> that stores chat history in a vector store.
/// State (the session DB key) is stored in the <see cref="AgentSession.StateBag"/> so it roundtrips
/// automatically with session serialization.
/// </summary>
internal sealed class VectorChatHistoryProvider : ChatHistoryProvider
{
private readonly ProviderSessionState<State> _sessionState;
private readonly VectorStore _vectorStore;
public VectorChatHistoryProvider(VectorStore vectorStore, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
public VectorChatHistoryProvider(
VectorStore vectorStore,
Func<AgentSession?, State>? stateInitializer = null,
string? stateKey = null)
: base(provideOutputMessageFilter: null, storeInputMessageFilter: null)
{
this._sessionState = new ProviderSessionState<State>(
stateInitializer ?? (_ => new State(Guid.NewGuid().ToString("N"))),
stateKey ?? this.GetType().Name);
this._vectorStore = vectorStore ?? throw new ArgumentNullException(nameof(vectorStore));
if (serializedState.ValueKind is JsonValueKind.String)
{
// Here we can deserialize the session id so that we can access the same messages as before the suspension.
this.SessionDbKey = serializedState.Deserialize<string>();
}
}
public string? SessionDbKey { get; private set; }
public override string StateKey => this._sessionState.StateKey;
protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
public string GetSessionDbKey(AgentSession session)
=> this._sessionState.GetOrInitializeState(session).SessionDbKey;
protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
{
var state = this._sessionState.GetOrInitializeState(context.Session);
var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
await collection.EnsureCollectionExistsAsync(cancellationToken);
var records = await collection
.GetAsync(
x => x.SessionId == this.SessionDbKey, 10,
x => x.SessionId == state.SessionDbKey, 10,
new() { OrderBy = x => x.Descending(y => y.Timestamp) },
cancellationToken)
.ToListAsync(cancellationToken);
var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!)
;
var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
messages.Reverse();
return messages;
}
protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
protected override async ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
{
// Don't store messages if the request failed.
if (context.InvokeException is not null)
{
return;
}
this.SessionDbKey ??= Guid.NewGuid().ToString("N");
var state = this._sessionState.GetOrInitializeState(context.Session);
var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
await collection.EnsureCollectionExistsAsync(cancellationToken);
// Add both request and response messages to the store
// Optionally messages produced by the AIContextProvider can also be persisted (not shown).
var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
{
Key = this.SessionDbKey + x.MessageId,
Key = state.SessionDbKey + x.MessageId,
Timestamp = DateTimeOffset.UtcNow,
SessionId = this.SessionDbKey,
SessionId = state.SessionDbKey,
SerializedMessage = JsonSerializer.Serialize(x),
MessageText = x.Text
}), cancellationToken);
}
public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null) =>
// We have to serialize the session id, so that on deserialization we can retrieve the messages using the same session id.
JsonSerializer.SerializeToElement(this.SessionDbKey);
/// <summary>
/// Represents the per-session state stored in the <see cref="AgentSession.StateBag"/>.
/// </summary>
public sealed class State
{
public State(string sessionDbKey)
{
this.SessionDbKey = sessionDbKey ?? throw new ArgumentNullException(nameof(sessionDbKey));
}
public string SessionDbKey { get; }
}
/// <summary>
/// The data structure used to store chat history items in the vector store.
dotnet/samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/README.md
+2 -2
View File
@@ -11,9 +11,9 @@ Alternatively, use the QuickstartClient sample from this repository: https://git
To use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), follow these steps:
1. Open a terminal in the Agent_Step10_AsMcpTool project directory.
1. Run the `npx @modelcontextprotocol/inspector dotnet run` command to start the MCP Inspector. Make sure you have [node.js](https://nodejs.org/en/download/) and npm installed.
1. Run the `npx @modelcontextprotocol/inspector dotnet run --framework net10.0` command to start the MCP Inspector. Make sure you have [node.js](https://nodejs.org/en/download/) and npm installed.
```bash
npx @modelcontextprotocol/inspector dotnet run
npx @modelcontextprotocol/inspector dotnet run --framework net10.0
```
1. When the inspector is running, it will display a URL in the terminal, like this:
```
dotnet/samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Program.cs
+18 -4
View File
@@ -27,7 +27,7 @@ AIAgent agent = new AzureOpenAIClient(
{
ChatOptions = new() { Instructions = "You are good at telling jokes." },
Name = "Joker",
ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions))
ChatHistoryProvider = new InMemoryChatHistoryProvider(new() { ChatReducer = new MessageCountingChatReducer(2) })
});
AgentSession session = await agent.CreateSessionAsync();
@@ -36,17 +36,31 @@ AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
// Get the chat history to see how many messages are stored.
IList<ChatMessage>? chatHistory = session.GetService<IList<ChatMessage>>();
// We can use the ChatHistoryProvider, that is also used by the agent, to read the
// chat history from the session state, and see how the reducer is affecting the stored messages.
// Here we expect to see 2 messages, the original user message and the agent response message.
var provider = agent.GetService<InMemoryChatHistoryProvider>();
List<ChatMessage>? chatHistory = provider?.GetMessages(session);
Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
// Invoke the agent a few more times.
Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session));
// Now we expect to see 4 messages in the chat history, 2 input and 2 output.
// While the target number of messages is 2, the default time for the InMemoryChatHistoryProvider
// to trigger the reducer is just before messages are contributed to a new agent run.
// So at this time, we have not yet triggered the reducer for the most recently added messages,
// and they are still in the chat history.
chatHistory = provider?.GetMessages(session);
Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
Console.WriteLine(await agent.RunAsync("Tell me a joke about a lemur.", session));
chatHistory = provider?.GetMessages(session);
Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
// At this point, the chat history has exceeded the limit and the original message will not exist anymore,
// so asking a follow up question about it will not work as expected.
Console.WriteLine(await agent.RunAsync("Tell me the joke about the pirate again, but add emojis and use the voice of a parrot.", session));
// so asking a follow up question about it may not work as expected.
Console.WriteLine(await agent.RunAsync("What was the first joke I asked you to tell again?", session));
chatHistory = provider?.GetMessages(session);
Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
dotnet/samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Program.cs
+62 -110
View File
@@ -1,13 +1,12 @@
// Copyright (c) Microsoft. All rights reserved.
// This sample shows how to inject additional AI context into a ChatClientAgent using a custom AIContextProvider component that is attached to the agent.
// The sample also shows how to combine the results from multiple providers into a single class, in order to attach multiple of these to an agent.
// This sample shows how to inject additional AI context into a ChatClientAgent using custom AIContextProvider components that are attached to the agent.
// Multiple providers can be attached to an agent, and they will be called in sequence, each receiving the accumulated context from the previous one.
// This mechanism can be used for various purposes, such as injecting RAG search results or memories into the agent's context.
// Also note that Agent Framework already provides built-in AIContextProviders for many of these scenarios.
#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
using System.ComponentModel;
using System.Text;
using System.Text.Json;
using Azure.AI.OpenAI;
@@ -48,16 +47,20 @@ AIAgent agent = new AzureOpenAIClient(
You manage a TODO list for the user. When the user has completed one of the tasks it can be removed from the TODO list. Only provide the list of TODO items if asked.
You remind users of upcoming calendar events when the user interacts with you.
""" },
ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider()
// Use WithAIContextProviderMessageRemoval, so that we don't store the messages from the AI context provider in the chat history.
ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
{
// Use StorageInputMessageFilter to provide a custom filter for messages stored in chat history.
// By default the chat history provider will store all messages, except for those that came from chat history in the first place.
// In this case, we want to also exclude messages that came from AI context providers.
// You may want to store these messages, depending on their content and your requirements.
.WithAIContextProviderMessageRemoval()),
// Add an AI context provider that maintains a todo list for the agent and one that provides upcoming calendar entries.
// Wrap these in an AI context provider that aggregates the other two.
AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new AggregatingAIContextProvider([
AggregatingAIContextProvider.CreateFactory((jsonElement, jsonSerializerOptions) => new TodoListAIContextProvider(jsonElement, jsonSerializerOptions)),
AggregatingAIContextProvider.CreateFactory((_, _) => new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents))
], ctx.SerializedState, ctx.JsonSerializerOptions)),
StorageInputMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
}),
// Add multiple AI context providers: one that maintains a todo list and one that provides upcoming calendar entries.
// The agent will call each provider in sequence, accumulating context from each.
AIContextProviders = [
new TodoListAIContextProvider(),
new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents)
],
});
// Invoke the agent and output the text result.
@@ -83,51 +86,67 @@ namespace SampleApp
/// </summary>
internal sealed class TodoListAIContextProvider : AIContextProvider
{
private readonly List<string> _todoItems = new();
private static List<string> GetTodoItems(AgentSession? session)
=> session?.StateBag.GetValue<List<string>>(nameof(TodoListAIContextProvider)) ?? new List<string>();
public TodoListAIContextProvider(JsonElement jsonElement, JsonSerializerOptions? jsonSerializerOptions = null)
{
// Only try and restore the state if we got an array, since any other json would be invalid or undefined/null meaning
// it's the first time we are running.
if (jsonElement.ValueKind == JsonValueKind.Array)
{
this._todoItems = JsonSerializer.Deserialize<List<string>>(jsonElement.GetRawText(), jsonSerializerOptions) ?? new List<string>();
}
}
private static void SetTodoItems(AgentSession? session, List<string> items)
=> session?.StateBag.SetValue(nameof(TodoListAIContextProvider), items);
protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
{
var inputContext = context.AIContext;
var todoItems = GetTodoItems(context.Session);
StringBuilder outputMessageBuilder = new();
outputMessageBuilder.AppendLine("Your todo list contains the following items:");
if (this._todoItems.Count == 0)
if (todoItems.Count == 0)
{
outputMessageBuilder.AppendLine(" (no items)");
}
else
{
for (int i = 0; i < this._todoItems.Count; i++)
for (int i = 0; i < todoItems.Count; i++)
{
outputMessageBuilder.AppendLine($"{i}. {this._todoItems[i]}");
outputMessageBuilder.AppendLine($"{i}. {todoItems[i]}");
}
}
return new ValueTask<AIContext>(new AIContext
{
Tools = [AIFunctionFactory.Create(this.AddTodoItem), AIFunctionFactory.Create(this.RemoveTodoItem)],
Messages = [new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())]
Instructions = inputContext.Instructions,
Tools = (inputContext.Tools ?? []).Concat(new AITool[]
{
AIFunctionFactory.Create((string item) => AddTodoItem(context.Session, item), "AddTodoItem", "Adds an item to the todo list."),
AIFunctionFactory.Create((int index) => RemoveTodoItem(context.Session, index), "RemoveTodoItem", "Removes an item from the todo list. Index is zero based.")
}),
Messages =
(inputContext.Messages ?? [])
.Concat(
[
new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
])
});
}
[Description("Adds an item to the todo list. Index is zero based.")]
private void RemoveTodoItem(int index) =>
this._todoItems.RemoveAt(index);
private static void RemoveTodoItem(AgentSession? session, int index)
{
var items = GetTodoItems(session);
items.RemoveAt(index);
SetTodoItems(session, items);
}
private void AddTodoItem(string item) =>
this._todoItems.Add(string.IsNullOrWhiteSpace(item) ? throw new ArgumentException("Item must have a value") : item);
private static void AddTodoItem(AgentSession? session, string item)
{
if (string.IsNullOrWhiteSpace(item))
{
throw new ArgumentException("Item must have a value");
}
public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null) =>
JsonSerializer.SerializeToElement(this._todoItems, jsonSerializerOptions);
var items = GetTodoItems(session);
items.Add(item);
SetTodoItems(session, items);
}
}
/// <summary>
@@ -137,6 +156,7 @@ namespace SampleApp
{
protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
{
var inputContext = context.AIContext;
var events = await loadNextThreeCalendarEvents();
StringBuilder outputMessageBuilder = new();
@@ -148,84 +168,16 @@ namespace SampleApp
return new()
{
Instructions = inputContext.Instructions,
Messages =
[
new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()),
]
(inputContext.Messages ?? [])
.Concat(
[
new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
])
.ToList(),
Tools = inputContext.Tools
};
}
}
/// <summary>
/// An <see cref="AIContextProvider"/> which aggregates multiple AI context providers into one.
/// Serialized state for the different providers are stored under their type name.
/// Tools and messages from all providers are combined, and instructions are concatenated.
/// </summary>
internal sealed class AggregatingAIContextProvider : AIContextProvider
{
private readonly List<AIContextProvider> _providers = new();
public AggregatingAIContextProvider(ProviderFactory[] providerFactories, JsonElement jsonElement, JsonSerializerOptions? jsonSerializerOptions)
{
// We received a json object, so let's check if it has some previously serialized state that we can use.
if (jsonElement.ValueKind == JsonValueKind.Object)
{
this._providers = providerFactories
.Select(factory => factory.FactoryMethod(jsonElement.TryGetProperty(factory.ProviderType.Name, out var prop) ? prop : default, jsonSerializerOptions))
.ToList();
return;
}
// We didn't receive any valid json, so we can just construct fresh providers.
this._providers = providerFactories
.Select(factory => factory.FactoryMethod(default, jsonSerializerOptions))
.ToList();
}
protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
{
// Invoke all the sub providers.
var tasks = this._providers.Select(provider => provider.InvokingAsync(context, cancellationToken).AsTask());
var results = await Task.WhenAll(tasks);
// Combine the results from each sub provider.
return new AIContext
{
Tools = results.SelectMany(r => r.Tools ?? []).ToList(),
Messages = results.SelectMany(r => r.Messages ?? []).ToList(),
Instructions = string.Join("\n", results.Select(r => r.Instructions).Where(s => !string.IsNullOrEmpty(s)))
};
}
public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
{
Dictionary<string, JsonElement> elements = new();
foreach (var provider in this._providers)
{
JsonElement element = provider.Serialize(jsonSerializerOptions);
// Don't try to store state for any providers that aren't producing any.
if (element.ValueKind != JsonValueKind.Undefined && element.ValueKind != JsonValueKind.Null)
{
elements[provider.GetType().Name] = element;
}
}
return JsonSerializer.SerializeToElement(elements, jsonSerializerOptions);
}
public static ProviderFactory CreateFactory<TProviderType>(Func<JsonElement, JsonSerializerOptions?, TProviderType> factoryMethod)
where TProviderType : AIContextProvider => new()
{
FactoryMethod = (jsonElement, jsonSerializerOptions) => factoryMethod(jsonElement, jsonSerializerOptions),
ProviderType = typeof(TProviderType)
};
public readonly struct ProviderFactory
{
public Func<JsonElement, JsonSerializerOptions?, AIContextProvider> FactoryMethod { get; init; }
public Type ProviderType { get; init; }
}
}
}
dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs
+2 -1
View File
@@ -64,7 +64,8 @@ IAsyncEnumerable<AgentResponseUpdate> updates = agentWithPersonInfo.RunStreaming
// Assemble all the parts of the streamed output, since we can only deserialize once we have the full json,
// then deserialize the response into the PersonInfo class.
PersonInfo personInfo = (await updates.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);
PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>((await updates.ToAgentResponseAsync()).Text, JsonSerializerOptions.Web)
?? throw new InvalidOperationException("Failed to deserialize the streamed response into PersonInfo.");
Console.WriteLine("Assistant Output:");
Console.WriteLine($"Name: {personInfo.Name}");
dotnet/samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/Resources.cs
+1 -1
View File
@@ -9,5 +9,5 @@ internal static class Resources
{
private const string ResourceFolder = "Resources";
public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
}
dotnet/samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/Resources.cs
+1 -1
View File
@@ -9,5 +9,5 @@ internal static class Resources
{
private const string ResourceFolder = "Resources";
public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
}
dotnet/samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/Resources.cs
+1 -1
View File
@@ -9,5 +9,5 @@ internal static class Resources
{
private const string ResourceFolder = "Resources";
public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
}
dotnet/samples/GettingStarted/Workflows/SharedStates/Resources.cs
+1 -1
View File
@@ -9,5 +9,5 @@ internal static class Resources
{
private const string ResourceFolder = "Resources";
public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
}
dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs
+2 -1
View File
@@ -330,7 +330,8 @@ internal sealed class CriticExecutor : Executor<ChatMessage, CriticDecision>
// Convert the stream to a response and deserialize the structured output
AgentResponse response = await updates.ToAgentResponseAsync(cancellationToken);
CriticDecision decision = response.Deserialize<CriticDecision>(JsonSerializerOptions.Web);
CriticDecision decision = JsonSerializer.Deserialize<CriticDecision>(response.Text, JsonSerializerOptions.Web)
?? throw new JsonException("Failed to deserialize CriticDecision from response text.");
Console.WriteLine($"Decision: {(decision.Approved ? "✅ APPROVED" : "❌ NEEDS REVISION")}");
if (!string.IsNullOrEmpty(decision.Feedback))
dotnet/samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj
-1
View File
@@ -15,7 +15,6 @@
and cannot access parent folders where Directory.Packages.props resides.
-->
<ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
<NoWarn>$(NoWarn);MEAI001;OPENAI001</NoWarn>
</PropertyGroup>
<!--
dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs
+22 -1
View File
@@ -54,7 +54,7 @@ public class WeatherForecastAgent : DelegatingAIAgent
// If the agent returned a valid structured output response
// we might be able to enhance the response with an adaptive card.
if (response.TryDeserialize<WeatherForecastAgentResponse>(JsonSerializerOptions.Web, out var structuredOutput))
if (TryDeserialize<WeatherForecastAgentResponse>(response.Text, JsonSerializerOptions.Web, out var structuredOutput))
{
var textContentMessage = response.Messages.FirstOrDefault(x => x.Contents.OfType<TextContent>().Any());
if (textContentMessage is not null)
@@ -112,4 +112,25 @@ public class WeatherForecastAgent : DelegatingAIAgent
});
return card;
}
private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
{
try
{
T? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
if (result is null)
{
structuredOutput = default!;
return false;
}
structuredOutput = result;
return true;
}
catch
{
structuredOutput = default!;
return false;
}
}
}