orchardcore-ai-chat

name	orchardcore-ai-chat
description	Skill for configuring AI Chat in Orchard Core using the CrestApps AI Chat module. Covers chat profiles, admin chat UI, frontend chat widgets, provider connections, and the AI Agent module for task automation. Use this skill when requests mention Orchard Core AI Chat, Configure AI Chat, Available AI Completion Providers, Enabling AI Chat Features, Setting Up a Provider Connection via Recipe, Creating a Chat Profile via Recipe, or closely related Orchard Core implementation, setup, extension, or troubleshooting work. Strong matches include work with CrestApps.OrchardCore.AI.Chat, CrestApps.OrchardCore.AI.Agent, CrestApps.OrchardCore.OpenAI, CrestApps.OrchardCore.AzureAIInference, CrestApps.OrchardCore.Ollama. It also helps with ai chat examples, Setting Up a Provider Connection via Recipe, Creating a Chat Profile via Recipe, Making a Chat Profile Visible on the Admin Menu, plus the code patterns, admin flows, recipe steps, and referenced examples captured in this skill.
license	Apache-2.0
metadata	{"author":"CrestApps Team","version":"1.0"}

Orchard Core AI Chat - Prompt Templates

Configure AI Chat

You are an Orchard Core expert. Generate code, configuration, and recipes for adding AI chat capabilities to an Orchard Core application using CrestApps modules.

Guidelines

• The CrestApps AI Chat module (CrestApps.OrchardCore.AI.Chat) builds on the core AI Services feature to provide chat interfaces.
• You must enable at least one AI completion provider (OpenAI, Azure OpenAI, Azure AI Inference, Ollama, DeepSeek) alongside the chat feature.
• Chat-type AI profiles with the "Show On Admin Menu" option appear under the Artificial Intelligence section in the admin menu.
• When the Widgets feature is enabled, an AI Chat widget can be embedded in frontend content.
• The AI Agent module (CrestApps.OrchardCore.AI.Agent) extends AI profiles with capabilities for content management, user management, feature management, and more.
• Profile types include Chat, Utility, TemplatePrompt, and Agent.
• Agent profiles function as reusable AI agents exposed as tools. They require a Description field and can be selected in the Capabilities tab.
• Agent availability modes: OnDemand (default, user selects) or AlwaysAvailable (auto-included in every request).
• The Capabilities tab is organized: MCP Connections first, then Agents, then Tools.
• Always secure API keys using user secrets or environment variables; never hardcode them.
• Install CrestApps packages in the web/startup project.

Available AI Completion Providers

Provider	Feature ID	Description
OpenAI	CrestApps.OrchardCore.OpenAI	Connect to OpenAI or any OpenAI-compatible endpoint (DeepSeek, Gemini, Together AI, LM Studio, etc.)
Azure OpenAI	CrestApps.OrchardCore.OpenAI.Azure	Azure OpenAI service
Azure AI Inference	CrestApps.OrchardCore.AzureAIInference	Azure AI Inference (GitHub Models)
Ollama	CrestApps.OrchardCore.Ollama	Local Ollama models

For retrieval-backed chat, pair the chat feature with the current AI data and document modules such as CrestApps.OrchardCore.AI.DataSources.AzureAI, CrestApps.OrchardCore.AI.DataSources.Elasticsearch, and the matching CrestApps.OrchardCore.AI.Documents.* modules instead of the older Azure OpenAI with data feature names.

Enabling AI Chat Features

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Setting Up a Provider Connection via Recipe

{
  "steps": [
    {
      "name": "AIProviderConnections",
      "connections": [
        {
          "Source": "OpenAI",
          "Name": "default",
          "DisplayText": "OpenAI",
          "Properties": {
            "OpenAIConnectionMetadata": {
              "Endpoint": "https://api.openai.com/v1",
              "ApiKey": "{{YourApiKey}}"
            }
          }
        }
      ]
    }
  ]
}

Managing Deployments via Recipe

Use typed deployments to bind chat profiles to specific models:

{
  "steps": [
    {
      "name": "AIDeployment",
      "deployments": [
        {
          "ItemId": "openai-chat",
          "Name": "gpt-4o",
          "ClientName": "OpenAI",
          "ConnectionName": "default",
          "Type": "Chat",
          "IsDefault": true
        },
        {
          "ItemId": "openai-utility",
          "Name": "gpt-4o-mini",
          "ClientName": "OpenAI",
          "ConnectionName": "default",
          "Type": "Utility",
          "IsDefault": true
        }
      ]
    }
  ]
}

