integrate-ai

name	integrate-ai
description	ABP AI workspaces with Microsoft.Extensions.AI, Microsoft Agent Framework, or Microsoft.SemanticKernel. USE FOR: choosing an ABP AI abstraction, AbpAIModule, AbpAIWorkspaceOptions, resolving IChatClient/IChatClientAccessor/IKernelAccessor, per-workspace provider/model config. DO NOT USE FOR: general .NET AI/ML outside ABP's workspace integration (out of scope); AI-call observability (out of scope); tenant-editable AI providers via the commercial AI Management module.
license	MIT

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:

[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

[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:

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:

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.