Web Chat Agents

Web Chat Agents

Overview

This document describes the two supported paths that invoke POSTAIResponse, the current gap for web chat instructions, and the refactor plan to align web chat with the Salesforce Apex path while enforcing strict security rules.

Invocation Paths

Salesforce managed package path

1. ../sfdc/src/classes/AIAssistantController.cls builds systemMessage via AIModel.getSystemPrompt(RunContext.Chat) and sends the request through ../sfdc/src/classes/AIDialogueAction.cls.
2. ../sfdc/src/classes/AIDialogueAction.cls posts to /orgs/{orgId}/ai/response via ../sfdc/src/classes/API.cls.
3. src/main/java/api/routes/APIRoutes.java routes /orgs/{orgid}/ai/response to src/main/java/api/ai/openai/responses/POSTAIResponse.java.
4. The Apex system prompt includes <include type="skill" ... /> tags, plus prompts, record context, knowledge, and memory sections as defined in ../sfdc/src/classes/AIModel.cls.

Public web chat path

1. knowledge/public/presentation/page.peb embeds a JS widget that posts a minimal AIChatRequest to https://api.idialogue.app/v1/chat.
2. src/main/java/api/routes/web/WebAPIRoutes.java routes /v1/chat to src/main/java/api/routes/web/POSTWebChat.java.
3. POSTWebChat sets isWebChat=true, loads the published agent, and forwards the request to POSTAIResponse.

Verified Handler Behavior

1. POSTAIResponse only uses systemMessage for initial requests; subsequent turns reuse Dialogue.instructions.
2. When a systemAgent is present, POSTAIResponse replaces the system agent placeholder with AIAgent.getSystemPrompt(...) and continues.
3. When systemMessage is present on an initial request, DialogueScriptProcessor expands tool include tags into tool definitions and AIAgent.applyToolDefinitions(...) attaches the tools.

Web Chat Security Rule

Web chat must never accept client-provided instructions.

1. Any systemMessage from a web chat payload is ignored.
2. The initial web chat systemMessage is always derived from the retrieved agent via AIAgent.getSystemPrompt(...).
3. The systemAgent branch remains a separate request path and is not modified by this change.

How Tool Descriptions Are Injected For Web Chat

1. AIAgent.getSystemPrompt(...) appends <include type="skill" primitive="..." /> tags for each skill on the agent.
2. POSTAIResponse runs DialogueScriptProcessor on the initial request when systemMessage is non-blank.
3. DialogueScriptProcessor resolves those include tags into tool definitions and AIAgent.applyToolDefinitions(...) registers them for the Response API call.

Refactor Plan (TDD First)

1. Add tests that prove web chat clears client systemMessage and replaces it with AIAgent.getSystemPrompt(...) for initial requests.
2. Add tests that the web chat flow does not override system agent requests.
3. Implement POSTAIResponse logic to enforce the web chat security rule before parsing dialogue scripts.
4. Keep systemAgent behavior unchanged.

Alignment Notes (Apex vs Java)

AIAgent.buildSystemPrompt() is not yet feature-parity with the Apex AIModel.getSystemPrompt(...).

1. Apex includes flow outputs, inline knowledge, memory blocks, and record context sections.
2. Java AIAgent.buildSystemPrompt() currently includes the base systemPrompt, system AIPrompt blocks, and <include type="skill" ... /> tags.
3. To fully align, extend the Java prompt builder to incorporate knowledge, memory, and record/file context as a separate, incremental follow-on change.