Chat & Conversations
Flow-Like chat boards begin with a Chat Event and return responses through chat callback nodes. The event supplies the current conversation and session context; the workflow decides which model, tools, retrieval, and response behavior to apply.
Chat event contract
Section titled “Chat event contract”Chat Event starts the board and exposes:
| Output | Purpose |
|---|---|
| History | Current model-compatible chat history |
| Local Session | State scoped to this chat |
| Global Session | State scoped to the user |
| Tools | Tools requested through the chat surface |
| Actions | User actions from prior interactive content |
| Attachments | Uploaded files or references |
| User | Current user information |
Read only the outputs the workflow needs. Treat user text, attachments, and restored session values as untrusted input.
Minimal model response
Section titled “Minimal model response”A basic model-backed chat board:
- receives History from Chat Event;
- applies the system instruction;
- invokes a configured model;
- pushes the resulting response to the chat.
| Stage | Node |
|---|---|
| Set role and rules | Set System Message |
| Invoke configured model | Invoke Model |
| Return complete response | Push Response |
The system message should state the role, source policy, tool policy, refusal behavior, and expected response shape. Do not include credentials or private operational data.
Work with history
Section titled “Work with history”The event’s History output already contains the conversation supplied by the chat surface. History nodes let the workflow modify a copy before invocation:
| Need | Node |
|---|---|
| Create an empty history | Make History |
| Add a message | Push Message |
| Build from messages | From Messages |
| Limit retained messages | Set History N |
| Remove the latest message | Pop Message from History |
| Clear history | Clear History |
Keep enough history for the task, but avoid unbounded transcripts. Store durable application facts in typed app or workflow state rather than relying on old conversational text.
Configure model behavior
Section titled “Configure model behavior”History configuration nodes expose settings such as:
- Set Max Tokens;
- Set History Temperature;
- Set History Top P;
- Set Stop Words;
- Set Seed;
- Set Response Format;
- Set Stream.
Provider support varies. A setting present in the workflow does not guarantee that every provider or model implements it identically.
Stream responses
Section titled “Stream responses”Enable streaming on the history or invocation path supported by the configured model, then pass each model response chunk to Push Chunk.
Use Push Response when:
- the model returns one complete response;
- the workflow must validate or redact the full result before display;
- the response is short enough that progressive delivery adds little value.
Use Push Chunk when:
- the model provides response chunks;
- the user benefits from lower perceived latency;
- the workflow can still report a final completion or failure state.
Do not stream raw internal reasoning. Stream user-facing answer content and named progress states.
Show progress and metadata
Section titled “Show progress and metadata”The chat callback nodes include:
| Need | Node |
|---|---|
| Add a named progress step | Push Step |
| Update text for a step | Push Text to Step |
| Remove a step | Remove Step |
| Push one statistic | Push Stat |
| Push several statistics | Push Stats |
Progress should describe observable work such as “Searching documents” or “Validating order,” not hidden chain-of-thought.
Session state
Section titled “Session state”Push Local Session updates state local to the conversation. Push Global Session updates user-level state.
Use local session state for turn-specific workflow context and global session state only for durable user preferences or facts that legitimately cross conversations. Define retention, schema, and deletion behavior for both.
Never trust a restored session field as authorization. Re-check permission at the operation boundary.
Attachments
Section titled “Attachments”Extract Attachments retrieves attachments from model history. Response attachments can be created:
- From Path;
- From Signed URL;
- and returned with Push Attachment or Push Attachments.
Before processing an upload:
- validate file type and size;
- inspect or scan content according to the app’s threat model;
- keep the original source reference;
- send only the necessary content to a model;
- avoid exposing filesystem paths in the response.
Structured interactions
Section titled “Structured interactions”Use a structured interaction when required input should not be guessed from free text:
| Interaction | Node |
|---|---|
| Form | Chat Form |
| One option | Single Choice |
| Several options | Multiple Choice |
Structured interactions are useful for configuration, approvals, and collecting missing fields before a tool call.
Add retrieval or tools
Section titled “Add retrieval or tools”- Use RAG and knowledge bases when answers must be grounded in a controlled document corpus.
- Use AI agents when the assistant must choose among bounded tools.
- Keep ordinary deterministic checks in the board even when a model or agent is involved.
Error handling
Section titled “Error handling”Every chat path should finish in one of three visible states:
- complete response;
- request for missing information;
- explicit failure or inability to answer.
If a tool or side effect fails, do not let an earlier streamed sentence imply success. Redact secrets and sensitive payloads from errors, and preserve a safe run identifier for support.
Production checklist
Section titled “Production checklist”- Chat Event outputs are treated as untrusted input
- System instructions and model configuration are versioned
- History is bounded
- Session state has scope and retention rules
- Streaming has explicit completion and failure
- Attachments are validated before processing
- Structured interactions collect required fields
- Retrieval and tools enforce access outside the prompt
- Logs and errors redact sensitive data