Building Chatbots
Flow-Like chat workflows can combine conversation history, retrieval, tools, and model responses. Design the bot as a controlled workflow: accept an event, assemble the allowed context, perform bounded work, return a response, and record enough information to evaluate the result.
Choose a chatbot pattern
Section titled “Choose a chatbot pattern”| Pattern | Best for | Main control |
|---|---|---|
| Prompted assistant | Drafting, explanation, simple Q&A | System instructions and model settings |
| Retrieval assistant | Answers grounded in a document collection | Search quality and citation policy |
| Tool-using agent | Looking up or changing external state | Tool permissions and confirmation |
| Guided conversation | Intake, troubleshooting, approvals | Explicit state and structured interactions |
| Notification bot | Proactive updates in a channel | Event filtering and delivery rules |
Start with the least autonomous pattern that completes the task. Add retrieval or tools only when the user need justifies the additional data and permissions.
Core chat workflow
Section titled “Core chat workflow”| Stage | Relevant nodes or design work |
|---|---|
| Receive | Chat Event |
| Build history | Make History, Push Message |
| Set instructions | Set System Message |
| Invoke | Invoke Model or an agent invocation |
| Return | Push Response |
| Stream | Push Chunk |
The system instructions should define the bot’s role, allowed sources, tool policy, refusal behavior, and response shape. Keep them versioned with the Flow so changes can be tied to evaluation results.
Conversation history
Section titled “Conversation history”Only include history that helps the current turn. Long, unbounded transcripts increase latency and can distract the model from current instructions.
Use one of these approaches:
- retain the most recent turns;
- summarize older turns into a compact memory record;
- preserve durable facts separately from conversational text;
- clear history when the task or user context changes;
- keep private session data scoped to the correct user or conversation.
History nodes include Set History N, Pop Message from History, and Clear History.
Ground responses with retrieval
Section titled “Ground responses with retrieval”Use retrieval when the bot must answer from a controlled corpus rather than general model knowledge.
- ingest documents and preserve source metadata;
- split content into retrieval-sized chunks;
- embed and store each chunk;
- embed the user’s query;
- retrieve relevant chunks;
- pass only the useful context to the model;
- return source references with the answer;
- decline or ask for clarification when retrieval is insufficient.
See Retrieval-Augmented Generation for the full indexing and query workflow.
Add tools
Section titled “Add tools”For multi-step or external operations, build an agent and register only the tools it needs.
| Need | Node |
|---|---|
| Build from a configured model | Agent from Model |
| Set agent instructions | Set Agent System Prompt |
| Register Flow-Like functions | Register Function Tools |
| Register MCP tools | Register MCP Tools |
| Invoke | Invoke Agent |
| Stream | Stream Invoke Agent |
Separate read tools from write tools. Ask for confirmation before destructive, costly, or externally visible actions. Validate tool arguments in the workflow even if the model produced them.
Stream useful progress
Section titled “Stream useful progress”Streaming improves perceived latency, but it should not expose raw internal reasoning or unvalidated tool output.
- stream user-facing response chunks with Push Chunk;
- use Push Step for named progress stages;
- use Push Stats for safe, structured status data;
- finish with a complete response or an explicit error state.
If the workflow fails after partial output, tell the user that the operation did not complete. Do not let a partial success message imply that a side effect happened.
Attachments
Section titled “Attachments”Chat events can work with attachments, and responses can include attachments from paths or signed URLs:
Validate type and size before processing uploads. Do not automatically pass every attachment to a model; select the minimum content needed for the task.
Structured interactions
Section titled “Structured interactions”Use interaction nodes when free-form text would make a task ambiguous:
| Interaction | Node |
|---|---|
| Form | Chat Form |
| One choice | Single Choice |
| Multiple choices | Multiple Choice |
Structured interactions are useful for approvals, configuration, and collecting required fields before a tool runs.
Channels
Section titled “Channels”The same conversational logic can be connected to the Flow-Like app chat surface or to supported provider-specific messaging nodes. Keep channel transport separate from the core response workflow:
- normalize incoming identity, message text, and attachments;
- call the shared bot workflow;
- adapt the result to the channel’s formatting and size limits;
- store channel-specific delivery identifiers outside the model prompt.
Search the node catalog for current provider coverage.
Safety and privacy
Section titled “Safety and privacy”- Treat retrieved documents, web content, and tool output as untrusted data rather than instructions.
- Restrict tools and credentials to the minimum required scope.
- Require confirmation for destructive or externally visible actions.
- Redact secrets and personal data from traces and error messages.
- Make uncertainty visible; do not invent a source or claim that a tool succeeded.
- Keep tenant, user, and conversation state isolated.
- Define retention for transcripts, uploaded files, and retrieved context.
Evaluate the bot
Section titled “Evaluate the bot”Maintain a representative test set for:
- common successful requests;
- ambiguous or incomplete requests;
- no-result retrieval queries;
- prompt-injection attempts in user and retrieved content;
- tool failures and timeouts;
- confirmation-required actions;
- long conversations and history truncation;
- attachment type and size limits.
Track answer correctness, source grounding, tool success, latency, cost, and escalation or refusal quality. Review traces by failure category instead of relying only on an average score.
Production checklist
Section titled “Production checklist”- System instructions and model settings are versioned
- History is bounded and scoped to the correct session
- Retrieval preserves source references
- Tool permissions are minimal
- Write actions have validation and confirmation
- Streaming has a clear completion and failure state
- Uploads are validated before processing
- Test cases cover failures and adversarial input
- Logs and traces redact sensitive data