---
template: "page.peb"
title: "Web Chat Agents"
description: "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."
displayName: "Web Chat Agents"
category: "agents"
contentType: "reference"
audience: "developer"
tags: "agents"
section: "agents"
seoTitle: "Web Chat Agents"
seoDescription: "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."
---

## 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.