diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 08b4553d64..0c75f1982d 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -563,7 +563,11 @@ { "text": "Microsoft.Extensions.AI", "path": "framework/infrastructure/artificial-intelligence/microsoft-extensions-ai.md" - }, + }, + { + "text": "Agent Framework", + "path": "framework/infrastructure/artificial-intelligence/microsoft-agent-framework.md" + }, { "text": "Semantic Kernel", "path": "framework/infrastructure/artificial-intelligence/microsoft-semantic-kernel.md" diff --git a/docs/en/framework/infrastructure/artificial-intelligence/index.md b/docs/en/framework/infrastructure/artificial-intelligence/index.md index bdd1125e9d..ddf9ad4b07 100644 --- a/docs/en/framework/infrastructure/artificial-intelligence/index.md +++ b/docs/en/framework/infrastructure/artificial-intelligence/index.md @@ -27,12 +27,14 @@ abp add-package Volo.Abp.AI The `Volo.Abp.AI` package provides integration with the following libraries: * [Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) +* [Microsoft.Agents.AI (Agent Framework)](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview) * [Microsoft.SemanticKernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) -The Microsoft.Extensions.AI library is suggested for library developers to keep the library dependency minimum and simple (since it provides basic abstractions and fundamental AI provider integrations), while Semantic Kernel is suggested for applications that need rich and advanced AI integration features. +The **Microsoft.Extensions.AI** library is suggested for library developers to keep the library dependency minimum and simple (since it provides basic abstractions and fundamental AI provider integrations). For applications, **Microsoft Agent Framework** is the recommended choice as it combines the best of both AutoGen and Semantic Kernel (it's direct successor of these two frameworks), offering simple abstractions for single- and multi-agent patterns along with advanced features like thread-based state management, type safety, filters, and telemetry. **Semantic Kernel** can still be used if you need its specific AI integration features. Check the following documentation to learn how to use these libraries with the ABP integration: - [ABP Microsoft.Extensions.AI integration](./microsoft-extensions-ai.md) +- [ABP Microsoft.Agents.AI (Agent Framework) integration](./microsoft-agent-framework.md) - [ABP Microsoft.SemanticKernel integration](./microsoft-semantic-kernel.md) diff --git a/docs/en/framework/infrastructure/artificial-intelligence/microsoft-agent-framework.md b/docs/en/framework/infrastructure/artificial-intelligence/microsoft-agent-framework.md new file mode 100644 index 0000000000..d3e7d128fc --- /dev/null +++ b/docs/en/framework/infrastructure/artificial-intelligence/microsoft-agent-framework.md @@ -0,0 +1,218 @@ +# Microsoft.Agents.AI (Agent Framework) + +[Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview) is an open-source development kit for **building AI agents** and **multi-agent workflows**. It is the direct successor to both *AutoGen* and [*Semantic Kernel*](./microsoft-semantic-kernel.md), combining their strengths while adding new capabilities, and is the suggested framework for building AI agent applications. This documentation is about the usage of this library with ABP Framework. Make sure you have read the [Artificial Intelligence](./index.md) documentation before reading this documentation. + +## Usage + +**Microsoft Agent Framework** works on top of `IChatClient` from **Microsoft.Extensions.AI**. After obtaining an `IChatClient` instance, you can create an AI agent using the `CreateAIAgent` extension method: + +```csharp +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +public class MyService +{ + private readonly IChatClient _chatClient; + + public MyService(IChatClient chatClient) + { + _chatClient = chatClient; + } + + public async Task GetResponseAsync(string userMessage) + { + AIAgent agent = _chatClient.CreateAIAgent( + instructions: "You are a helpful assistant that provides concise answers." + ); + + AgentRunResponse response = await agent.RunAsync(userMessage); + + return response.Text; + } +} +``` + +You can also use `IChatClientAccessor` to access the `IChatClient` in scenarios where AI capabilities are **optional**, such as when developing a module or a service that may use AI capabilities optionally: + +```csharp +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Volo.Abp.AI; + +public class MyService +{ + private readonly IChatClientAccessor _chatClientAccessor; + + public MyService(IChatClientAccessor chatClientAccessor) + { + _chatClientAccessor = chatClientAccessor; + } + + public async Task GetResponseAsync(string userMessage) + { + var chatClient = _chatClientAccessor.ChatClient; + if (chatClient is null) + { + return "No chat client configured"; + } + + AIAgent agent = chatClient.CreateAIAgent( + instructions: "You are a helpful assistant that provides concise answers." + ); + + var response = await agent.RunAsync(userMessage); + + return response.Text; + } +} +``` + +### Workspaces + +Workspaces are a way to configure isolated AI configurations for a named scope. You can define a workspace by decorating a class with the `WorkspaceNameAttribute` attribute that carries the workspace name. +- Workspace names must be unique. +- Workspace names cannot contain spaces _(use underscores or camelCase)_. +- Workspace names are case-sensitive. + +```csharp +using Volo.Abp.AI; + +[WorkspaceName("CommentSummarization")] +public class CommentSummarization +{ +} +``` + +> [!NOTE] +> If you don't specify the workspace name, the full name of the class will be used as the workspace name. + +You can resolve generic versions of `IChatClient` and `IChatClientAccessor` services for a specific workspace as generic arguments. If Chat Client is not configured for a workspace, you will get `null` from the accessor services. You should check the accessor before using it. This applies only for specified workspaces. Another workspace may have a configured Chat Client. + +`IChatClient` or `IChatClientAccessor` can be resolved to access a specific workspace's chat client. This is a typed chat client and can be configured separately from the default chat client. + +Example of resolving a typed chat client for a workspace: + +```csharp +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Volo.Abp.AI; + +public class MyService +{ + private readonly IChatClient _chatClient; + + public MyService(IChatClient chatClient) + { + _chatClient = chatClient; + } + + public async Task GetResponseAsync(string userMessage) + { + AIAgent agent = _chatClient.CreateAIAgent( + instructions: "You are a customer support assistant. Be polite and helpful." + ); + + var response = await agent.RunAsync(userMessage); + return response.Text; + } +} +``` + +Example of resolving a typed chat client accessor for a workspace: + +```csharp +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Volo.Abp.AI; + +public class MyService +{ + private readonly IChatClientAccessor _chatClientAccessor; + + public MyService(IChatClientAccessor chatClientAccessor) + { + _chatClientAccessor = chatClientAccessor; + } + + public async Task GetResponseAsync(string userMessage) + { + var chatClient = _chatClientAccessor.ChatClient; + if (chatClient is null) + { + return "No chat client configured"; + } + + AIAgent agent = chatClient.CreateAIAgent( + instructions: "You are a customer support assistant. Be polite and helpful." + ); + + var response = await agent.RunAsync(userMessage); + return response.Text; + } +} +``` + +## Configuration + +**Microsoft Agent Framework** uses `IChatClient` from **Microsoft.Extensions.AI** as its foundation. Therefore, the configuration process for workspaces is the same as described in the [Microsoft.Extensions.AI documentation](./microsoft-extensions-ai.md#configuration). + +You need to configure the Chat Client for your workspace using `AbpAIWorkspaceOptions`, and then you can use the `CreateAIAgent` extension method to create AI agents from the configured chat client. + +To configure a chat client, you'll need a LLM provider package such as [Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) or [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/). + +_The following example requires [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) package to be installed._ + +Demonstration of the default workspace configuration: + +```csharp +[DependsOn(typeof(AbpAIModule))] +public class MyProjectModule : AbpModule +{ + public override void PreConfigureServices(ServiceConfigurationContext context) + { + PreConfigure(options => + { + options.Workspaces.ConfigureDefault(configuration => + { + configuration.ConfigureChatClient(chatClientConfiguration => + { + chatClientConfiguration.Builder = new ChatClientBuilder( + sp => new OllamaApiClient("http://localhost:11434", "mistral") + ); + }); + }); + }); + } +} +``` + +Demonstration of the isolated workspace configuration: + +```csharp +[DependsOn(typeof(AbpAIModule))] +public class MyProjectModule : AbpModule +{ + public override void PreConfigureServices(ServiceConfigurationContext context) + { + PreConfigure(options => + { + options.Workspaces.Configure(configuration => + { + configuration.ConfigureChatClient(chatClientConfiguration => + { + chatClientConfiguration.Builder = new ChatClientBuilder( + sp => new OllamaApiClient("http://localhost:11434", "mistral") + ); + }); + }); + }); + } +} +``` + +## See Also + +- [Usage of Microsoft.Extensions.AI](./microsoft-extensions-ai.md) +- [Usage of Semantic Kernel](./microsoft-semantic-kernel.md) +- [Microsoft Agent Framework Overview](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview) +- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) \ No newline at end of file diff --git a/docs/en/framework/infrastructure/artificial-intelligence/microsoft-extensions-ai.md b/docs/en/framework/infrastructure/artificial-intelligence/microsoft-extensions-ai.md index 35b370585e..b44572838a 100644 --- a/docs/en/framework/infrastructure/artificial-intelligence/microsoft-extensions-ai.md +++ b/docs/en/framework/infrastructure/artificial-intelligence/microsoft-extensions-ai.md @@ -172,5 +172,6 @@ public class MyProjectModule : AbpModule ## See Also +- [Usage of Agent Framework](./microsoft-agent-framework.md) - [Usage of Semantic Kernel](./microsoft-semantic-kernel.md) - [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) \ No newline at end of file diff --git a/docs/en/modules/ai-management/index.md b/docs/en/modules/ai-management/index.md index 0b36d0e539..6bd0bdc483 100644 --- a/docs/en/modules/ai-management/index.md +++ b/docs/en/modules/ai-management/index.md @@ -832,4 +832,5 @@ The cache is automatically invalidated when workspaces are created, updated, or - [Artificial Intelligence Infrastructure](../../framework/infrastructure/artificial-intelligence/index.md): Learn about the underlying AI workspace infrastructure - [Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/): Microsoft's unified AI abstractions +- [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview): Microsoft's Agent Framework - [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/): Microsoft's Semantic Kernel integration