Skip to content

docs(chat_settings): document that agent responses are untrusted text #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
northdpole wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(chat_settings): document that agent responses are untrusted text #290

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/docs/reference/resources/chat_settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,27 @@ See the [Safety filters reference](./safety_filters.md) for the full schema, fie

Chat greeting, style prompt, and safety filters are validated as a set: if any one of `chat/configuration.yaml`'s `greeting` or `style_prompt` sections or `chat/safety_filters.yaml` is present locally, the other two must be present as well. `poly push` fails with a "Webchat config resources must all be present together" error if one is missing.

## Rendering agent responses

!!! warning "Agent responses are untrusted text"
Treat the agent's reply exactly as you would treat text typed by an end user.

Agent responses are generated by a language model. Anyone who can talk to the agent can influence what it says, including persuading it to produce HTML, JSON or XML. Any integration that renders a response into a markup context must encode it for that context.

Safety filters screen for harmful *content*. They are not an output encoder, and they do not make a response safe to insert into a page.

The platform does not strip or escape markup from responses, and this is deliberate: the correct encoding depends on where the string is finally rendered, and the platform has no way of knowing. Encode at the point of use.

| Where you render it | What to do |
| --- | --- |
| HTML element content | Sanitise against a tag allowlist, or entity-encode |
| HTML attribute value | Attribute-encode, quotes included — a helper written for element content is not sufficient here |
| URL, inline script, or CSS | Encode for that context specifically |
| Speech, SMS, plain text, logs | Nothing. The text is inert unless something parses it as markup |

The PolyAI web chat widget sanitises with DOMPurify against a tag allowlist, so embedding the widget gives you this for free. If you consume the Chat API directly, or render responses in a contact-centre platform or your own interface, the encoding is yours to do.


## Full example

~~~yaml
Expand Down
Loading