--- 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 ```json { "steps": [ { "name": "Feature", "enable": [ "CrestApps.OrchardCore.AI", "CrestApps.OrchardCore.AI.Chat", "CrestApps.OrchardCore.OpenAI" ], "disable": [] } ] } ``` ### Setting Up a Provider Connection via Recipe ```json { "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: ```json { "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 ```json { "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 ```csharp public sealed class AIChatProfileMigrations : DataMigration { private readonly IAIProfileManager _profileManager; public AIChatProfileMigrations(IAIProfileManager profileManager) { _profileManager = profileManager; } public async Task 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.). ```json { "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 ```json { "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 ```csharp 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 ```csharp public sealed class LookupOrderFunction : AIFunction { public const string TheName = "lookup_order"; private static readonly JsonElement _jsonSchema = JsonSerializer.Deserialize( """ { "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 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: ```csharp services.AddAITool(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:** ```csharp profile.AlterSettings(s => { s.ChatMode = ChatMode.Conversation; s.VoiceName = "en-US-JennyNeural"; // Optional TTS voice }); ``` > **Important:** Always use `profile.TryGetSettings()` to read and `profile.AlterSettings()` 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) |