integrate-ai

# Integrating AI with ABP This integration is new and has active API/documentation movement. Re-check the target ABP version before copying these names or fallback rules. ## When to Use - Give a reusable ABP module an optional AI dependency through accessors. - Configure one default model/provider or isolated named workspaces. - Build application agents on top of the configured `IChatClient`. - Use Semantic Kernel through an ABP-configured `Kernel` accessor. ## When Not to Use - **Select AI/ML technology without an ABP workspace requirement** — out of scope; choose the .NET AI library directly. - **Configure traces, metrics, or AI telemetry** — out of scope here; ABP ships no OpenTelemetry framework module, so wire the OpenTelemetry .NET SDK directly. - **Dynamically manage providers/models through the commercial AI Management UI** — that module is outside the framework abstractions covered here. ## Workflow ### 1. Choose the integration surface ABP's `Volo.Abp.AI` package supports three related surfaces: - **Microsoft.Extensions.AI** — use `IChatClient`; ABP recommends this minimal abstraction for reusable libraries. - **Microsoft Agent Framework** — create agents from an `IChatClient` with `CreateAIAgent`; ABP recommends it for agent applications. - **Microsoft.SemanticKernel** — use `IKernelAccessor` when Semantic Kernel-specific integration is required. Agent Framework does not have a separate ABP workspace module. It runs on the `IChatClient` configured by the Microsoft.Extensions.AI path. ### 2. Add the module and a provider package Depend on `AbpAIModule` from `Volo.Abp.AI`: ```csharp [DependsOn(typeof(AbpAIModule))] public class MyAppModule : AbpModule { } ``` Also add the provider/connector package used to construct the `ChatClientBuilder` or `IKernelBuilder`. ABP does not choose provider credentials, endpoint, or model for you. ### 3. Define a workspace when isolation is needed ```csharp [WorkspaceName("CommentSummarization")] public class CommentSummarizationWorkspace { } ``` `WorkspaceNameAttribute.GetWorkspaceName<T>()` returns the attribute value, or the type's full name when the attribute is absent. Treat workspace names as unique and case-sensitive; the docs also disallow spaces. ### 4. Pre-configure workspaces Use `PreConfigure<AbpAIWorkspaceOptions>` before `AbpAIModule.ConfigureServices` consumes the configuration: ```csharp public override void PreConfigureServices(ServiceConfigurationContext context) { PreConfigure<AbpAIWorkspaceOptions>(options => { options.Workspaces.ConfigureDefault(workspace => { workspace.ConfigureChatClient(chat => { chat.Builder = CreateChatClientBuilder(); }); }); options.Workspaces.Configure<CommentSummarizationWorkspace>(workspace => { workspace.ConfigureChatClient(chat => { chat.Builder = CreateSummarizationChatClientBuilder(); }); }); }); } ``` `WorkspaceConfiguration` always exposes `ChatClient` and `Kernel` configurations. Set each `Builder` once; use `ConfigureBuilder(...)` to append named or unnamed builder actions, which ABP applies in insertion order before registering services. For Semantic Kernel, call `workspace.ConfigureKernel(kernel => kernel.Builder = ...)`. The ABP source consumes `AbpAIWorkspaceOptions`; do not copy documentation examples that use `PreConfigure<AbpAIOptions>` for kernel setup. ### 5. Resolve the narrowest service For a required default chat client, inject Microsoft's `IChatClient`. For optional AI in a reusable module, inject ABP's `IChatClientAccessor` and null-check `ChatClient`. For typed workspaces: ```csharp public class CommentSummarizer { private readonly IChatClientAccessor<CommentSummarizationWorkspace> _accessor; public CommentSummarizer( IChatClientAccessor<CommentSummarizationWorkspace> accessor) { _accessor = accessor; } public async Task<string?> SummarizeAsync(string comment) { var client = _accessor.ChatClient; return client is null ? null : (await client.GetResponseAsync(comment)).Text; } } ``` Verified behavior: - `IChatClientAccessor<TWorkspace>` falls back to the default chat client when the named client is absent. - `IChatClient<TWorkspace>` also falls back to the default, but resolution fails if neither exists. - `IKernelAccessor<TWorkspace>` does not fall back to the default kernel; it returns null when its keyed kernel is absent. - `IChatClientAccessor` and `IKernelAccessor` for the default workspace return nullable values. - Configuring only a chat client causes ABP to build a keyed Kernel containing that chat client. Configuring only a Kernel can expose the Kernel's required `IChatClient` under the workspace chat-client key. For Agent Framework, obtain the configured `IChatClient`, call `CreateAIAgent(...)`, then run the returned `AIAgent`. Workspace configuration remains the same. ## Validation - Start with no configured workspace and verify optional accessors return null. - Configure the default workspace and verify untyped `IChatClient` resolves and sends a test request to the chosen provider. - Configure two typed workspaces and verify each resolves its own keyed client/model. - Verify typed chat fallback and typed kernel no-fallback behavior separately. - Keep provider calls out of unit tests or replace the client with a deterministic test double; run one explicit integration test for credentials/network wiring. ## Common Pitfalls - **Using `Configure<AbpAIWorkspaceOptions>` instead of `PreConfigure`** — the module executes pre-configured actions while registering services. - **Copying the Semantic Kernel doc's `AbpAIOptions` example** — ABP source configuration uses `AbpAIWorkspaceOptions`; `AbpAIOptions` only tracks configured workspace names. - **Assuming all typed accessors share fallback behavior** — chat accessors fall back to default; kernel accessors do not. - **Injecting required `IChatClient` into an optional reusable module** — use `IChatClientAccessor` and handle null. - **Treating Agent Framework as separate ABP configuration** — it is built on the configured Microsoft.Extensions.AI `IChatClient`. - **Hard-coding secrets in module code** — obtain endpoints, keys, and model names from secure host configuration. - **Freezing these APIs for future ABP versions** — this area is explicitly version-sensitive; re-verify after upgrading.