From 781a5aef953e3b1de14c7a5f67ffe43b277a1306 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Wed, 26 Nov 2025 13:27:55 +0000 Subject: [PATCH 1/7] Update the declarative agent samples --- .../azure/AzureOpenAIAssistants.yaml | 10 +++---- agent-samples/azure/AzureOpenAIChat.yaml | 25 +++++++++++++++++ agent-samples/azure/AzureOpenAIResponses.yaml | 17 +++++------ agent-samples/chatclient/Assistant.yaml | 6 ++-- agent-samples/chatclient/GetWeather.yaml | 2 ++ agent-samples/foundry/FoundryAgent.yaml | 22 +++++++++++++++ agent-samples/openai/OpenAIAssistants.yaml | 14 ++++------ agent-samples/openai/OpenAIChat.yaml | 28 +++++++++++++++++++ agent-samples/openai/OpenAIResponses.yaml | 16 +++++------ 9 files changed, 106 insertions(+), 34 deletions(-) create mode 100644 agent-samples/azure/AzureOpenAIChat.yaml create mode 100644 agent-samples/foundry/FoundryAgent.yaml create mode 100644 agent-samples/openai/OpenAIChat.yaml diff --git a/agent-samples/azure/AzureOpenAIAssistants.yaml b/agent-samples/azure/AzureOpenAIAssistants.yaml index 8c0d889598..f973d05acc 100644 --- a/agent-samples/azure/AzureOpenAIAssistants.yaml +++ b/agent-samples/azure/AzureOpenAIAssistants.yaml @@ -1,9 +1,9 @@ kind: Prompt name: Assistant description: Helpful assistant -instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response. +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response. model: - id: =Env.AZURE_OPENAI_DEPLOYMENT_NAME + id: gpt-4o-mini provider: AzureOpenAI apiType: Assistants options: @@ -12,14 +12,14 @@ model: outputSchema: properties: language: - kind: string + type: string required: true description: The language of the answer. answer: - kind: string + type: string required: true description: The answer text. type: - kind: string + type: string required: true description: The type of the response. diff --git a/agent-samples/azure/AzureOpenAIChat.yaml b/agent-samples/azure/AzureOpenAIChat.yaml new file mode 100644 index 0000000000..d02e0c6039 --- /dev/null +++ b/agent-samples/azure/AzureOpenAIChat.yaml @@ -0,0 +1,25 @@ +kind: Prompt +name: Assistant +description: Helpful assistant +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response. +model: + id: gpt-4o-mini + provider: AzureOpenAI + apiType: Chat + options: + temperature: 0.9 + topP: 0.95 +outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + type: + type: string + required: true + description: The type of the response. diff --git a/agent-samples/azure/AzureOpenAIResponses.yaml b/agent-samples/azure/AzureOpenAIResponses.yaml index 5db218ade3..006c1476f4 100644 --- a/agent-samples/azure/AzureOpenAIResponses.yaml +++ b/agent-samples/azure/AzureOpenAIResponses.yaml @@ -1,28 +1,25 @@ kind: Prompt name: Assistant description: Helpful assistant -instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response. +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response. model: - id: =Env.AZURE_OPENAI_DEPLOYMENT_NAME + id: gpt-4o-mini provider: AzureOpenAI apiType: Responses options: - text: - verbosity: medium - connection: - kind: remote - endpoint: =Env.AZURE_OPENAI_ENDPOINT + temperature: 0.9 + topP: 0.95 outputSchema: properties: language: - kind: string + type: string required: true description: The language of the answer. answer: - kind: string + type: string required: true description: The answer text. type: - kind: string + type: string required: true description: The type of the response. diff --git a/agent-samples/chatclient/Assistant.yaml b/agent-samples/chatclient/Assistant.yaml index b34add2d23..3332d54540 100644 --- a/agent-samples/chatclient/Assistant.yaml +++ b/agent-samples/chatclient/Assistant.yaml @@ -1,7 +1,7 @@ kind: Prompt name: Assistant description: Helpful assistant -instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. model: options: temperature: 0.9 @@ -9,10 +9,10 @@ model: outputSchema: properties: language: - kind: string + type: string required: true description: The language of the answer. answer: - kind: string + type: string required: true description: The answer text. diff --git a/agent-samples/chatclient/GetWeather.yaml b/agent-samples/chatclient/GetWeather.yaml index 9ed637894d..f32411be98 100644 --- a/agent-samples/chatclient/GetWeather.yaml +++ b/agent-samples/chatclient/GetWeather.yaml @@ -4,6 +4,8 @@ description: Helpful assistant instructions: You are a helpful assistant. You answer questions using the tools provided. model: options: + temperature: 0.9 + topP: 0.95 allowMultipleToolCalls: true chatToolMode: auto tools: diff --git a/agent-samples/foundry/FoundryAgent.yaml b/agent-samples/foundry/FoundryAgent.yaml new file mode 100644 index 0000000000..2de2ea069e --- /dev/null +++ b/agent-samples/foundry/FoundryAgent.yaml @@ -0,0 +1,22 @@ +kind: Prompt +name: Assistant +description: Helpful assistant +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. +model: + id: gpt-4.1-mini + options: + temperature: 0.9 + topP: 0.95 + connection: + kind: Remote + endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT +outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. diff --git a/agent-samples/openai/OpenAIAssistants.yaml b/agent-samples/openai/OpenAIAssistants.yaml index 78bd48d701..c1f20beb38 100644 --- a/agent-samples/openai/OpenAIAssistants.yaml +++ b/agent-samples/openai/OpenAIAssistants.yaml @@ -1,30 +1,28 @@ kind: Prompt name: Assistant description: Helpful assistant -instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response. +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response. model: - id: =Env.OPENAI_MODEL + id: gpt-4.1-mini provider: OpenAI apiType: Assistants options: temperature: 0.9 topP: 0.95 connection: - kind: key + kind: ApiKey key: =Env.OPENAI_APIKEY outputSchema: - name: AssistantResponse - description: The response from the assistant. properties: language: - kind: string + type: string required: true description: The language of the answer. answer: - kind: string + type: string required: true description: The answer text. type: - kind: string + type: string required: true description: The type of the response. diff --git a/agent-samples/openai/OpenAIChat.yaml b/agent-samples/openai/OpenAIChat.yaml new file mode 100644 index 0000000000..832ef4eb15 --- /dev/null +++ b/agent-samples/openai/OpenAIChat.yaml @@ -0,0 +1,28 @@ +kind: Prompt +name: Assistant +description: Helpful assistant +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response. +model: + id: gpt-4.1-mini + provider: OpenAI + apiType: Chat + options: + temperature: 0.9 + topP: 0.95 + connection: + kind: ApiKey + key: =Env.OPENAI_APIKEY +outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + type: + type: string + required: true + description: The type of the response. diff --git a/agent-samples/openai/OpenAIResponses.yaml b/agent-samples/openai/OpenAIResponses.yaml index 0fcda30c9c..efe822233e 100644 --- a/agent-samples/openai/OpenAIResponses.yaml +++ b/agent-samples/openai/OpenAIResponses.yaml @@ -1,28 +1,28 @@ kind: Prompt name: Assistant description: Helpful assistant -instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response. +instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response. model: - id: =Env.OPENAI_MODEL + id: gpt-4.1-mini provider: OpenAI apiType: Responses options: - text: - verbosity: medium + temperature: 0.9 + topP: 0.95 connection: - kind: key + kind: ApiKey key: =Env.OPENAI_APIKEY outputSchema: properties: language: - kind: string + type: string required: true description: The language of the answer. answer: - kind: string + type: string required: true description: The answer text. type: - kind: string + type: string required: true description: The type of the response. From 8bf6dab7e420fb7b01fdf3b3b3331108009d40b3 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Wed, 26 Nov 2025 15:13:46 +0000 Subject: [PATCH 2/7] Add the Microsoft.Agents.AI.Declarative project --- dotnet/agent-framework-dotnet.slnx | 1 + .../AgentBotElementYaml.cs | 91 ++++++++++++++ .../AgentFactory.cs | 62 ++++++++++ .../AggregatorAgentFactory.cs | 50 ++++++++ .../ChatClient/ChatClientAgentFactory.cs | 54 +++++++++ .../CodeInterpreterToolExtensions.cs | 23 ++++ .../Extensions/FileSearchToolExtensions.cs | 28 +++++ .../Extensions/FunctionToolExtensions.cs | 61 ++++++++++ .../McpServerToolApprovalModeExtensions.cs | 30 +++++ .../Extensions/McpServerToolExtensions.cs | 35 ++++++ .../Extensions/ModelOptionsExtensions.cs | 66 +++++++++++ .../Extensions/PromptAgentExtensions.cs | 112 ++++++++++++++++++ .../Extensions/PropertyInfoExtensions.cs | 96 +++++++++++++++ .../Extensions/RecordDataTypeExtensions.cs | 77 ++++++++++++ .../Extensions/RecordDataValueExtensions.cs | 107 +++++++++++++++++ .../Extensions/StringExpressionExtensions.cs | 42 +++++++ .../Extensions/WebSearchToolExtensions.cs | 23 ++++ .../Extensions/YamlAgentFactoryExtensions.cs | 33 ++++++ .../Microsoft.Agents.AI.Declarative.csproj | 44 +++++++ 19 files changed, 1035 insertions(+) create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/AgentBotElementYaml.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/CodeInterpreterToolExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FileSearchToolExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FunctionToolExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolApprovalModeExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/ModelOptionsExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PropertyInfoExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataValueExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/WebSearchToolExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx index 9c5f1a81f3..7282cd8f74 100644 --- a/dotnet/agent-framework-dotnet.slnx +++ b/dotnet/agent-framework-dotnet.slnx @@ -338,6 +338,7 @@ + diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/AgentBotElementYaml.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/AgentBotElementYaml.cs new file mode 100644 index 0000000000..808bf76462 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/AgentBotElementYaml.cs @@ -0,0 +1,91 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Diagnostics.CodeAnalysis; +using System.IO; +using System.Linq; +using Microsoft.Bot.ObjectModel; +using Microsoft.Bot.ObjectModel.Abstractions; +using Microsoft.Bot.ObjectModel.Yaml; +using Microsoft.Extensions.Configuration; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI; + +/// +/// Helper methods for creating from YAML. +/// +internal static class AgentBotElementYaml +{ + /// + /// Convert the given YAML text to a model. + /// + /// YAML representation of the to use to create the prompt function. + /// Optional instance which provides environment variables to the template. + [RequiresDynamicCode("Calls YamlDotNet.Serialization.DeserializerBuilder.DeserializerBuilder()")] + public static GptComponentMetadata FromYaml(string text, IConfiguration? configuration = null) + { + Throw.IfNullOrEmpty(text); + + using var yamlReader = new StringReader(text); + BotElement rootElement = YamlSerializer.Deserialize(yamlReader) ?? throw new InvalidDataException("Text does not contain a valid agent definition."); + + if (rootElement is not GptComponentMetadata promptAgent) + { + throw new InvalidDataException($"Unsupported root element: {rootElement.GetType().Name}. Expected an {nameof(GptComponentMetadata)}."); + } + + var botDefinition = WrapPromptAgentWithBot(promptAgent, configuration); + + return botDefinition.Descendants().OfType().First(); + } + + #region private + private sealed class AgentFeatureConfiguration : IFeatureConfiguration + { + public long GetInt64Value(string settingName, long defaultValue) => defaultValue; + + public string GetStringValue(string settingName, string defaultValue) => defaultValue; + + public bool IsEnvironmentFeatureEnabled(string featureName, bool defaultValue) => true; + + public bool IsTenantFeatureEnabled(string featureName, bool defaultValue) => defaultValue; + } + + public static BotDefinition WrapPromptAgentWithBot(this GptComponentMetadata element, IConfiguration? configuration = null) + { + var botBuilder = + new BotDefinition.Builder + { + Components = + { + new GptComponent.Builder + { + SchemaName = "default-schema", + Metadata = element.ToBuilder(), + } + } + }; + + if (configuration is not null) + { + foreach (var kvp in configuration.AsEnumerable().Where(kvp => kvp.Value is not null)) + { + botBuilder.EnvironmentVariables.Add(new EnvironmentVariableDefinition.Builder() + { + SchemaName = kvp.Key, + Id = Guid.NewGuid(), + DisplayName = kvp.Key, + ValueComponent = new EnvironmentVariableValue.Builder() + { + Id = Guid.NewGuid(), + Value = kvp.Value!, + }, + }); + } + } + + return botBuilder.Build(); + } + #endregion +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs new file mode 100644 index 0000000000..0b60cc86c8 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs @@ -0,0 +1,62 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Bot.ObjectModel; +using Microsoft.Extensions.Configuration; +using Microsoft.PowerFx; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI; + +/// +/// Represents a factory for creating instances. +/// +public abstract class AgentFactory +{ + /// + /// Initializes a new instance of the class. + /// + /// The configuration. + protected AgentFactory(IConfiguration? configuration = null) + { + this.Engine = new RecalcEngine(); + + if (configuration is not null) + { + foreach (var kvp in configuration.AsEnumerable()) + { + this.Engine.UpdateVariable(kvp.Key, kvp.Value ?? string.Empty); + } + } + } + + /// + /// Gets the Power Fx recalculation engine used to evaluate expressions in agent definitions. + /// This engine is configured with variables from the provided during construction. + /// + protected RecalcEngine Engine { get; } + + /// + /// Create a from the specified . + /// + /// Definition of the agent to create. + /// Optional cancellation token. + /// The created , if null the agent type is not supported. + public async Task CreateAsync(GptComponentMetadata promptAgent, CancellationToken cancellationToken = default) + { + Throw.IfNull(promptAgent); + + var agent = await this.TryCreateAsync(promptAgent, cancellationToken).ConfigureAwait(false); + return agent ?? throw new NotSupportedException($"Agent type {promptAgent.Kind} is not supported."); + } + + /// + /// Tries to create a from the specified . + /// + /// Definition of the agent to create. + /// Optional cancellation token. + /// The created , if null the agent type is not supported. + public abstract Task TryCreateAsync(GptComponentMetadata promptAgent, CancellationToken cancellationToken = default); +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs new file mode 100644 index 0000000000..e9ddcdd6d8 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs @@ -0,0 +1,50 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Bot.ObjectModel; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI; + +/// +/// Provides a which aggregates multiple agent factories. +/// +public sealed class AggregatorAgentFactory : AgentFactory +{ + private readonly AgentFactory[] _agentFactories; + + /// Initializes the instance. + /// Ordered instances to aggregate. + /// + /// Where multiple instances are provided, the first factory that supports the will be used. + /// + public AggregatorAgentFactory(params AgentFactory[] agentFactories) + { + Throw.IfNullOrEmpty(agentFactories); + + foreach (AgentFactory agentFactory in agentFactories) + { + Throw.IfNull(agentFactory, nameof(agentFactories)); + } + + this._agentFactories = agentFactories; + } + + /// + public override async Task TryCreateAsync(GptComponentMetadata promptAgent, CancellationToken cancellationToken = default) + { + Throw.IfNull(promptAgent); + + foreach (var agentFactory in this._agentFactories) + { + var agent = await agentFactory.TryCreateAsync(promptAgent, cancellationToken).ConfigureAwait(false); + if (agent is not null) + { + return agent; + } + } + + return null; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs new file mode 100644 index 0000000000..1a9a3b7a4b --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs @@ -0,0 +1,54 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Bot.ObjectModel; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Logging; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI; + +/// +/// Provides an which creates instances of . +/// +public sealed class ChatClientAgentFactory : AgentFactory +{ + /// + /// Creates a new instance of the class. + /// + public ChatClientAgentFactory(IChatClient chatClient, IList? functions = null, IConfiguration? configuration = null, ILoggerFactory? loggerFactory = null) : base(configuration) + { + Throw.IfNull(chatClient); + + this._chatClient = chatClient; + this._functions = functions; + this._loggerFactory = loggerFactory; + } + + /// + public override Task TryCreateAsync(GptComponentMetadata promptAgent, CancellationToken cancellationToken = default) + { + Throw.IfNull(promptAgent); + + var options = new ChatClientAgentOptions() + { + Name = promptAgent.Name, + Description = promptAgent.Description, + Instructions = promptAgent.Instructions?.ToTemplateString(), + ChatOptions = promptAgent.GetChatOptions(this._functions), + }; + + var agent = new ChatClientAgent(this._chatClient, options, this._loggerFactory); + + return Task.FromResult(agent); + } + + #region private + private readonly IChatClient _chatClient; + private readonly IList? _functions; + private readonly ILoggerFactory? _loggerFactory; + #endregion +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/CodeInterpreterToolExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/CodeInterpreterToolExtensions.cs new file mode 100644 index 0000000000..e6f13d5f54 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/CodeInterpreterToolExtensions.cs @@ -0,0 +1,23 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class CodeInterpreterToolExtensions +{ + /// + /// Creates a from a . + /// + /// Instance of + internal static HostedCodeInterpreterTool AsCodeInterpreterTool(this CodeInterpreterTool tool) + { + Throw.IfNull(tool); + + return new HostedCodeInterpreterTool(); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FileSearchToolExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FileSearchToolExtensions.cs new file mode 100644 index 0000000000..5e1cb1bb5f --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FileSearchToolExtensions.cs @@ -0,0 +1,28 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class FileSearchToolExtensions +{ + /// + /// Create a from a . + /// + /// Instance of + internal static HostedFileSearchTool CreateFileSearchTool(this FileSearchTool tool) + { + Throw.IfNull(tool); + + return new HostedFileSearchTool() + { + MaximumResultCount = (int?)tool.MaximumResultCount?.LiteralValue, + Inputs = tool.VectorStoreIds?.LiteralValue.Select(id => (AIContent)new HostedVectorStoreContent(id)).ToList(), + }; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FunctionToolExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FunctionToolExtensions.cs new file mode 100644 index 0000000000..2c54d7e749 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/FunctionToolExtensions.cs @@ -0,0 +1,61 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class FunctionToolExtensions +{ + /// + /// Creates a from a . + /// + /// + /// If a matching function already exists in the provided list, it will be returned. + /// Otherwise, a new function declaration will be created. + /// + /// Instance of + /// Instance of + internal static AITool CreateOrGetAITool(this InvokeClientTaskAction tool, IList? functions) + { + Throw.IfNull(tool); + Throw.IfNull(tool.Name); + + // use the tool from the provided list if it exists + if (functions is not null) + { + var function = functions.FirstOrDefault(f => tool.Matches(f)); + + if (function is not null) + { + return function; + } + } + + return AIFunctionFactory.CreateDeclaration( + name: tool.Name, + description: tool.Description, + jsonSchema: tool.ClientActionInputSchema?.GetSchema() ?? s_defaultSchema); + } + + /// + /// Checks if a matches an . + /// + /// Instance of + /// Instance of + internal static bool Matches(this InvokeClientTaskAction tool, AIFunction aiFunc) + { + Throw.IfNull(tool); + Throw.IfNull(aiFunc); + + return tool.Name == aiFunc.Name; + } + + private static readonly JsonElement s_defaultSchema = JsonDocument.Parse("{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false}").RootElement; +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolApprovalModeExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolApprovalModeExtensions.cs new file mode 100644 index 0000000000..ee5632368b --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolApprovalModeExtensions.cs @@ -0,0 +1,30 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.Extensions.AI; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class McpServerToolApprovalModeExtensions +{ + /// + /// Converts a to a . + /// + /// Instance of + internal static HostedMcpServerToolApprovalMode AsHostedMcpServerToolApprovalMode(this McpServerToolApprovalMode mode) + { + return mode switch + { + McpServerToolNeverRequireApprovalMode => HostedMcpServerToolApprovalMode.NeverRequire, + McpServerToolAlwaysRequireApprovalMode => HostedMcpServerToolApprovalMode.AlwaysRequire, + McpServerToolRequireSpecificApprovalMode specificMode => + HostedMcpServerToolApprovalMode.RequireSpecific( + specificMode?.AlwaysRequireApprovalToolNames?.LiteralValue ?? [], + specificMode?.NeverRequireApprovalToolNames?.LiteralValue ?? [] + ), + _ => HostedMcpServerToolApprovalMode.AlwaysRequire, + }; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolExtensions.cs new file mode 100644 index 0000000000..763e402625 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/McpServerToolExtensions.cs @@ -0,0 +1,35 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class McpServerToolExtensions +{ + /// + /// Creates a from a . + /// + /// Instance of + internal static HostedMcpServerTool CreateHostedMcpTool(this McpServerTool tool) + { + Throw.IfNull(tool); + Throw.IfNull(tool.ServerName?.LiteralValue); + Throw.IfNull(tool.Connection); + + var connection = tool.Connection as AnonymousConnection ?? throw new ArgumentException("Only AnonymousConnection is supported for MCP Server Tool connections.", nameof(tool)); + var serverUrl = connection.Endpoint?.LiteralValue; + Throw.IfNullOrEmpty(serverUrl, nameof(connection.Endpoint)); + + return new HostedMcpServerTool(tool.ServerName.LiteralValue, serverUrl) + { + ServerDescription = tool.ServerDescription?.LiteralValue, + AllowedTools = tool.AllowedTools?.LiteralValue, + ApprovalMode = tool.ApprovalMode?.AsHostedMcpServerToolApprovalMode(), + }; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/ModelOptionsExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/ModelOptionsExtensions.cs new file mode 100644 index 0000000000..7ad4d26a6b --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/ModelOptionsExtensions.cs @@ -0,0 +1,66 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class ModelOptionsExtensions +{ + /// + /// Converts the 'chatToolMode' property from a to a . + /// + /// Instance of + internal static ChatToolMode? AsChatToolMode(this ModelOptions modelOptions) + { + Throw.IfNull(modelOptions); + + var mode = modelOptions.ExtensionData?.GetPropertyOrNull(InitializablePropertyPath.Create("chatToolMode"))?.Value; + if (mode is null) + { + return null; + } + + return mode switch + { + "auto" => ChatToolMode.Auto, + "none" => ChatToolMode.None, + "require_any" => ChatToolMode.RequireAny, + _ => ChatToolMode.RequireSpecific(mode), + }; + } + + /// + /// Retrieves the 'additional_properties' property from a . + /// + /// Instance of + /// List of properties which should not be included in additional properties. + internal static AdditionalPropertiesDictionary? GetAdditionalProperties(this ModelOptions modelOptions, string[] excludedProperties) + { + Throw.IfNull(modelOptions); + + var options = modelOptions.ExtensionData; + if (options is null || options.Properties.Count == 0) + { + return null; + } + + var additionalProperties = options.Properties + .Where(kvp => !excludedProperties.Contains(kvp.Key)) + .ToDictionary( + kvp => kvp.Key, + kvp => kvp.Value?.ToObject()); + + if (additionalProperties is null || additionalProperties.Count == 0) + { + return null; + } + + return new AdditionalPropertiesDictionary(additionalProperties); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs new file mode 100644 index 0000000000..dacc83bc63 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs @@ -0,0 +1,112 @@ +// Copyright (c) Microsoft. All rights reserved. +using System; +using System.Collections.Generic; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +public static class PromptAgentExtensions +{ + /// + /// Retrieves the 'options' property from a as a instance. + /// + /// Instance of + /// Instance of + public static ChatOptions? GetChatOptions(this GptComponentMetadata promptAgent, IList? functions) + { + Throw.IfNull(promptAgent); + + var outputSchema = promptAgent.OutputType; + var modelOptions = promptAgent.Model?.Options; + + var tools = promptAgent.GetAITools(functions); + + if (modelOptions is null && tools is null) + { + return null; + } + + return new ChatOptions() + { + Instructions = promptAgent.ResponseInstructions?.ToTemplateString(), + Temperature = (float?)modelOptions?.Temperature?.LiteralValue, + MaxOutputTokens = (int?)modelOptions?.MaxOutputTokens?.LiteralValue, + TopP = (float?)modelOptions?.TopP?.LiteralValue, + TopK = (int?)modelOptions?.TopK?.LiteralValue, + FrequencyPenalty = (float?)modelOptions?.FrequencyPenalty?.LiteralValue, + PresencePenalty = (float?)modelOptions?.PresencePenalty?.LiteralValue, + Seed = modelOptions?.Seed?.LiteralValue, + ResponseFormat = outputSchema?.AsChatResponseFormat(), + ModelId = promptAgent.Model?.ModelNameHint, + StopSequences = modelOptions?.StopSequences, + AllowMultipleToolCalls = modelOptions?.AllowMultipleToolCalls?.LiteralValue, + ToolMode = modelOptions?.AsChatToolMode(), + Tools = tools, + AdditionalProperties = modelOptions?.GetAdditionalProperties(s_chatOptionProperties), + }; + } + + /// + /// Retrieves the 'tools' property from a . + /// + /// Instance of + /// Instance of + internal static List? GetAITools(this GptComponentMetadata promptAgent, IList? functions) + { + return promptAgent.Tools.Select(tool => + { + return tool switch + { + CodeInterpreterTool => ((CodeInterpreterTool)tool).AsCodeInterpreterTool(), + InvokeClientTaskAction => ((InvokeClientTaskAction)tool).CreateOrGetAITool(functions), + McpServerTool => ((McpServerTool)tool).CreateHostedMcpTool(), + FileSearchTool => ((FileSearchTool)tool).CreateFileSearchTool(), + WebSearchTool => ((WebSearchTool)tool).CreateWebSearchTool(), + _ => throw new NotSupportedException($"Unable to create tool definition because of unsupported tool type: {tool.Kind}, supported tool types are: {string.Join(",", s_validToolKinds)}"), + }; + }).ToList() ?? []; + } + + #region private + private const string CodeInterpreterKind = "codeInterpreter"; + private const string FileSearchKind = "fileSearch"; + private const string FunctionKind = "function"; + private const string WebSearchKind = "webSearch"; + private const string McpKind = "mcp"; + + private static readonly string[] s_validToolKinds = + [ + CodeInterpreterKind, + FileSearchKind, + FunctionKind, + WebSearchKind, + McpKind + ]; + + private static readonly string[] s_chatOptionProperties = + [ + "allowMultipleToolCalls", + "conversationId", + "chatToolMode", + "frequencyPenalty", + "additionalInstructions", + "maxOutputTokens", + "modelId", + "presencePenalty", + "responseFormat", + "seed", + "stopSequences", + "temperature", + "topK", + "topP", + "toolMode", + "tools", + ]; + + #endregion +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PropertyInfoExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PropertyInfoExtensions.cs new file mode 100644 index 0000000000..a62fddec88 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PropertyInfoExtensions.cs @@ -0,0 +1,96 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Text.Json; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +public static class PropertyInfoExtensions +{ + /// + /// Creates a of and + /// from an of and . + /// + /// A read-only dictionary of property names and their corresponding objects. + public static Dictionary AsObjectDictionary(this IReadOnlyDictionary properties) + { + var result = new Dictionary(); + + foreach (var property in properties) + { + result[property.Key] = BuildPropertySchema(property.Value); + } + + return result; + } + + #region private + private static Dictionary BuildPropertySchema(PropertyInfo propertyInfo) + { + var propertySchema = new Dictionary(); + + // Map the DataType to JSON schema type and add type-specific properties + switch (propertyInfo.Type) + { + case StringDataType: + propertySchema["type"] = "string"; + break; + case NumberDataType: + propertySchema["type"] = "number"; + break; + case BooleanDataType: + propertySchema["type"] = "boolean"; + break; + case DateTimeDataType: + propertySchema["type"] = "string"; + propertySchema["format"] = "date-time"; + break; + case DateDataType: + propertySchema["type"] = "string"; + propertySchema["format"] = "date"; + break; + case TimeDataType: + propertySchema["type"] = "string"; + propertySchema["format"] = "time"; + break; + case RecordDataType nestedRecordType: +#pragma warning disable IL2026, IL3050 + // For nested records, recursively build the schema + var nestedSchema = nestedRecordType.GetSchema(); + var nestedJson = JsonSerializer.Serialize(nestedSchema, ElementSerializer.CreateOptions()); + var nestedDict = JsonSerializer.Deserialize>(nestedJson, ElementSerializer.CreateOptions()); +#pragma warning restore IL2026, IL3050 + if (nestedDict != null) + { + return nestedDict; + } + propertySchema["type"] = "object"; + break; + case TableDataType tableType: + propertySchema["type"] = "array"; + // TableDataType has Properties like RecordDataType + propertySchema["items"] = new Dictionary + { + ["type"] = "object", + ["properties"] = AsObjectDictionary(tableType.Properties), + ["additionalProperties"] = false + }; + break; + default: + propertySchema["type"] = "string"; + break; + } + + // Add description if available + if (!string.IsNullOrEmpty(propertyInfo.Description)) + { + propertySchema["description"] = propertyInfo.Description; + } + + return propertySchema; + } + #endregion +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs new file mode 100644 index 0000000000..e4b696d9cd --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs @@ -0,0 +1,77 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Text.Json; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +public static class RecordDataTypeExtensions +{ + /// + /// Creates a from a . + /// + /// Instance of + internal static ChatResponseFormat? AsChatResponseFormat(this RecordDataType recordDataType) + { + Throw.IfNull(recordDataType); + + if (recordDataType.Properties.Count == 0) + { + return null; + } + + // TODO: Consider adding schemaName and schemaDescription parameters to this method. + return ChatResponseFormat.ForJsonSchema( + schema: recordDataType.GetSchema(), + schemaName: recordDataType.GetSchemaName(), + schemaDescription: recordDataType.GetSchemaDescription()); + } + + /// + /// Converts a to a . + /// + /// Instance of +#pragma warning disable IL2026 // Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise can break functionality when trimming application code +#pragma warning disable IL3050 // Calling members annotated with 'RequiresDynamicCodeAttribute' may break functionality when AOT compiling. + public static JsonElement GetSchema(this RecordDataType recordDataType) + { + Throw.IfNull(recordDataType); + + var schemaObject = new Dictionary + { + ["type"] = "object", + ["properties"] = recordDataType.Properties.AsObjectDictionary(), + ["additionalProperties"] = false + }; + + var json = JsonSerializer.Serialize(schemaObject, ElementSerializer.CreateOptions()); + return JsonSerializer.Deserialize(json); + } +#pragma warning restore IL3050 // Calling members annotated with 'RequiresDynamicCodeAttribute' may break functionality when AOT compiling. +#pragma warning restore IL2026 // Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise can break functionality when trimming application code + + /// + /// Retrieves the 'schemaName' property from a . + /// + internal static string? GetSchemaName(this RecordDataType recordDataType) + { + Throw.IfNull(recordDataType); + + return recordDataType.ExtensionData?.GetPropertyOrNull(InitializablePropertyPath.Create("schemaName"))?.Value; + } + + /// + /// Retrieves the 'schemaDescription' property from a . + /// + internal static string? GetSchemaDescription(this RecordDataType recordDataType) + { + Throw.IfNull(recordDataType); + + return recordDataType.ExtensionData?.GetPropertyOrNull(InitializablePropertyPath.Create("schemaDescription"))?.Value; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataValueExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataValueExtensions.cs new file mode 100644 index 0000000000..6351b7badb --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataValueExtensions.cs @@ -0,0 +1,107 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +public static class RecordDataValueExtensions +{ + /// + /// Retrieves a 'number' property from a + /// + /// Instance of + /// Path of the property to retrieve + public static decimal? GetNumber(this RecordDataValue recordData, string propertyPath) + { + Throw.IfNull(recordData); + + var numberValue = recordData.GetPropertyOrNull(InitializablePropertyPath.Create(propertyPath)); + return numberValue?.Value; + } + + /// + /// Retrieves a nullable boolean value from the specified property path within the given record data. + /// + /// Instance of + /// Path of the property to retrieve + public static bool? GetBoolean(this RecordDataValue recordData, string propertyPath) + { + Throw.IfNull(recordData); + + var booleanValue = recordData.GetPropertyOrNull(InitializablePropertyPath.Create(propertyPath)); + return booleanValue?.Value; + } + + /// + /// Converts a to a . + /// + /// Instance of + public static IReadOnlyDictionary ToDictionary(this RecordDataValue recordData) + { + Throw.IfNull(recordData); + + return recordData.Properties.ToDictionary( + kvp => kvp.Key, + kvp => kvp.Value?.ToString() ?? string.Empty + ); + } + + /// + /// Retrieves the 'schema' property from a . + /// + /// Instance of +#pragma warning disable IL2026 // Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise can break functionality when trimming application code +#pragma warning disable IL3050 // Calling members annotated with 'RequiresDynamicCodeAttribute' may break functionality when AOT compiling. + public static JsonElement? GetSchema(this RecordDataValue recordData) + { + Throw.IfNull(recordData); + + try + { + var schemaStr = recordData.GetPropertyOrNull(InitializablePropertyPath.Create("json_schema.schema")); + if (schemaStr?.Value is not null) + { + return JsonSerializer.Deserialize(schemaStr.Value); + } + } + catch (InvalidCastException) + { + // Ignore and try next + } + + var responseFormRec = recordData.GetPropertyOrNull(InitializablePropertyPath.Create("json_schema.schema")); + if (responseFormRec is not null) + { + var json = JsonSerializer.Serialize(responseFormRec, ElementSerializer.CreateOptions()); + return JsonSerializer.Deserialize(json); + } + + return null; + } +#pragma warning restore IL3050 // Calling members annotated with 'RequiresDynamicCodeAttribute' may break functionality when AOT compiling. +#pragma warning restore IL2026 // Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise can break functionality when trimming application code + + internal static object? ToObject(this DataValue? value) + { + if (value is null) + { + return null; + } + return value switch + { + StringDataValue s => s.Value, + NumberDataValue n => n.Value, + BooleanDataValue b => b.Value, + TableDataValue t => t.Values.Select(v => v.ToObject()).ToList(), + RecordDataValue r => r.Properties.ToDictionary(kvp => kvp.Key, kvp => kvp.Value?.ToObject()), + _ => throw new NotSupportedException($"Unsupported DataValue type: {value.GetType().FullName}"), + }; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs new file mode 100644 index 0000000000..6353bf3d42 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs @@ -0,0 +1,42 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.PowerFx; +using Microsoft.PowerFx.Types; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +public static class StringExpressionExtensions +{ + /// + /// Evaluates the given using the provided . + /// + /// Expression to evaluate. + /// Recalc engine to use for evaluation. + /// The evaluated string value, or null if the expression is null or cannot be evaluated. + public static string? Eval(this StringExpression? expression, RecalcEngine engine) + { + if (expression is null) + { + return null; + } + + if (expression.IsLiteral) + { + return expression.LiteralValue?.ToString(); + } + else if (expression.IsExpression) + { + return engine.Eval(expression.ExpressionText!).ToString(); + } + else if (expression.IsVariableReference) + { + var stringValue = engine.Eval(expression.VariableReference!.VariableName) as StringValue; + return stringValue?.Value; + } + + return null; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/WebSearchToolExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/WebSearchToolExtensions.cs new file mode 100644 index 0000000000..e6ee360308 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/WebSearchToolExtensions.cs @@ -0,0 +1,23 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class WebSearchToolExtensions +{ + /// + /// Create a from a . + /// + /// Instance of + internal static HostedWebSearchTool CreateWebSearchTool(this WebSearchTool tool) + { + Throw.IfNull(tool); + + return new HostedWebSearchTool(); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs new file mode 100644 index 0000000000..2bbda44a71 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs @@ -0,0 +1,33 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Diagnostics.CodeAnalysis; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI; + +/// +/// Extension methods for to support YAML based agent definitions. +/// +public static class YamlAgentFactoryExtensions +{ + /// + /// Create a from the given agent YAML. + /// + /// which will be used to create the agent. + /// Text string containing the YAML representation of an . + /// Optional cancellation token + [RequiresDynamicCode("Calls YamlDotNet.Serialization.DeserializerBuilder.DeserializerBuilder()")] + public static Task CreateFromYamlAsync(this AgentFactory agentFactory, string agentYaml, CancellationToken cancellationToken = default) + { + Throw.IfNull(agentFactory); + Throw.IfNullOrEmpty(agentYaml); + + var agentDefinition = AgentBotElementYaml.FromYaml(agentYaml); + + return agentFactory.CreateAsync( + agentDefinition, + cancellationToken); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj b/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj new file mode 100644 index 0000000000..ff3564f898 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj @@ -0,0 +1,44 @@ + + + + preview + $(NoWarn);MEAI001 + + + + true + true + true + + + + + + + Microsoft Agent Framework Declarative Agents + Provides Microsoft Agent Framework support for declarative agents. + + + + + + + + + + + + + + + + + + + + + + + + + From 185aca617c0e7371852c23567d33269865dc8aa0 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Wed, 26 Nov 2025 15:21:08 +0000 Subject: [PATCH 3/7] Make the package non packable --- .../Microsoft.Agents.AI.Declarative.csproj | 1 + 1 file changed, 1 insertion(+) diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj b/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj index ff3564f898..306ba27e97 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj @@ -3,6 +3,7 @@ preview $(NoWarn);MEAI001 + false From cb5b2bb7a88de61696dfc10a1767fce42f7e5de1 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Fri, 28 Nov 2025 17:20:16 +0000 Subject: [PATCH 4/7] Use the RecalcEngine when creating the ChatOptions --- dotnet/agent-framework-dotnet.slnx | 5 +- .../ChatClient/ChatClientAgentFactory.cs | 2 +- .../Extensions/BoolExpressionExtensions.cs | 56 +++ .../Extensions/IntExpressionExtensions.cs | 57 +++ .../Extensions/NumberExpressionExtensions.cs | 57 +++ .../Extensions/PromptAgentExtensions.cs | 20 +- .../Extensions/StringExpressionExtensions.cs | 10 +- .../Microsoft.Agents.AI.csproj | 1 + .../AgentBotElementYamlTests.cs | 310 ++++++++++++++ .../AggregatorAgentFactoryTests.cs | 89 ++++ .../ChatClient/ChatClientAgentFactoryTests.cs | 107 +++++ ...oft.Agents.AI.Declarative.UnitTests.csproj | 17 + .../PromptAgents.cs | 386 ++++++++++++++++++ 13 files changed, 1103 insertions(+), 14 deletions(-) create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/BoolExpressionExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/IntExpressionExtensions.cs create mode 100644 dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/NumberExpressionExtensions.cs create mode 100644 dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AgentBotElementYamlTests.cs create mode 100644 dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs create mode 100644 dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/ChatClient/ChatClientAgentFactoryTests.cs create mode 100644 dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj create mode 100644 dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/PromptAgents.cs diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx index b8c30c41a1..b32c9b0925 100644 --- a/dotnet/agent-framework-dotnet.slnx +++ b/dotnet/agent-framework-dotnet.slnx @@ -343,12 +343,12 @@ - + @@ -385,11 +385,12 @@ - + + diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs index 1a9a3b7a4b..ca126c6547 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs @@ -38,7 +38,7 @@ public ChatClientAgentFactory(IChatClient chatClient, IList? functio Name = promptAgent.Name, Description = promptAgent.Description, Instructions = promptAgent.Instructions?.ToTemplateString(), - ChatOptions = promptAgent.GetChatOptions(this._functions), + ChatOptions = promptAgent.GetChatOptions(this.Engine, this._functions), }; var agent = new ChatClientAgent(this._chatClient, options, this._loggerFactory); diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/BoolExpressionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/BoolExpressionExtensions.cs new file mode 100644 index 0000000000..9926e0e6be --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/BoolExpressionExtensions.cs @@ -0,0 +1,56 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.PowerFx; +using Microsoft.PowerFx.Types; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class BoolExpressionExtensions +{ + /// + /// Evaluates the given using the provided . + /// + /// Expression to evaluate. + /// Recalc engine to use for evaluation. + /// The evaluated boolean value, or null if the expression is null or cannot be evaluated. + internal static bool? Eval(this BoolExpression? expression, RecalcEngine? engine) + { + if (expression is null) + { + return null; + } + + if (expression.IsLiteral) + { + return expression.LiteralValue; + } + + if (engine is null) + { + return null; + } + + if (expression.IsExpression) + { + return engine.Eval(expression.ExpressionText!).AsBoolean(); + } + else if (expression.IsVariableReference) + { + var formulaValue = engine.Eval(expression.VariableReference!.VariableName); + if (formulaValue is BooleanValue booleanValue) + { + return booleanValue.Value; + } + + if (formulaValue is StringValue stringValue && bool.TryParse(stringValue.Value, out bool result)) + { + return result; + } + } + + return null; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/IntExpressionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/IntExpressionExtensions.cs new file mode 100644 index 0000000000..479d6ccea3 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/IntExpressionExtensions.cs @@ -0,0 +1,57 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Globalization; +using Microsoft.PowerFx; +using Microsoft.PowerFx.Types; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class IntExpressionExtensions +{ + /// + /// Evaluates the given using the provided . + /// + /// Expression to evaluate. + /// Recalc engine to use for evaluation. + /// The evaluated integer value, or null if the expression is null or cannot be evaluated. + internal static long? Eval(this IntExpression? expression, RecalcEngine? engine) + { + if (expression is null) + { + return null; + } + + if (expression.IsLiteral) + { + return expression.LiteralValue; + } + + if (engine is null) + { + return null; + } + + if (expression.IsExpression) + { + return (long)engine.Eval(expression.ExpressionText!).AsDouble(); + } + else if (expression.IsVariableReference) + { + var formulaValue = engine.Eval(expression.VariableReference!.VariableName); + if (formulaValue is NumberValue numberValue) + { + return (long)numberValue.Value; + } + + if (formulaValue is StringValue stringValue && int.TryParse(stringValue.Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int result)) + { + return result; + } + } + + return null; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/NumberExpressionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/NumberExpressionExtensions.cs new file mode 100644 index 0000000000..cfa36185cc --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/NumberExpressionExtensions.cs @@ -0,0 +1,57 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Globalization; +using Microsoft.PowerFx; +using Microsoft.PowerFx.Types; + +namespace Microsoft.Bot.ObjectModel; + +/// +/// Extension methods for . +/// +internal static class NumberExpressionExtensions +{ + /// + /// Evaluates the given using the provided . + /// + /// Expression to evaluate. + /// Recalc engine to use for evaluation. + /// The evaluated number value, or null if the expression is null or cannot be evaluated. + internal static double? Eval(this NumberExpression? expression, RecalcEngine? engine) + { + if (expression is null) + { + return null; + } + + if (expression.IsLiteral) + { + return expression.LiteralValue; + } + + if (engine is null) + { + return null; + } + + if (expression.IsExpression) + { + return engine.Eval(expression.ExpressionText!).AsDouble(); + } + else if (expression.IsVariableReference) + { + var formulaValue = engine.Eval(expression.VariableReference!.VariableName); + if (formulaValue is NumberValue numberValue) + { + return numberValue.Value; + } + + if (formulaValue is StringValue stringValue && double.TryParse(stringValue.Value, NumberStyles.Float, CultureInfo.InvariantCulture, out double result)) + { + return result; + } + } + + return null; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs index dacc83bc63..b85452119c 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs @@ -3,6 +3,7 @@ using System.Collections.Generic; using System.Linq; using Microsoft.Extensions.AI; +using Microsoft.PowerFx; using Microsoft.Shared.Diagnostics; namespace Microsoft.Bot.ObjectModel; @@ -16,8 +17,9 @@ public static class PromptAgentExtensions /// Retrieves the 'options' property from a as a instance. /// /// Instance of + /// Instance of /// Instance of - public static ChatOptions? GetChatOptions(this GptComponentMetadata promptAgent, IList? functions) + public static ChatOptions? GetChatOptions(this GptComponentMetadata promptAgent, RecalcEngine? engine, IList? functions) { Throw.IfNull(promptAgent); @@ -34,17 +36,17 @@ public static class PromptAgentExtensions return new ChatOptions() { Instructions = promptAgent.ResponseInstructions?.ToTemplateString(), - Temperature = (float?)modelOptions?.Temperature?.LiteralValue, - MaxOutputTokens = (int?)modelOptions?.MaxOutputTokens?.LiteralValue, - TopP = (float?)modelOptions?.TopP?.LiteralValue, - TopK = (int?)modelOptions?.TopK?.LiteralValue, - FrequencyPenalty = (float?)modelOptions?.FrequencyPenalty?.LiteralValue, - PresencePenalty = (float?)modelOptions?.PresencePenalty?.LiteralValue, - Seed = modelOptions?.Seed?.LiteralValue, + Temperature = (float?)modelOptions?.Temperature?.Eval(engine), + MaxOutputTokens = (int?)modelOptions?.MaxOutputTokens?.Eval(engine), + TopP = (float?)modelOptions?.TopP?.Eval(engine), + TopK = (int?)modelOptions?.TopK?.Eval(engine), + FrequencyPenalty = (float?)modelOptions?.FrequencyPenalty?.Eval(engine), + PresencePenalty = (float?)modelOptions?.PresencePenalty?.Eval(engine), + Seed = modelOptions?.Seed?.Eval(engine), ResponseFormat = outputSchema?.AsChatResponseFormat(), ModelId = promptAgent.Model?.ModelNameHint, StopSequences = modelOptions?.StopSequences, - AllowMultipleToolCalls = modelOptions?.AllowMultipleToolCalls?.LiteralValue, + AllowMultipleToolCalls = modelOptions?.AllowMultipleToolCalls?.Eval(engine), ToolMode = modelOptions?.AsChatToolMode(), Tools = tools, AdditionalProperties = modelOptions?.GetAdditionalProperties(s_chatOptionProperties), diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs index 6353bf3d42..40c1b7c9c8 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/StringExpressionExtensions.cs @@ -16,7 +16,7 @@ public static class StringExpressionExtensions /// Expression to evaluate. /// Recalc engine to use for evaluation. /// The evaluated string value, or null if the expression is null or cannot be evaluated. - public static string? Eval(this StringExpression? expression, RecalcEngine engine) + public static string? Eval(this StringExpression? expression, RecalcEngine? engine) { if (expression is null) { @@ -27,7 +27,13 @@ public static class StringExpressionExtensions { return expression.LiteralValue?.ToString(); } - else if (expression.IsExpression) + + if (engine is null) + { + return null; + } + + if (expression.IsExpression) { return engine.Eval(expression.ExpressionText!).ToString(); } diff --git a/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj b/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj index 5a9cb416c8..ad5b2e0fdd 100644 --- a/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj +++ b/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj @@ -32,6 +32,7 @@ + diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AgentBotElementYamlTests.cs b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AgentBotElementYamlTests.cs new file mode 100644 index 0000000000..31cadfb0ce --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AgentBotElementYamlTests.cs @@ -0,0 +1,310 @@ +// Copyright (c) Microsoft. All rights reserved. +using System.Collections.Generic; +using System.ComponentModel; +using System.IO; +using System.Linq; +using System.Text.Json.Serialization; +using Microsoft.Bot.ObjectModel; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Configuration; +using Microsoft.PowerFx; + +namespace Microsoft.Agents.AI.Declarative.UnitTests; + +/// +/// Unit tests for +/// +public sealed class AgentBotElementYamlTests +{ + [Theory] + [InlineData(PromptAgents.AgentWithEverything)] + [InlineData(PromptAgents.AgentWithApiKeyConnection)] + [InlineData(PromptAgents.AgentWithVariableReferences)] + [InlineData(PromptAgents.AgentWithOutputSchema)] + [InlineData(PromptAgents.OpenAIChatAgent)] + [InlineData(PromptAgents.AgentWithCurrentModels)] + [InlineData(PromptAgents.AgentWithRemoteConnection)] + public void FromYaml_DoesNotThrow(string text) + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(text); + + // Assert + Assert.NotNull(agent); + } + + [Fact] + public void FromYaml_NotPromptAgent_Throws() + { + // Arrange & Act & Assert + Assert.Throws(() => AgentBotElementYaml.FromYaml(PromptAgents.Workflow)); + } + + [Fact] + public void FromYaml_Properties() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + Assert.Equal("AgentName", agent.Name); + Assert.Equal("Agent description", agent.Description); + Assert.Equal("You are a helpful assistant.", agent.Instructions?.ToTemplateString()); + Assert.NotNull(agent.Model); + Assert.True(agent.Tools.Length > 0); + } + + [Fact] + public void FromYaml_CurrentModels() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithCurrentModels); + + // Assert + Assert.NotNull(agent); + Assert.NotNull(agent.Model); + Assert.Equal("gpt-4o", agent.Model.ModelNameHint); + Assert.NotNull(agent.Model.Options); + Assert.Equal(0.7f, (float?)agent.Model.Options?.Temperature?.LiteralValue); + Assert.Equal(0.9f, (float?)agent.Model.Options?.TopP?.LiteralValue); + + // Assert contents using extension methods + Assert.Equal(1024, agent.Model.Options?.MaxOutputTokens?.LiteralValue); + Assert.Equal(50, agent.Model.Options?.TopK?.LiteralValue); + Assert.Equal(0.7f, (float?)agent.Model.Options?.FrequencyPenalty?.LiteralValue); + Assert.Equal(0.7f, (float?)agent.Model.Options?.PresencePenalty?.LiteralValue); + Assert.Equal(42, agent.Model.Options?.Seed?.LiteralValue); + Assert.Equal(PromptAgents.s_stopSequences, agent.Model.Options?.StopSequences); + Assert.True(agent.Model.Options?.AllowMultipleToolCalls?.LiteralValue); + Assert.Equal(ChatToolMode.Auto, agent.Model.Options?.AsChatToolMode()); + } + + [Fact] + public void FromYaml_OutputSchema() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithOutputSchema); + + // Assert + Assert.NotNull(agent); + Assert.NotNull(agent.OutputType); + ChatResponseFormatJson responseFormat = (agent.OutputType.AsChatResponseFormat() as ChatResponseFormatJson)!; + Assert.NotNull(responseFormat); + Assert.NotNull(responseFormat.Schema); + } + + [Fact] + public void FromYaml_CodeInterpreter() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + var tools = agent.Tools; + var codeInterpreterTools = tools.Where(t => t is CodeInterpreterTool).ToArray(); + Assert.Single(codeInterpreterTools); + CodeInterpreterTool codeInterpreterTool = (codeInterpreterTools[0] as CodeInterpreterTool)!; + Assert.NotNull(codeInterpreterTool); + } + + [Fact] + public void FromYaml_FunctionTool() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + var tools = agent.Tools; + var functionTools = tools.Where(t => t is InvokeClientTaskAction).ToArray(); + Assert.Single(functionTools); + InvokeClientTaskAction functionTool = (functionTools[0] as InvokeClientTaskAction)!; + Assert.NotNull(functionTool); + Assert.Equal("GetWeather", functionTool.Name); + Assert.Equal("Get the weather for a given location.", functionTool.Description); + // TODO check schema + } + + [Fact] + public void FromYaml_MCP() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + var tools = agent.Tools; + var mcpTools = tools.Where(t => t is McpServerTool).ToArray(); + Assert.Single(mcpTools); + McpServerTool mcpTool = (mcpTools[0] as McpServerTool)!; + Assert.NotNull(mcpTool); + Assert.Equal("PersonInfoTool", mcpTool.ServerName?.LiteralValue); + AnonymousConnection connection = (mcpTool.Connection as AnonymousConnection)!; + Assert.NotNull(connection); + Assert.Equal("https://my-mcp-endpoint.com/api", connection.Endpoint?.LiteralValue); + } + + [Fact] + public void FromYaml_WebSearchTool() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + var tools = agent.Tools; + var webSearchTools = tools.Where(t => t is WebSearchTool).ToArray(); + Assert.Single(webSearchTools); + Assert.NotNull(webSearchTools[0] as WebSearchTool); + } + + [Fact] + public void FromYaml_FileSearchTool() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithEverything); + + // Assert + Assert.NotNull(agent); + var tools = agent.Tools; + var fileSearchTools = tools.Where(t => t is FileSearchTool).ToArray(); + Assert.Single(fileSearchTools); + FileSearchTool fileSearchTool = (fileSearchTools[0] as FileSearchTool)!; + Assert.NotNull(fileSearchTool); + + // Verify vector store content property exists and has correct values + Assert.NotNull(fileSearchTool.VectorStoreIds); + Assert.Equal(3, fileSearchTool.VectorStoreIds.LiteralValue.Length); + Assert.Equal("1", fileSearchTool.VectorStoreIds.LiteralValue[0]); + Assert.Equal("2", fileSearchTool.VectorStoreIds.LiteralValue[1]); + Assert.Equal("3", fileSearchTool.VectorStoreIds.LiteralValue[2]); + } + + [Fact] + public void FromYaml_ApiKeyConnection() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithApiKeyConnection); + + // Assert + Assert.NotNull(agent); + Assert.NotNull(agent.Model); + CurrentModels model = (agent.Model as CurrentModels)!; + Assert.NotNull(model); + Assert.NotNull(model.Connection); + Assert.IsType(model.Connection); + ApiKeyConnection connection = (model.Connection as ApiKeyConnection)!; + Assert.NotNull(connection); + Assert.Equal("https://my-azure-openai-endpoint.openai.azure.com/", connection.Endpoint?.LiteralValue); + Assert.Equal("my-api-key", connection.Key?.LiteralValue); + } + + [Fact] + public void FromYaml_RemoteConnection() + { + // Arrange & Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithRemoteConnection); + + // Assert + Assert.NotNull(agent); + Assert.NotNull(agent.Model); + CurrentModels model = (agent.Model as CurrentModels)!; + Assert.NotNull(model); + Assert.NotNull(model.Connection); + Assert.IsType(model.Connection); + RemoteConnection connection = (model.Connection as RemoteConnection)!; + Assert.NotNull(connection); + Assert.Equal("https://my-azure-openai-endpoint.openai.azure.com/", connection.Endpoint?.LiteralValue); + } + + [Fact] + public void FromYaml_WithVariableReferences() + { + // Arrange + IConfiguration configuration = new ConfigurationBuilder() + .AddInMemoryCollection(new Dictionary + { + ["OpenAIEndpoint"] = "endpoint", + ["OpenAIApiKey"] = "apiKey", + ["Temperature"] = "0.9", + ["TopP"] = "0.8" + }) + .Build(); + + // Act + var agent = AgentBotElementYaml.FromYaml(PromptAgents.AgentWithVariableReferences, configuration); + + // Assert + Assert.NotNull(agent); + Assert.NotNull(agent.Model); + CurrentModels model = (agent.Model as CurrentModels)!; + Assert.NotNull(model); + Assert.NotNull(model.Options); + Assert.Equal(0.9, Eval(model.Options?.Temperature, configuration)); + Assert.Equal(0.8, Eval(model.Options?.TopP, configuration)); + Assert.NotNull(model.Connection); + Assert.IsType(model.Connection); + ApiKeyConnection connection = (model.Connection as ApiKeyConnection)!; + Assert.NotNull(connection); + Assert.NotNull(connection.Endpoint); + Assert.NotNull(connection.Key); + Assert.Equal("endpoint", Eval(connection.Endpoint, configuration)); + Assert.Equal("apiKey", Eval(connection.Key, configuration)); + } + + /// + /// Represents information about a person, including their name, age, and occupation, matched to the JSON schema used in the agent. + /// + [Description("Information about a person including their name, age, and occupation")] + public sealed class PersonInfo + { + [JsonPropertyName("name")] + public string? Name { get; set; } + + [JsonPropertyName("age")] + public int? Age { get; set; } + + [JsonPropertyName("occupation")] + public string? Occupation { get; set; } + } + + private static string? Eval(StringExpression? expression, IConfiguration? configuration = null) + { + if (expression is null) + { + return null; + } + + RecalcEngine engine = new(); + if (configuration is not null) + { + foreach (var kvp in configuration.AsEnumerable()) + { + engine.UpdateVariable(kvp.Key, kvp.Value ?? string.Empty); + } + } + + return expression.Eval(engine); + } + + private static double? Eval(NumberExpression? expression, IConfiguration? configuration = null) + { + if (expression is null) + { + return null; + } + + RecalcEngine engine = new(); + if (configuration != null) + { + foreach (var kvp in configuration.AsEnumerable()) + { + engine.UpdateVariable(kvp.Key, kvp.Value ?? string.Empty); + } + } + + return expression.Eval(engine); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs new file mode 100644 index 0000000000..a09f134983 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs @@ -0,0 +1,89 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Bot.ObjectModel; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.Declarative.UnitTests; + +/// +/// Unit tests for +/// +public sealed class AggregatorAgentFactoryTests +{ + [Fact] + public void AggregatorAgentFactory_ThrowsForEmptyArray() + { + // Arrange & Act & Assert + Assert.Throws(() => new AggregatorAgentFactory([])); + } + + [Fact] + public async Task AggregatorAgentFactory_ReturnsNull() + { + // Arrange + var factory = new AggregatorAgentFactory([new TestAgentFactory(null)]); + + // Act + var agent = await factory.TryCreateAsync(new GptComponentMetadata("test")); + + // Assert + Assert.Null(agent); + } + + [Fact] + public async Task AggregatorAgentFactory_ReturnsAgent() + { + // Arrange + var agentToReturn = new TestAgent(); + var factory = new AggregatorAgentFactory([new TestAgentFactory(null), new TestAgentFactory(agentToReturn)]); + + // Act + var agent = await factory.TryCreateAsync(new GptComponentMetadata("test")); + + // Assert + Assert.Equal(agentToReturn, agent); + } + + private sealed class TestAgentFactory : AgentFactory + { + private readonly AIAgent? _agentToReturn; + + public TestAgentFactory(AIAgent? agentToReturn = null) + { + this._agentToReturn = agentToReturn; + } + + public override Task TryCreateAsync(GptComponentMetadata promptAgent, CancellationToken cancellationToken = default) + { + return Task.FromResult(this._agentToReturn); + } + } + + private sealed class TestAgent : AIAgent + { + public override AgentThread DeserializeThread(JsonElement serializedThread, JsonSerializerOptions? jsonSerializerOptions = null) + { + throw new NotImplementedException(); + } + + public override AgentThread GetNewThread() + { + throw new NotImplementedException(); + } + + public override Task RunAsync(IEnumerable messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotImplementedException(); + } + + public override IAsyncEnumerable RunStreamingAsync(IEnumerable messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) + { + throw new NotImplementedException(); + } + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/ChatClient/ChatClientAgentFactoryTests.cs b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/ChatClient/ChatClientAgentFactoryTests.cs new file mode 100644 index 0000000000..b9078ee0b0 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/ChatClient/ChatClientAgentFactoryTests.cs @@ -0,0 +1,107 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Moq; + +namespace Microsoft.Agents.AI.Declarative.UnitTests.ChatClient; + +/// +/// Unit tests for . +/// +public sealed class ChatClientAgentFactoryTests +{ + private readonly Mock _mockChatClient; + + public ChatClientAgentFactoryTests() + { + this._mockChatClient = new(); + } + + [Fact] + public async Task TryCreateAsync_WithChatClientInConstructor_CreatesAgentAsync() + { + // Arrange + var promptAgent = PromptAgents.CreateTestPromptAgent(); + ChatClientAgentFactory factory = new(this._mockChatClient.Object); + + // Act + AIAgent? agent = await factory.TryCreateAsync(promptAgent); + + // Assert + Assert.NotNull(agent); + Assert.IsType(agent); + Assert.Equal("Test Agent", agent.Name); + Assert.Equal("Test Description", agent.Description); + } + + [Fact] + public async Task TryCreateAsync_Creates_ChatClientAgentAsync() + { + // Arrange + var promptAgent = PromptAgents.CreateTestPromptAgent(); + ChatClientAgentFactory factory = new(this._mockChatClient.Object); + + // Act + AIAgent? agent = await factory.TryCreateAsync(promptAgent); + + // Assert + Assert.NotNull(agent); + Assert.IsType(agent); + var chatClientAgent = agent as ChatClientAgent; + Assert.NotNull(chatClientAgent); + Assert.Equal("You are a helpful assistant.", chatClientAgent.Instructions); + Assert.NotNull(chatClientAgent.ChatClient); + Assert.NotNull(chatClientAgent.ChatOptions); + } + + [Fact] + public async Task TryCreateAsync_Creates_ChatOptionsAsync() + { + // Arrange + var promptAgent = PromptAgents.CreateTestPromptAgent(); + ChatClientAgentFactory factory = new(this._mockChatClient.Object); + + // Act + AIAgent? agent = await factory.TryCreateAsync(promptAgent); + + // Assert + Assert.NotNull(agent); + Assert.IsType(agent); + var chatClientAgent = agent as ChatClientAgent; + Assert.NotNull(chatClientAgent?.ChatOptions); + Assert.Equal("Provide detailed and accurate responses.", chatClientAgent?.ChatOptions?.Instructions); + Assert.Equal(0.7F, chatClientAgent?.ChatOptions?.Temperature); + Assert.Equal(0.7F, chatClientAgent?.ChatOptions?.FrequencyPenalty); + Assert.Equal(1024, chatClientAgent?.ChatOptions?.MaxOutputTokens); + Assert.Equal(0.9F, chatClientAgent?.ChatOptions?.TopP); + Assert.Equal(50, chatClientAgent?.ChatOptions?.TopK); + Assert.Equal(0.7F, chatClientAgent?.ChatOptions?.PresencePenalty); + Assert.Equal(42L, chatClientAgent?.ChatOptions?.Seed); + Assert.NotNull(chatClientAgent?.ChatOptions?.ResponseFormat); + Assert.Equal("gpt-4o", chatClientAgent?.ChatOptions?.ModelId); + Assert.Equal(["###", "END", "STOP"], chatClientAgent?.ChatOptions?.StopSequences); + Assert.True(chatClientAgent?.ChatOptions?.AllowMultipleToolCalls); + Assert.Equal(ChatToolMode.Auto, chatClientAgent?.ChatOptions?.ToolMode); + Assert.Equal("customValue", chatClientAgent?.ChatOptions?.AdditionalProperties?["customProperty"]); + } + + [Fact] + public async Task TryCreateAsync_Creates_ToolsAsync() + { + // Arrange + var promptAgent = PromptAgents.CreateTestPromptAgent(); + ChatClientAgentFactory factory = new(this._mockChatClient.Object); + + // Act + AIAgent? agent = await factory.TryCreateAsync(promptAgent); + + // Assert + Assert.NotNull(agent); + Assert.IsType(agent); + var chatClientAgent = agent as ChatClientAgent; + Assert.NotNull(chatClientAgent?.ChatOptions?.Tools); + var tools = chatClientAgent?.ChatOptions?.Tools; + Assert.Equal(5, tools?.Count); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj new file mode 100644 index 0000000000..f583809d09 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj @@ -0,0 +1,17 @@ + + + + $(NoWarn);IDE1006 + + + + + + + + + + + + + diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/PromptAgents.cs b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/PromptAgents.cs new file mode 100644 index 0000000000..163e4ded18 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/PromptAgents.cs @@ -0,0 +1,386 @@ +// Copyright (c) Microsoft. All rights reserved. + +using Microsoft.Bot.ObjectModel; + +namespace Microsoft.Agents.AI.Declarative.UnitTests; + +internal static class PromptAgents +{ + internal const string AgentWithEverything = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + options: + temperature: 0.7 + maxOutputTokens: 1024 + topP: 0.9 + topK: 50 + frequencyPenalty: 0.0 + presencePenalty: 0.0 + seed: 42 + responseFormat: text + stopSequences: + - "###" + - "END" + - "STOP" + allowMultipleToolCalls: true + tools: + - kind: codeInterpreter + inputs: + - kind: HostedFileContent + FileId: fileId123 + - kind: function + name: GetWeather + description: Get the weather for a given location. + parameters: + - name: location + type: string + description: The city and state, e.g. San Francisco, CA + required: true + - name: unit + type: string + description: The unit of temperature. Possible values are 'celsius' and 'fahrenheit'. + required: false + enum: + - celsius + - fahrenheit + - kind: mcp + serverName: PersonInfoTool + serverDescription: Get information about a person. + connection: + kind: AnonymousConnection + endpoint: https://my-mcp-endpoint.com/api + allowedTools: + - "GetPersonInfo" + - "UpdatePersonInfo" + - "DeletePersonInfo" + approvalMode: + kind: HostedMcpServerToolRequireSpecificApprovalMode + AlwaysRequireApprovalToolNames: + - "UpdatePersonInfo" + - "DeletePersonInfo" + NeverRequireApprovalToolNames: + - "GetPersonInfo" + - kind: webSearch + name: WebSearchTool + description: Search the web for information. + - kind: fileSearch + name: FileSearchTool + description: Search files for information. + ranker: default + scoreThreshold: 0.5 + maxResults: 5 + maxContentLength: 2000 + vectorStoreIds: + - 1 + - 2 + - 3 + """; + + internal const string AgentWithOutputSchema = + """ + kind: Prompt + name: Translation Assistant + description: A helpful assistant that translates text to a specified language. + model: + id: gpt-4o + options: + temperature: 0.9 + topP: 0.95 + instructions: You are a helpful assistant. You answer questions in {language}. You return your answers in a JSON format. + additionalInstructions: You must always respond in the specified language. + tools: + - kind: codeInterpreter + template: + format: PowerFx # Mustache is the other option + parser: None # Prompty and XML are the other options + inputSchema: + properties: + language: string + outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + """; + + internal const string AgentWithApiKeyConnection = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + connection: + kind: ApiKey + endpoint: https://my-azure-openai-endpoint.openai.azure.com/ + key: my-api-key + """; + + internal const string AgentWithRemoteConnection = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + connection: + kind: Remote + endpoint: https://my-azure-openai-endpoint.openai.azure.com/ + """; + + internal const string AgentWithVariableReferences = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + options: + temperature: =Env.Temperature + topP: =Env.TopP + connection: + kind: apiKey + endpoint: =Env.OpenAIEndpoint + key: =Env.OpenAIApiKey + """; + + internal const string OpenAIChatAgent = + """ + kind: Prompt + name: Assistant + description: Helpful assistant + instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. + model: + id: =Env.OPENAI_MODEL + options: + temperature: 0.9 + topP: 0.95 + connection: + kind: apiKey + key: =Env.OPENAI_APIKEY + outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + """; + + internal const string AgentWithCurrentModels = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + options: + temperature: 0.7 + maxOutputTokens: 1024 + topP: 0.9 + topK: 50 + frequencyPenalty: 0.7 + presencePenalty: 0.7 + seed: 42 + responseFormat: text + stopSequences: + - "###" + - "END" + - "STOP" + allowMultipleToolCalls: true + chatToolMode: auto + """; + + internal const string AgentWithCurrentModelsSnakeCase = + """ + kind: Prompt + name: AgentName + description: Agent description + instructions: You are a helpful assistant. + model: + id: gpt-4o + options: + temperature: 0.7 + max_output_tokens: 1024 + top_p: 0.9 + top_k: 50 + frequency_penalty: 0.7 + presence_penalty: 0.7 + seed: 42 + response_format: text + stop_sequences: + - "###" + - "END" + - "STOP" + allow_multiple_tool_calls: true + chat_tool_mode: auto + """; + + internal const string Workflow = + """ + kind: Workflow + trigger: + + kind: OnConversationStart + id: workflow_demo + actions: + + - kind: InvokeAzureAgent + id: question_student + conversationId: =System.ConversationId + agent: + name: StudentAgent + + - kind: InvokeAzureAgent + id: question_teacher + conversationId: =System.ConversationId + agent: + name: TeacherAgent + output: + messages: Local.TeacherResponse + + - kind: SetVariable + id: set_count_increment + variable: Local.TurnCount + value: =Local.TurnCount + 1 + + - kind: ConditionGroup + id: check_completion + conditions: + + - condition: =!IsBlank(Find("CONGRATULATIONS", Upper(MessageText(Local.TeacherResponse)))) + id: check_turn_done + actions: + + - kind: SendActivity + id: sendActivity_done + activity: GOLD STAR! + + - condition: =Local.TurnCount < 4 + id: check_turn_count + actions: + + - kind: GotoAction + id: goto_student_agent + actionId: question_student + + elseActions: + + - kind: SendActivity + id: sendActivity_tired + activity: Let's try again later... + + """; + + internal static readonly string[] s_stopSequences = ["###", "END", "STOP"]; + + internal static GptComponentMetadata CreateTestPromptAgent(string? publisher = "OpenAI", string? apiType = "Chat") + { + string agentYaml = + $""" + kind: Prompt + name: Test Agent + description: Test Description + instructions: You are a helpful assistant. + additionalInstructions: Provide detailed and accurate responses. + model: + id: gpt-4o + publisher: {publisher} + apiType: {apiType} + options: + modelId: gpt-4o + temperature: 0.7 + maxOutputTokens: 1024 + topP: 0.9 + topK: 50 + frequencyPenalty: 0.7 + presencePenalty: 0.7 + seed: 42 + responseFormat: text + stopSequences: + - "###" + - "END" + - "STOP" + allowMultipleToolCalls: true + chatToolMode: auto + customProperty: customValue + connection: + kind: apiKey + endpoint: https://my-azure-openai-endpoint.openai.azure.com/ + key: my-api-key + tools: + - kind: codeInterpreter + - kind: function + name: GetWeather + description: Get the weather for a given location. + parameters: + - name: location + type: string + description: The city and state, e.g. San Francisco, CA + required: true + - name: unit + type: string + description: The unit of temperature. Possible values are 'celsius' and 'fahrenheit'. + required: false + enum: + - celsius + - fahrenheit + - kind: mcp + serverName: PersonInfoTool + serverDescription: Get information about a person. + allowedTools: + - "GetPersonInfo" + - "UpdatePersonInfo" + - "DeletePersonInfo" + approvalMode: + kind: HostedMcpServerToolRequireSpecificApprovalMode + AlwaysRequireApprovalToolNames: + - "UpdatePersonInfo" + - "DeletePersonInfo" + NeverRequireApprovalToolNames: + - "GetPersonInfo" + connection: + kind: AnonymousConnection + endpoint: https://my-mcp-endpoint.com/api + - kind: webSearch + name: WebSearchTool + description: Search the web for information. + - kind: fileSearch + name: FileSearchTool + description: Search files for information. + vectorStoreIds: + - 1 + - 2 + - 3 + outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + """; + + return AgentBotElementYaml.FromYaml(agentYaml); + } +} From 6579bfebff411a0d5a2e94c82f5f0db4da5c7af8 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Fri, 28 Nov 2025 17:29:41 +0000 Subject: [PATCH 5/7] Ignore VSTHRD200 --- .../Microsoft.Agents.AI.Declarative.UnitTests.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj index f583809d09..d348a0b433 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj @@ -1,7 +1,7 @@  - $(NoWarn);IDE1006 + $(NoWarn);IDE1006;VSTHRD200 From 242586dccef1cb1ec03e5b20dadfc506aa2b9073 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Fri, 28 Nov 2025 18:02:48 +0000 Subject: [PATCH 6/7] Add geting started samples --- dotnet/agent-framework-dotnet.slnx | 4 ++ .../Agent_Step19_Declarative.csproj | 25 +++++++++ .../Agent_Step19_Declarative/Program.cs | 54 ++++++++++++++++++ .../samples/GettingStarted/Agents/README.md | 1 + .../DeclarativeChatClientAgents.csproj | 25 +++++++++ .../DeclarativeAgents/ChatClient/Program.cs | 55 +++++++++++++++++++ .../ChatClient/Properties/launchSettings.json | 12 ++++ 7 files changed, 176 insertions(+) create mode 100644 dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj create mode 100644 dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Program.cs create mode 100644 dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj create mode 100644 dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Program.cs create mode 100644 dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Properties/launchSettings.json diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx index b32c9b0925..70ea1603c0 100644 --- a/dotnet/agent-framework-dotnet.slnx +++ b/dotnet/agent-framework-dotnet.slnx @@ -78,6 +78,10 @@ + + + + diff --git a/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj b/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj new file mode 100644 index 0000000000..550e1f22cb --- /dev/null +++ b/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj @@ -0,0 +1,25 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + + + + + + diff --git a/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Program.cs b/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Program.cs new file mode 100644 index 0000000000..6275b63b62 --- /dev/null +++ b/dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Program.cs @@ -0,0 +1,54 @@ +// Copyright (c) Microsoft. All rights reserved. + +// This sample shows how to create an agent from a YAML based declarative representation. + +using Azure.AI.OpenAI; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +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"; + +// Create the chat client +IChatClient chatClient = new AzureOpenAIClient( + new Uri(endpoint), + new AzureCliCredential()) + .GetChatClient(deploymentName) + .AsIChatClient(); + +// Define the agent using a YAML definition. +var text = + """ + kind: Prompt + name: Assistant + description: Helpful assistant + instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. + model: + options: + temperature: 0.9 + topP: 0.95 + outputSchema: + properties: + language: + type: string + required: true + description: The language of the answer. + answer: + type: string + required: true + description: The answer text. + """; + +// Create the agent from the YAML definition. +var agentFactory = new ChatClientAgentFactory(chatClient); +var agent = await agentFactory.CreateFromYamlAsync(text); + +// Invoke the agent and output the text result. +Console.WriteLine(await agent!.RunAsync("Tell me a joke about a pirate in English.")); + +// Invoke the agent with streaming support. +await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pirate in French.")) +{ + Console.WriteLine(update); +} diff --git a/dotnet/samples/GettingStarted/Agents/README.md b/dotnet/samples/GettingStarted/Agents/README.md index cbe4b65047..d023d6455c 100644 --- a/dotnet/samples/GettingStarted/Agents/README.md +++ b/dotnet/samples/GettingStarted/Agents/README.md @@ -45,6 +45,7 @@ Before you begin, ensure you have the following prerequisites: |[Reducing chat history size](./Agent_Step16_ChatReduction/)|This sample demonstrates how to reduce the chat history to constrain its size, where chat history is maintained locally| |[Background responses](./Agent_Step17_BackgroundResponses/)|This sample demonstrates how to use background responses for long-running operations with polling and resumption support| |[Deep research with an agent](./Agent_Step18_DeepResearch/)|This sample demonstrates how to use the Deep Research Tool to perform comprehensive research on complex topics| +|[Declarative agent](./Agent_Step19_Declarative/)|This sample demonstrates how to declaratively define an agent.| ## Running the samples from the console diff --git a/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj new file mode 100644 index 0000000000..0fc316acac --- /dev/null +++ b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj @@ -0,0 +1,25 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + + + + + + diff --git a/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Program.cs b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Program.cs new file mode 100644 index 0000000000..c3f998a836 --- /dev/null +++ b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Program.cs @@ -0,0 +1,55 @@ +// Copyright (c) Microsoft. All rights reserved. + +// This sample shows how to load an AI agent from a YAML file and process a prompt using Azure OpenAI as the backend. + +using System.ComponentModel; +using Azure.AI.OpenAI; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +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"; + +// Create the chat client +IChatClient chatClient = new AzureOpenAIClient( + new Uri(endpoint), + new AzureCliCredential()) + .GetChatClient(deploymentName) + .AsIChatClient(); + +// Read command-line arguments +if (args.Length < 2) +{ + Console.WriteLine("Usage: DeclarativeAgents "); + Console.WriteLine(" : The path to the YAML file containing the agent definition"); + Console.WriteLine(" : The prompt to send to the agent"); + return; +} + +var yamlFilePath = args[0]; +var prompt = args[1]; + +// Verify the YAML file exists +if (!File.Exists(yamlFilePath)) +{ + Console.WriteLine($"Error: File not found: {yamlFilePath}"); + return; +} + +// Read the YAML content from the file +var text = await File.ReadAllTextAsync(yamlFilePath); + +// Example function tool that can be used by the agent. +[Description("Get the weather for a given location.")] +static string GetWeather( + [Description("The city and state, e.g. San Francisco, CA")] string location, + [Description("The unit of temperature. Possible values are 'celsius' and 'fahrenheit'.")] string unit) + => $"The weather in {location} is cloudy with a high of {(unit.Equals("celsius", StringComparison.Ordinal) ? "15°C" : "59°F")}."; + +// Create the agent from the YAML definition. +var agentFactory = new ChatClientAgentFactory(chatClient, [AIFunctionFactory.Create(GetWeather, "GetWeather")]); +var agent = await agentFactory.CreateFromYamlAsync(text); + +// Invoke the agent and output the text result. +Console.WriteLine(await agent!.RunAsync(prompt)); diff --git a/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Properties/launchSettings.json b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Properties/launchSettings.json new file mode 100644 index 0000000000..5ec486626c --- /dev/null +++ b/dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Properties/launchSettings.json @@ -0,0 +1,12 @@ +{ + "profiles": { + "GetWeather": { + "commandName": "Project", + "commandLineArgs": "..\\..\\..\\..\\..\\..\\..\\..\\agent-samples\\chatclient\\GetWeather.yaml \"What is the weather in Cambridge, MA in °C?\"" + }, + "Assistant": { + "commandName": "Project", + "commandLineArgs": "..\\..\\..\\..\\..\\..\\..\\..\\agent-samples\\chatclient\\Assistant.yaml \"Tell me a joke about a pirate in Italian.\"" + } + } +} \ No newline at end of file From 5b7848eb623cb02b4db0a0b9c486e3a4a038a302 Mon Sep 17 00:00:00 2001 From: markwallace-microsoft <127216156+markwallace-microsoft@users.noreply.github.com> Date: Mon, 1 Dec 2025 12:19:20 +0000 Subject: [PATCH 7/7] Address code review feedback --- ...tFactory.cs => AggregatorPromptAgentFactory.cs} | 14 +++++++------- .../ChatClient/ChatClientAgentFactory.cs | 7 ++++--- .../Extensions/RecordDataTypeExtensions.cs | 4 ++-- .../Extensions/YamlAgentFactoryExtensions.cs | 6 +++--- .../{AgentFactory.cs => PromptAgentFactory.cs} | 11 ++++++----- ...sts.cs => AggregatorPromptAgentFactoryTests.cs} | 12 ++++++------ 6 files changed, 28 insertions(+), 26 deletions(-) rename dotnet/src/Microsoft.Agents.AI.Declarative/{AggregatorAgentFactory.cs => AggregatorPromptAgentFactory.cs} (61%) rename dotnet/src/Microsoft.Agents.AI.Declarative/{AgentFactory.cs => PromptAgentFactory.cs} (80%) rename dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/{AggregatorAgentFactoryTests.cs => AggregatorPromptAgentFactoryTests.cs} (83%) diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorPromptAgentFactory.cs similarity index 61% rename from dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs rename to dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorPromptAgentFactory.cs index e9ddcdd6d8..49027367f1 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorAgentFactory.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/AggregatorPromptAgentFactory.cs @@ -8,22 +8,22 @@ namespace Microsoft.Agents.AI; /// -/// Provides a which aggregates multiple agent factories. +/// Provides a which aggregates multiple agent factories. /// -public sealed class AggregatorAgentFactory : AgentFactory +public sealed class AggregatorPromptAgentFactory : PromptAgentFactory { - private readonly AgentFactory[] _agentFactories; + private readonly PromptAgentFactory[] _agentFactories; /// Initializes the instance. - /// Ordered instances to aggregate. + /// Ordered instances to aggregate. /// - /// Where multiple instances are provided, the first factory that supports the will be used. + /// Where multiple instances are provided, the first factory that supports the will be used. /// - public AggregatorAgentFactory(params AgentFactory[] agentFactories) + public AggregatorPromptAgentFactory(params PromptAgentFactory[] agentFactories) { Throw.IfNullOrEmpty(agentFactories); - foreach (AgentFactory agentFactory in agentFactories) + foreach (PromptAgentFactory agentFactory in agentFactories) { Throw.IfNull(agentFactory, nameof(agentFactories)); } diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs index ca126c6547..2c94facbd0 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientAgentFactory.cs @@ -7,19 +7,20 @@ using Microsoft.Extensions.AI; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Logging; +using Microsoft.PowerFx; using Microsoft.Shared.Diagnostics; namespace Microsoft.Agents.AI; /// -/// Provides an which creates instances of . +/// Provides an which creates instances of . /// -public sealed class ChatClientAgentFactory : AgentFactory +public sealed class ChatClientAgentFactory : PromptAgentFactory { /// /// Creates a new instance of the class. /// - public ChatClientAgentFactory(IChatClient chatClient, IList? functions = null, IConfiguration? configuration = null, ILoggerFactory? loggerFactory = null) : base(configuration) + public ChatClientAgentFactory(IChatClient chatClient, IList? functions = null, RecalcEngine? engine = null, IConfiguration? configuration = null, ILoggerFactory? loggerFactory = null) : base(engine, configuration) { Throw.IfNull(chatClient); diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs index e4b696d9cd..b5c5793cab 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/RecordDataTypeExtensions.cs @@ -58,7 +58,7 @@ public static JsonElement GetSchema(this RecordDataType recordDataType) /// /// Retrieves the 'schemaName' property from a . /// - internal static string? GetSchemaName(this RecordDataType recordDataType) + private static string? GetSchemaName(this RecordDataType recordDataType) { Throw.IfNull(recordDataType); @@ -68,7 +68,7 @@ public static JsonElement GetSchema(this RecordDataType recordDataType) /// /// Retrieves the 'schemaDescription' property from a . /// - internal static string? GetSchemaDescription(this RecordDataType recordDataType) + private static string? GetSchemaDescription(this RecordDataType recordDataType) { Throw.IfNull(recordDataType); diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs index 2bbda44a71..1cc24055d9 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/YamlAgentFactoryExtensions.cs @@ -8,18 +8,18 @@ namespace Microsoft.Agents.AI; /// -/// Extension methods for to support YAML based agent definitions. +/// Extension methods for to support YAML based agent definitions. /// public static class YamlAgentFactoryExtensions { /// /// Create a from the given agent YAML. /// - /// which will be used to create the agent. + /// which will be used to create the agent. /// Text string containing the YAML representation of an . /// Optional cancellation token [RequiresDynamicCode("Calls YamlDotNet.Serialization.DeserializerBuilder.DeserializerBuilder()")] - public static Task CreateFromYamlAsync(this AgentFactory agentFactory, string agentYaml, CancellationToken cancellationToken = default) + public static Task CreateFromYamlAsync(this PromptAgentFactory agentFactory, string agentYaml, CancellationToken cancellationToken = default) { Throw.IfNull(agentFactory); Throw.IfNullOrEmpty(agentYaml); diff --git a/dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs b/dotnet/src/Microsoft.Agents.AI.Declarative/PromptAgentFactory.cs similarity index 80% rename from dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs rename to dotnet/src/Microsoft.Agents.AI.Declarative/PromptAgentFactory.cs index 0b60cc86c8..cb277b06da 100644 --- a/dotnet/src/Microsoft.Agents.AI.Declarative/AgentFactory.cs +++ b/dotnet/src/Microsoft.Agents.AI.Declarative/PromptAgentFactory.cs @@ -13,15 +13,16 @@ namespace Microsoft.Agents.AI; /// /// Represents a factory for creating instances. /// -public abstract class AgentFactory +public abstract class PromptAgentFactory { /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// - /// The configuration. - protected AgentFactory(IConfiguration? configuration = null) + /// Optional , if none is provided a default instance will be created. + /// Optional configuration to be added as variables to the . + protected PromptAgentFactory(RecalcEngine? engine = null, IConfiguration? configuration = null) { - this.Engine = new RecalcEngine(); + this.Engine = engine ?? new RecalcEngine(); if (configuration is not null) { diff --git a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorPromptAgentFactoryTests.cs similarity index 83% rename from dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs rename to dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorPromptAgentFactoryTests.cs index a09f134983..d20bd9be00 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorAgentFactoryTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Declarative.UnitTests/AggregatorPromptAgentFactoryTests.cs @@ -11,22 +11,22 @@ namespace Microsoft.Agents.AI.Declarative.UnitTests; /// -/// Unit tests for +/// Unit tests for /// -public sealed class AggregatorAgentFactoryTests +public sealed class AggregatorPromptAgentFactoryTests { [Fact] public void AggregatorAgentFactory_ThrowsForEmptyArray() { // Arrange & Act & Assert - Assert.Throws(() => new AggregatorAgentFactory([])); + Assert.Throws(() => new AggregatorPromptAgentFactory([])); } [Fact] public async Task AggregatorAgentFactory_ReturnsNull() { // Arrange - var factory = new AggregatorAgentFactory([new TestAgentFactory(null)]); + var factory = new AggregatorPromptAgentFactory([new TestAgentFactory(null)]); // Act var agent = await factory.TryCreateAsync(new GptComponentMetadata("test")); @@ -40,7 +40,7 @@ public async Task AggregatorAgentFactory_ReturnsAgent() { // Arrange var agentToReturn = new TestAgent(); - var factory = new AggregatorAgentFactory([new TestAgentFactory(null), new TestAgentFactory(agentToReturn)]); + var factory = new AggregatorPromptAgentFactory([new TestAgentFactory(null), new TestAgentFactory(agentToReturn)]); // Act var agent = await factory.TryCreateAsync(new GptComponentMetadata("test")); @@ -49,7 +49,7 @@ public async Task AggregatorAgentFactory_ReturnsAgent() Assert.Equal(agentToReturn, agent); } - private sealed class TestAgentFactory : AgentFactory + private sealed class TestAgentFactory : PromptAgentFactory { private readonly AIAgent? _agentToReturn;