Creating a Chat Profile via Recipe

{
  "steps": [
    {
      "name": "AIProfile",
      "profiles": [
        {
          "Name": "customer-support-chat",
          "DisplayText": "Customer Support Chat",
          "WelcomeMessage": "Hello! How can I help you today?",
          "FunctionNames": [],
          "Type": "Chat",
          "TitleType": "InitialPrompt",
          "PromptTemplate": null,
          "ChatDeploymentName": "gpt-4o",
          "UtilityDeploymentName": "gpt-4o-mini",
          "Properties": {
            "AIProfileMetadata": {
              "SystemMessage": "You are a helpful customer support assistant. Answer questions about our products and services. Be friendly and concise.",
              "Temperature": 0.3,
              "TopP": null,
              "FrequencyPenalty": null,
              "PresencePenalty": null,
              "MaxTokens": 2048,
              "PastMessagesCount": 10
            }
          }
        }
      ]
    }
  ]
}

The AIProfile recipe format omits Source. Profiles are source-agnostic and resolve their active client from ChatDeploymentName and UtilityDeploymentName.

Making a Chat Profile Visible on the Admin Menu

When creating or editing a profile, enable the "Show On Admin Menu" option. Profiles with this setting appear under Artificial Intelligence in the admin sidebar.

Defining a Chat Profile in Code with DataMigration

public sealed class AIChatProfileMigrations : DataMigration
{
    private readonly IAIProfileManager _profileManager;

    public AIChatProfileMigrations(IAIProfileManager profileManager)
    {
        _profileManager = profileManager;
    }

    public async Task<int> CreateAsync()
    {
        var profile = await _profileManager.NewAsync();

        profile.Name = "site-assistant";
        profile.DisplayText = "Site Assistant";
        profile.Type = AIProfileType.Chat;

        profile.WithSettings(new AIProfileSettings
        {
            LockSystemMessage = true,
            IsRemovable = false,
            IsListable = true,
        });

        profile.WithSettings(new AIChatProfileSettings
        {
            IsOnAdminMenu = true,
        });

        profile.Put(new AIProfileMetadata
        {
            SystemMessage = "You are a site assistant. Help users navigate the site and answer questions.",
            Temperature = 0.3f,
            MaxTokens = 4096,
            PastMessagesCount = 10,
        });

        await _profileManager.SaveAsync(profile);

        return 1;
    }
}

Enabling the AI Agent Module

The AI Agent module provides tools that allow AI profiles to perform tasks on the Orchard Core site (content management, feature management, user management, etc.).

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat",
        "CrestApps.OrchardCore.AI.Agent",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Once enabled, navigate to your AI profile and assign capabilities under the Capabilities tab. The tab is organized in this order: MCP Connections, Agents, Tools.

Creating an Agent Profile

Agent profiles are reusable agents that can be invoked as tools by other profiles. When creating an Agent profile:

1. Set Type to Agent
2. Provide a Description — this is used by the LLM to decide when to invoke the agent
3. Set Availability to OnDemand (default) or AlwaysAvailable
4. Configure a system message, tools, and other capabilities

{
  "steps": [
    {
      "name": "AIProfile",
      "profiles": [
        {
          "Name": "research-agent",
          "DisplayText": "Research Agent",
          "Description": "An agent that can research topics and provide comprehensive summaries with citations.",
          "Type": "Agent",
          "TitleType": "InitialPrompt",
          "ChatDeploymentName": "gpt-4o",
          "UtilityDeploymentName": "gpt-4o-mini",
          "Properties": {
            "AIProfileMetadata": {
              "SystemMessage": "You are a research assistant. Gather information, verify facts, and provide comprehensive answers with sources.",
              "Temperature": 0.3,
              "MaxTokens": 4096
            },
            "AgentMetadata": {
              "Availability": "OnDemand"
            }
          }
        }
      ]
    }
  ]
}

Creating an Agent Profile in Code

var profile = await _profileManager.NewAsync();

profile.Name = "research-agent";
profile.DisplayText = "Research Agent";
profile.Description = "Researches topics and provides comprehensive summaries with citations.";
profile.Type = AIProfileType.Agent;

profile.Put(new AIProfileMetadata
{
    SystemMessage = "You are a research assistant...",
    Temperature = 0.3f,
    MaxTokens = 4096,
});

