|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "How to: Using Microsoft's AI extensions with Dapr's .NET Conversation SDK" |
| 4 | +linkTitle: "How to: Use Microsoft's AI extensions with Dapr" |
| 5 | +weight: 500200 |
| 6 | +description: Learn how to create and use Dapr with Microsoft's AI extensions |
| 7 | +--- |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | +- [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0), or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed |
| 11 | +- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) |
| 12 | +- [Initialized Dapr environment](https://docs.dapr.io/getting-started/install-dapr-selfhost) |
| 13 | + |
| 14 | +## Installation |
| 15 | + |
| 16 | +To get started with this SDK, install both the [Dapr.AI](https://www.nuget.org/packages/Dapr.AI) and |
| 17 | +[Dapr.AI.Microsoft.Extensions](https://www.nuget.org/packages/Dapr.AI.Microsoft.Extensions) packages from NuGet: |
| 18 | +```sh |
| 19 | +dotnet add package Dapr.AI |
| 20 | +dotnet add package Dapr.AI.Microsoft.Extensions |
| 21 | +``` |
| 22 | + |
| 23 | +The `DaprChatClient` is a Dapr-based implementation of the `IChatClient` interface provided in the |
| 24 | +`Microsoft.Extensions.AI.Abstractions` package using Dapr's [conversation building block]({{ ref conversation-overview.md }}). It allows |
| 25 | +developers to build against the types provided by Microsoft's abstraction while providing the greatest conformity to the |
| 26 | +Dapr conversation building block available. As both approaches adopt OpenAI's API approach, these are expected to increasingly |
| 27 | +converge over time. |
| 28 | + |
| 29 | +{{% alert title="Dapr Conversation Building Block" color="primary" %}} |
| 30 | + |
| 31 | +Do note that Dapr's conversation building block is still in an alpha state, meaning that the shape of the API |
| 32 | +is likely to change future releases. It's the intent of this SDK package to provide an API that's aligned with |
| 33 | +Microsoft's AI extensions that also maps to and conforms with the Dapr API, but the names of types and properties |
| 34 | +may change from one release to the next, so please be aware of this possibility when using this SDK. |
| 35 | + |
| 36 | +{{% /alert %}} |
| 37 | + |
| 38 | +## About Microsoft.Extensions.AI |
| 39 | +The `Dapr.AI.Microsoft.Extensions` package implements the `Microsoft.Extensions.AI` abstractions, providing a unified API for |
| 40 | +AI services in .NET applications. `Microsoft.Extensions.AI` is designed to offer a consistent programming model across |
| 41 | +different AI providers and scenarios. For detailed information about `Microsoft.Extensions.AI`, refer to the |
| 42 | +[official documentation](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai). |
| 43 | + |
| 44 | +{{% alert title="Limited Support" color="warning" %}} |
| 45 | + |
| 46 | +Note that Microsoft's AI extension provide many more properties and methods than Dapr's conversation building block currently |
| 47 | +supports. This package will only map those properties that have Dapr support and will ignore the others, so just because |
| 48 | +it's available in the Microsoft.Extensions.AI package doesn't mean it's supported by Dapr. Rely on this documentation |
| 49 | +and the exposed XML documentation in the package to understand what is and isn't supported. |
| 50 | + |
| 51 | +{{% /alert %}} |
| 52 | + |
| 53 | +## Service Registration |
| 54 | +The `DaprChatClient` can be registered with the dependency injection container using several extension methods. First, |
| 55 | +ensure that you reigster the `DaprConversationClient` that's part of the `Dapr.AI` package from NuGet: |
| 56 | + |
| 57 | +```csharp |
| 58 | +services.AddDaprConversationClient(); |
| 59 | +``` |
| 60 | + |
| 61 | +Then register the `DaprChatClient` with your conversation component name: |
| 62 | + |
| 63 | +```csharp |
| 64 | +services.AddDaprChatClient("my-conversation-component"); |
| 65 | +``` |
| 66 | + |
| 67 | +### Configuration Options |
| 68 | +You can confiugre the `DaprChatClient` using the `DaprChatClientOptions` though the current implementation only |
| 69 | +provides configuration for the component name itself. This is expected to change in future releases. |
| 70 | + |
| 71 | +```csharp |
| 72 | +services.AddDaprChatClient("my-conversation-component", options => |
| 73 | +{ |
| 74 | + // Configure additional options here |
| 75 | +}); |
| 76 | +``` |
| 77 | + |
| 78 | +You can also configure the service lifetime (this defaults to `ServiceLifetime.Scoped`): |
| 79 | + |
| 80 | +```csharp |
| 81 | +services.AddDaprChatClient("my-conversation-component", ServiceLifetime.Singleton); |
| 82 | +``` |
| 83 | + |
| 84 | +## Usage |
| 85 | +Once registered, you can inject and use `IChatClient` in your services: |
| 86 | + |
| 87 | +```csharp |
| 88 | +public class ChatService(IChatClient chatClient) |
| 89 | +{ |
| 90 | + public async Task<IReadOnlyList<string>> GetResponseAsync(string message) |
| 91 | + { |
| 92 | + var response = await chatClient.GetResponseAsync([ |
| 93 | + new ChatMessage(ChatRole.User, |
| 94 | + "Please write me a poem in iambic pentameter about the joys of using Dapr to develop distributed applications with .NET") |
| 95 | + ]); |
| 96 | + |
| 97 | + return response.Messages.Select(msg => msg.Text).ToList(); |
| 98 | + } |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +### Streaming Conversations |
| 103 | +The `DaprChatClient` does not yet support streaming responses and use of the corresponding `GetStreamingResponseAsync` |
| 104 | +methods will throw a `NotImplemenetedException`. This is expected to change in a future release once the Dapr runtime |
| 105 | +supports this functionality. |
| 106 | + |
| 107 | +### Tool Integration |
| 108 | +The client supports function calling through the `Microsoft.Extensions.AI` tool integration. Tools registered with the |
| 109 | +conversation will be automatically available to the large language model. |
| 110 | + |
| 111 | +```csharp |
| 112 | +string GetCurrentWeather() => Random.Shared.NextDouble() > 0.5 ? "It's sunny today!" : "It's raining today!"; |
| 113 | +var toolChatOptions = new ChatOptions { Tools = [AIFunctionFactory.Create(GetCurrentWeather, "weather")] }; |
| 114 | +var toolResponse = await chatClient.GetResponseAsync("What's the weather like today?", toolChatOptions); |
| 115 | +foreach (var toolResp in toolResponse.Messages) |
| 116 | +{ |
| 117 | + Console.WriteLine(toolResp); |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +## Error Handling |
| 122 | +The `DaprChatClient` integrates with Dapr's error handling and will throw appropriate exceptions when issues occur. |
| 123 | + |
| 124 | +## Configuration and Metadata |
| 125 | +The underlying Dapr conversation component can be configured with metadata and parameters through the Dapr conversation |
| 126 | +building block configuration. The `DaprChatClient` will respect these settings when making calls to the conversation component. |
| 127 | + |
| 128 | +## Best Practices |
| 129 | + |
| 130 | +1. **Service Lifetime**: Use `ServiceLifetime.Scoped` or `ServiceLifetime.Singleton` for the `DaprChatClient` registration to avoid creating multiple instances unnecessarily. |
| 131 | + |
| 132 | +2. **Error Handling**: Always wrap calls in appropriate try-catch blocks to handle both Dapr-specific and general exceptions. |
| 133 | + |
| 134 | +3. **Resource Management**: The `DaprChatClient` properly implements `IDisposable` through its base classes, so resources are automatically managed when using dependency injection. |
| 135 | + |
| 136 | +4. **Configuration**: Configure your Dapr conversation component properly to ensure optimal performance and reliability. |
| 137 | + |
| 138 | +## Related Links |
| 139 | + |
| 140 | +- [Dapr Conversation Building Block]({{ ref conversation-overview.md }}) |
| 141 | +- [Microsoft.Extensions.AI Documentation](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) |
| 142 | +- [Dapr .NET Conversation SDK]({{% ref dotnet-ai-conversation-howto.md %}}) |
0 commit comments