|
| 1 | +# Microsoft.Agents.AI (Agent Framework) |
| 2 | + |
| 3 | +[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. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +**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: |
| 8 | + |
| 9 | +```csharp |
| 10 | +using Microsoft.Agents.AI; |
| 11 | +using Microsoft.Extensions.AI; |
| 12 | + |
| 13 | +public class MyService |
| 14 | +{ |
| 15 | + private readonly IChatClient _chatClient; |
| 16 | + |
| 17 | + public MyService(IChatClient chatClient) |
| 18 | + { |
| 19 | + _chatClient = chatClient; |
| 20 | + } |
| 21 | + |
| 22 | + public async Task<string> GetResponseAsync(string userMessage) |
| 23 | + { |
| 24 | + AIAgent agent = _chatClient.CreateAIAgent( |
| 25 | + instructions: "You are a helpful assistant that provides concise answers." |
| 26 | + ); |
| 27 | + |
| 28 | + AgentRunResponse response = await agent.RunAsync(userMessage); |
| 29 | + |
| 30 | + return response.Text; |
| 31 | + } |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +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: |
| 36 | + |
| 37 | +```csharp |
| 38 | +using Microsoft.Agents.AI; |
| 39 | +using Microsoft.Extensions.AI; |
| 40 | +using Volo.Abp.AI; |
| 41 | + |
| 42 | +public class MyService |
| 43 | +{ |
| 44 | + private readonly IChatClientAccessor _chatClientAccessor; |
| 45 | + |
| 46 | + public MyService(IChatClientAccessor chatClientAccessor) |
| 47 | + { |
| 48 | + _chatClientAccessor = chatClientAccessor; |
| 49 | + } |
| 50 | + |
| 51 | + public async Task<string> GetResponseAsync(string userMessage) |
| 52 | + { |
| 53 | + var chatClient = _chatClientAccessor.ChatClient; |
| 54 | + if (chatClient is null) |
| 55 | + { |
| 56 | + return "No chat client configured"; |
| 57 | + } |
| 58 | + |
| 59 | + AIAgent agent = chatClient.CreateAIAgent( |
| 60 | + instructions: "You are a helpful assistant that provides concise answers." |
| 61 | + ); |
| 62 | + |
| 63 | + var response = await agent.RunAsync(userMessage); |
| 64 | + |
| 65 | + return response.Text; |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Workspaces |
| 71 | + |
| 72 | +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. |
| 73 | +- Workspace names must be unique. |
| 74 | +- Workspace names cannot contain spaces _(use underscores or camelCase)_. |
| 75 | +- Workspace names are case-sensitive. |
| 76 | + |
| 77 | +```csharp |
| 78 | +using Volo.Abp.AI; |
| 79 | + |
| 80 | +[WorkspaceName("CommentSummarization")] |
| 81 | +public class CommentSummarization |
| 82 | +{ |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +> [!NOTE] |
| 87 | +> If you don't specify the workspace name, the full name of the class will be used as the workspace name. |
| 88 | +
|
| 89 | +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. |
| 90 | + |
| 91 | +`IChatClient<TWorkSpace>` or `IChatClientAccessor<TWorkSpace>` 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. |
| 92 | + |
| 93 | +Example of resolving a typed chat client for a workspace: |
| 94 | + |
| 95 | +```csharp |
| 96 | +using Microsoft.Agents.AI; |
| 97 | +using Microsoft.Extensions.AI; |
| 98 | +using Volo.Abp.AI; |
| 99 | + |
| 100 | +public class MyService |
| 101 | +{ |
| 102 | + private readonly IChatClient<CustomerSupport> _chatClient; |
| 103 | + |
| 104 | + public MyService(IChatClient<CustomerSupport> chatClient) |
| 105 | + { |
| 106 | + _chatClient = chatClient; |
| 107 | + } |
| 108 | + |
| 109 | + public async Task<string> GetResponseAsync(string userMessage) |
| 110 | + { |
| 111 | + AIAgent agent = _chatClient.CreateAIAgent( |
| 112 | + instructions: "You are a customer support assistant. Be polite and helpful." |
| 113 | + ); |
| 114 | + |
| 115 | + var response = await agent.RunAsync(userMessage); |
| 116 | + return response.Text; |
| 117 | + } |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +Example of resolving a typed chat client accessor for a workspace: |
| 122 | + |
| 123 | +```csharp |
| 124 | +using Microsoft.Agents.AI; |
| 125 | +using Microsoft.Extensions.AI; |
| 126 | +using Volo.Abp.AI; |
| 127 | + |
| 128 | +public class MyService |
| 129 | +{ |
| 130 | + private readonly IChatClientAccessor<CustomerSupport> _chatClientAccessor; |
| 131 | + |
| 132 | + public MyService(IChatClientAccessor<CustomerSupport> chatClientAccessor) |
| 133 | + { |
| 134 | + _chatClientAccessor = chatClientAccessor; |
| 135 | + } |
| 136 | + |
| 137 | + public async Task<string> GetResponseAsync(string userMessage) |
| 138 | + { |
| 139 | + var chatClient = _chatClientAccessor.ChatClient; |
| 140 | + if (chatClient is null) |
| 141 | + { |
| 142 | + return "No chat client configured"; |
| 143 | + } |
| 144 | + |
| 145 | + AIAgent agent = chatClient.CreateAIAgent( |
| 146 | + instructions: "You are a customer support assistant. Be polite and helpful." |
| 147 | + ); |
| 148 | + |
| 149 | + var response = await agent.RunAsync(userMessage); |
| 150 | + return response.Text; |
| 151 | + } |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +## Configuration |
| 156 | + |
| 157 | +**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). |
| 158 | + |
| 159 | +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. |
| 160 | + |
| 161 | +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/). |
| 162 | + |
| 163 | +_The following example requires [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) package to be installed._ |
| 164 | + |
| 165 | +Demonstration of the default workspace configuration: |
| 166 | + |
| 167 | +```csharp |
| 168 | +[DependsOn(typeof(AbpAIModule))] |
| 169 | +public class MyProjectModule : AbpModule |
| 170 | +{ |
| 171 | + public override void PreConfigureServices(ServiceConfigurationContext context) |
| 172 | + { |
| 173 | + PreConfigure<AbpAIWorkspaceOptions>(options => |
| 174 | + { |
| 175 | + options.Workspaces.ConfigureDefault(configuration => |
| 176 | + { |
| 177 | + configuration.ConfigureChatClient(chatClientConfiguration => |
| 178 | + { |
| 179 | + chatClientConfiguration.Builder = new ChatClientBuilder( |
| 180 | + sp => new OllamaApiClient("http://localhost:11434", "mistral") |
| 181 | + ); |
| 182 | + }); |
| 183 | + }); |
| 184 | + }); |
| 185 | + } |
| 186 | +} |
| 187 | +``` |
| 188 | + |
| 189 | +Demonstration of the isolated workspace configuration: |
| 190 | + |
| 191 | +```csharp |
| 192 | +[DependsOn(typeof(AbpAIModule))] |
| 193 | +public class MyProjectModule : AbpModule |
| 194 | +{ |
| 195 | + public override void PreConfigureServices(ServiceConfigurationContext context) |
| 196 | + { |
| 197 | + PreConfigure<AbpAIWorkspaceOptions>(options => |
| 198 | + { |
| 199 | + options.Workspaces.Configure<CustomerSupport>(configuration => |
| 200 | + { |
| 201 | + configuration.ConfigureChatClient(chatClientConfiguration => |
| 202 | + { |
| 203 | + chatClientConfiguration.Builder = new ChatClientBuilder( |
| 204 | + sp => new OllamaApiClient("http://localhost:11434", "mistral") |
| 205 | + ); |
| 206 | + }); |
| 207 | + }); |
| 208 | + }); |
| 209 | + } |
| 210 | +} |
| 211 | +``` |
| 212 | + |
| 213 | +## See Also |
| 214 | + |
| 215 | +- [Usage of Microsoft.Extensions.AI](./microsoft-extensions-ai.md) |
| 216 | +- [Usage of Semantic Kernel](./microsoft-semantic-kernel.md) |
| 217 | +- [Microsoft Agent Framework Overview](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview) |
| 218 | +- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) |
0 commit comments