profile.Put(new AgentMetadata
{
    Availability = AgentAvailability.OnDemand,
});

await _profileManager.SaveAsync(profile);

Adding an AI Chat Widget to Frontend Content

When the Widgets feature is enabled, you can add an AI Chat widget to zones. Create a widget layer and add the AI Chat widget to display the chat interface on your frontend pages.

Creating a Custom AI Tool for Chat

public sealed class LookupOrderFunction : AIFunction
{
    public const string TheName = "lookup_order";

    private static readonly JsonElement _jsonSchema = JsonSerializer.Deserialize<JsonElement>(
    """
     {
       "type": "object",
       "properties": {
         "OrderId": {
           "type": "string",
           "description": "The order ID to look up."
         }
       },
       "additionalProperties": false,
       "required": ["OrderId"]
     }
    """);

    public override string Name => TheName;

    public override string Description => "Looks up order details by order ID.";

    public override JsonElement JsonSchema => _jsonSchema;

    protected override async ValueTask<object> InvokeCoreAsync(
        AIFunctionArguments arguments,
        CancellationToken cancellationToken)
    {
        if (!arguments.TryGetValue("OrderId", out var value) || value is null)
        {
            return "OrderId is required.";
        }

        var orderId = value is JsonElement jsonElement
            ? jsonElement.GetString()
            : value?.ToString();

        // Replace with actual order lookup logic.
        return $"Order {orderId}: Status=Shipped, ETA=2 days.";
    }
}

Register the tool and assign it to a profile:

services.AddAITool<LookupOrderFunction>(LookupOrderFunction.TheName, options =>
{
    options.Title = "Order Lookup";
    options.Description = "Looks up order details by order ID.";
    options.Category = "Commerce";
});

Security Best Practices

• Store API keys using dotnet user-secrets during development.
• Use environment variables or Azure Key Vault in production.
• Restrict AI profile access with Orchard Core permissions.
• Set appropriate token limits to control costs.
• Lock system messages on production profiles to prevent prompt injection.

Chat Mode Configuration

Chat profiles support three modes via the ChatModeProfileSettings:

Mode	Description	Requirements
TextOnly	Standard text-only chat (default)	None
AudioInput	Adds microphone button for speech-to-text dictation. User types or dictates, then sends manually.	DefaultSpeechToTextDeploymentName configured in site settings
Conversation	Two-way voice conversation. User speaks → transcript sent automatically → AI responds with text and spoken audio.	Both DefaultSpeechToTextDeploymentName and DefaultTextToSpeechDeploymentName configured

Chat mode is set in the AI Profile edit page under the "Chat Mode" dropdown (only visible for Chat-type profiles).

In code:

profile.AlterSettings<ChatModeProfileSettings>(s =>
{
    s.ChatMode = ChatMode.Conversation;
    s.VoiceName = "en-US-JennyNeural"; // Optional TTS voice
});

Important: Always use profile.TryGetSettings<ChatModeProfileSettings>() to read and profile.AlterSettings<ChatModeProfileSettings>() to write. Do not read this data from Entity.Properties; chat mode settings live in AIProfile.Settings.

Voice Configuration

When ChatMode is Conversation, a voice dropdown appears in the AI Profile editor, populated via AJAX from the configured TTS deployment. Voices are grouped by language and sorted alphabetically. If no voice is selected, the provider's default voice is used.

The SpeechVoice model includes: Id, Name, Language, Gender, and VoiceSampleUrl.

Admin Chat Session UI

Chat profiles are accessible at /admin/ai-chat/session/{profileId}. The session view:

• Supports all three chat modes (TextOnly, AudioInput, Conversation)
• Shows microphone button when AudioInput or Conversation mode is enabled
• Shows conversation (headset) button when Conversation mode is enabled
• Streams audio and text simultaneously during conversation mode
• Supports document upload when the session documents feature is enabled

Admin Widget and Frontend Widget

Both the admin widget (AIChatAdminWidget) and frontend widget (Widget-AIChat) support all chat modes. Chat configuration is passed to JavaScript via data-config attributes on hidden elements, not inline @Html.Raw().

SignalR Hub Methods (AIChatHub)

Method	Description
CreateSession	Creates a new chat session
SendMessage	Sends a text message to the AI
SendAudioStream	Streams audio chunks for speech-to-text transcription
StartConversation	Starts a full two-way voice conversation
SynthesizeSpeech	Converts text to speech audio
RateMessage	Rates an assistant message (thumbs up/down)