ChatFeature Configuration

Every AI Chat capability is configured from a single ChatFeature plugin registration. Extension-specific options are reached through the extension properties it exposes (Tools, ApiTools, Mcp, Publish, Pdf, …), so a complete configuration reads as one object graph.

services.AddPlugin(new ChatFeature {
    RequireAuth = true,
    RequiredRole = "Employee",
    AuthType = ChatAuthType.Credentials,

    DisableExtensions = ["computer", "publish"],

    Tools = {
        EnableApiTools = true,
        EnableFilesystemTools = false,
        EnableCodeExecution = false,
    },
    ApiTools = {
        IncludeTags = ["CoffeeShop", "Bookings"],
    },
    Mcp = {
        ToolGroups = ["api_tools"],
    },

    Setup = ctx => {
        // runs after config + providers are created, before extensions install
    },
});

Hosting​

Mounting at the site root​

RoutePrefix = "" gives full llms.py fidelity, serving the Chat UI from / - appropriate for a dedicated AI host rather than an App with its own pages:

services.AddPlugin(new ChatFeature { RoutePrefix = "" });

Extensions​

services.AddPlugin(new ChatFeature {
    // remove the filesystem + run_bash tools completely
    DisableExtensions = ["computer"],

    // add your App's own extension
    Extensions = {
        new BookingToolsExtension(),
    },
});

disable_extensions in llms.json is merged with DisableExtensions, so extensions can also be turned off without a redeploy. See Extensions.

Configuring your own extensions​

An extension's configuration is just its own properties, so your extensions are configured where they're added - the same object-initializer syntax the built-ins use, one level deeper:

services.AddPlugin(new ChatFeature {
    Extensions = {
        new BookingToolsExtension {
            NamedConnection = "reporting",
            DefaultTake = 50,
            IncludeCancelled = false,
        },
    },
});

Those values are set before Install(ctx) runs, so an extension can read its own configuration while registering its routes and tools:

public class BookingToolsExtension() : ChatExtension("booking_tools")
{
    /// <summary>OrmLite connection bookings are read from</summary>
    public string? NamedConnection { get; set; }
    /// <summary>Rows returned when the Agent doesn't specify a limit</summary>
    public int DefaultTake { get; set; } = 25;
    /// <summary>Whether cancelled bookings are counted in summaries</summary>
    public bool IncludeCancelled { get; set; }

    public override void Install(ExtensionContext ctx)
    {
        if (NamedConnection != null)
            ctx.Log.LogInformation("Bookings using {Db}", NamedConnection);

        ctx.RegisterTool<BookingSummaryCommand>("bookings");
    }
}

Configuration that has to see the fully-loaded feature belongs in Setup instead, which runs after config and providers load but before extensions install:

services.AddPlugin(new ChatFeature {
    Extensions = { new BookingToolsExtension() },
    Setup = ctx => {
        ctx.AssertExtension<BookingToolsExtension>().DefaultTake = ctx.ApiTools.DefaultTake;
    },
});

See Custom Extensions for the full ExtensionContext API.

Providers & config​

Update Provider Models​

Each ServiceStack release includes the latest providers.json. To update the provider catalog between releases, override it with the latest version from the ServiceStack/llms repo.

Run the following command from your application's App_Data/chat directory to download and overwrite providers.json:

curl -fL https://raw.githubusercontent.com/ServiceStack/llms/refs/heads/main/llms/providers.json -o providers.json

See Providers & Models.

Limits​

Limits mirrors the limits object in llms.json:

services.AddPlugin(new ChatFeature {
    Limits = {
        MaxIterations = 20,
        StreamCheckpointInterval = TimeSpan.FromMilliseconds(500),
    },
});

MaxIterations is the ceiling on an agentic loop: a Model that keeps calling tools stops after this many rounds. Raise it for long multi-step workflows, lower it to bound cost.

Request hooks​

services.AddPlugin(new ChatFeature {
    ValidateRequest = async req => {
        if (req.GetSession() is { } session && await IsOverQuotaAsync(session.UserAuthId))
            return HttpError.Forbidden("Monthly AI quota exceeded");
        return null;
    },

    // populate the Admin analytics user filter from the App's Identity users
    UserNamesResolver = req => req.Resolve<IDbConnectionFactory>().Open()
        .Column<string>(db.From<ApplicationUser>().Select(x => x.UserName)),
});

Setup is the escape hatch for configuration that has to see the fully-loaded feature:

Setup = ctx => {
    ctx.Mcp.ToolGroups = ["api_tools", "core_tools", "booking_tools"];
    ctx.Tools.ToolTimeout = TimeSpan.FromSeconds(120);
}

Tool sandboxing​

Tools = {
    EnableFilesystemTools = true,
    AllowedDirectories = ["/srv/workspaces"],
}

Higher-risk capabilities are opt-in. Filesystem and code execution tools stay unregistered unless the host turns them on - and even then, Projects further narrows each user's reachable directories. See Tools.

AI Chat and the OpenAI API​

ChatFeature also registers the typed ChatCompletion service at POST /v1/chat/completions and an in-process IChatClient. Both run the same pipeline - provider selection, retry/failover, the tool loop, usage and cost accounting. See Chat API.

Full configuration reference​

services.AddPlugin(new ChatFeature {
    // ── Hosting ──
    RoutePrefix = "/chat",
    RequireAuth = true,
    RequiredRole = null,
    AuthType = ChatAuthType.Credentials,
    SignInUrl = "/Account/Login",
    AppDataPath = null,             // ~/App_Data/chat
    AutoInitSchema = true,
    NamedConnection = null,
    DisableAdminUi = false,

    // ── Extensions ──
    DisableExtensions = [],
    Extensions = { /* built-ins + your own */ },

    // ── Providers ──
    EnableProviders = [],
    Variables = {},
    LoadingMessages = ["Computing", "Cooking", "Crafting", "Creating"],

    // ── Limits ──
    Limits = {
        ClientTimeout = 120,
        ClientMaxSize = 20 * 1024 * 1024,
        Retries = 3,
        MaxIterations = 10,
        StreamCheckpointInterval = TimeSpan.FromMilliseconds(250),
    },

    // ── Extension config ──
    Tools     = { EnableApiTools = true, EnableFilesystemTools = false, EnableCodeExecution = false },
    ApiTools  = { IncludeTags = [], IncludeTypes = [], ExcludeTypes = [], DefaultTake = 25, MaxTake = 100 },
    Mcp       = { ToolGroups = [], Tools = [], RejectToolsRequiringApproval = true },
    Publish   = { Enabled = false },

    // ── Hooks ──
    ValidateRequest = null,
    ValidateDownloadUrl = null,
    UserNamesResolver = null,
    ImageTransformer = null,
    Setup = null,
});