Orchard Core AI Chat Interactions - Prompt Templates

Configure AI Chat Interactions

You are an Orchard Core expert. Generate code, configuration, and recipes for adding ad-hoc AI chat interactions with document upload and RAG to an Orchard Core application using CrestApps modules.

Guidelines

The AI Chat Interactions module (CrestApps.OrchardCore.AI.Chat.Interactions) provides ad-hoc chat without predefined AI profiles.
Users can configure temperature, TopP, max tokens, frequency/presence penalties, and past messages count per session.
The current interaction flow is deployment-driven: users select chat and utility deployments per interaction, or rely on the configured site-level default deployments when explicit deployments are not set.
Users can select agents from the Capabilities tab to enhance interaction capabilities. Agent selection is saved via the SignalR hub.
The Capabilities tab is organized: MCP Connections first, then Agents, then Tools.
All chat messages are persisted and sessions can be resumed later.
The AI Documents modules add document upload with RAG (Retrieval Augmented Generation) support.
Document-aware chat interactions should use CrestApps.OrchardCore.AI.Documents.ChatInteractions plus a current data-source module such as CrestApps.OrchardCore.AI.DataSources.AzureAI or CrestApps.OrchardCore.AI.DataSources.Elasticsearch.
Image and chart generation are orchestration system tools (generate_image and generate_chart), not interaction intents. Image generation requires a deployment with the Image purpose.
Install CrestApps packages in the web/startup project.
Always secure API keys using user secrets or environment variables.

Enabling AI Chat Interactions

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

Getting Started

Enable the AI Chat Interactions feature in the Orchard Core admin under Configuration → Features.
Navigate to Artificial Intelligence → Chat Interactions.
Click + New Chat and select the chat and utility deployments you want to use, or rely on the site-level default deployments.
Configure chat settings (temperature, tools, orchestrator, documents) and start chatting.

Chat interactions are authored as ad-hoc sessions rather than predefined AI profiles. In current guidance, the interaction chooses deployments directly and does not require a profile Source in authoring recipes or prompts.

Configuring Image Generation

To enable image generation, create a deployment with Purpose: Image. The orchestration system tool generate_image resolves that deployment. The generate_chart system tool creates a Chart.js configuration and does not require an image deployment.

Via Admin UI: Navigate to Artificial Intelligence → Deployments and create an Image deployment (e.g., dall-e-3), then optionally set it as a default Image deployment.

Via appsettings.json:

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "Deployments": [
          { "Name": "gpt-4o", "ClientName": "OpenAI", "ConnectionName": "default", "Purpose": "Chat" },
          { "Name": "dall-e-3", "ClientName": "OpenAI", "ConnectionName": "default", "Purpose": "Image" }
        ]
      }
    }
  }
}

Enabling Document Upload and RAG

The AI Documents for Chat Interactions feature (CrestApps.OrchardCore.AI.Documents.ChatInteractions) adds document upload and document-aware prompt processing. Pair it with the current data-source feature for the backend you are using.

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat.Interactions",
        "CrestApps.OrchardCore.AI.Documents.ChatInteractions",
        "CrestApps.OrchardCore.AI.DataSources.AzureAI",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Or for Elasticsearch:

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat.Interactions",
        "CrestApps.OrchardCore.AI.Documents.ChatInteractions",
        "CrestApps.OrchardCore.AI.DataSources.Elasticsearch",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Setting Up Document Indexing

Enable the current data-source feature for Elasticsearch or Azure AI Search.
Navigate to Search → Indexing and create a new index (e.g., "ChatDocuments").
Navigate to Settings → Artificial Intelligence → Chat Interactions and select the new index as the default document index.
Enable the AI Documents for Chat Interactions feature.

Configuring Embedding Model for Documents

Documents require an embedding deployment for RAG. Define it in appsettings.json with Purpose: Embedding:

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "Deployments": [
          { "Name": "gpt-4o", "ClientName": "OpenAI", "ConnectionName": "default", "Purpose": "Chat" },
          { "Name": "text-embedding-3-small", "ClientName": "OpenAI", "ConnectionName": "default", "Purpose": "Embedding" },
          { "Name": "gpt-4o-mini", "ClientName": "OpenAI", "ConnectionName": "default", "Purpose": "Utility" }
        ]
      }
    }
  }
}

For file-format, tabular-data, and custom document-processing guidance, use the AI Documents and AI Documents Extractors features. They own extraction and document-specific tools; Chat Interactions only supplies the chat context and upload UI.

Enabling PDF and Office Document Support

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI.Documents.Pdf",
        "CrestApps.OrchardCore.AI.Documents.OpenXml"
      ],
      "disable": []
    }
  ]
}

Document Upload API Endpoints

Endpoint	Method	Description
`/ai/chat-interactions/upload-document`	POST	Upload one or more documents
`/ai/chat-interactions/remove-document`	POST	Remove a document

Chat Mode in Chat Interactions

Chat interactions support the same ChatMode options as AI profiles, but configured at the site level via ChatInteractionChatModeSettings (under Settings → Artificial Intelligence → Chat Interactions):

Mode	Description	Requirements
`TextInput`	Standard text-only chat (default)	None
`AudioInput`	Adds microphone button for speech-to-text dictation	`DefaultSpeechToTextDeploymentName` configured
`Conversation`	Two-way voice conversation	Both `DefaultSpeechToTextDeploymentName` and `DefaultTextToSpeechDeploymentName` configured

Unlike AI profiles (configured per profile), chat interactions use a single site-wide setting that applies to all chat interaction sessions.

SignalR Hub Methods (ChatInteractionHub)

Method	Description
`SendMessage`	Sends a text message
`LoadInteraction`	Loads an interaction and joins its SignalR group
`SaveSettings`	Persists interaction settings, including selected agents and tools
`SendAudioStream`	Streams audio chunks for speech-to-text transcription
`StartConversation`	Starts a full two-way voice conversation
`SynthesizeSpeech`	Converts text to speech audio
`ClearHistory`	Clears chat history for a session
`HandleNotificationAction`	Dispatches a notification action
`StopConversation`	Cancels the active conversation

Voice Configuration

When conversation mode is enabled, voices are populated from the configured TTS deployment. Voices are grouped by language in dropdown menus and sorted alphabetically. Each SpeechVoice includes Id, Name, Language, Gender, and VoiceSampleUrl.

Conversation Mode Behavior

In conversation mode:

User clicks the headset button → persistent audio stream opens
Microphone, send button, and textarea are hidden/disabled
User speaks → audio streams to server via SignalR → STT transcribes → text appears as user message
Transcript is automatically sent to AI orchestrator → AI response text streams to message list AND audio streams back
User can interrupt by speaking → cancels current AI response → processes new prompt
User clicks headset again → ends conversation, restores normal UI