Skip to main content
In this tutorial, you build a mortgage advisor chatbot β€” a Chat Driven conversational AI app that guides users through mortgage product selection. The app detects what the user wants, answers questions from a knowledge base, collects financial data across conversation turns, and generates personalized recommendations by letting an AI agent call a deterministic calculation workflow as a tool. What you will build:
  • A main Chat Driven workflow that uses an Intent Classification Agent to route messages
  • Built-in session memory that carries financial data across conversation turns
  • A knowledge base Q&A handler that answers mortgage questions from uploaded documents, using agentic search
  • A data collection handler that captures the user’s financial data from free-text messages
  • A personalized offer generator where a Custom Agent calls a workflow-as-tool for auditable calculations
  • A small talk responder and fallback handler
AI node types used: Intent Classification Agent, Custom Agent (with Knowledge Base, workflow tools, and Send as Chat Reply) Patterns demonstrated: Intent classification, Knowledge base RAG, Hybrid AI + business rules, Session state management

Architecture overview

The app is a Chat Driven workflow that uses an Intent Classification Agent to classify each user message and route it to the right handler. Each intent maps to a separate output branch on the node, eliminating the need for a Condition node. Each handler is a Custom Agent with Send as Chat Reply enabled, which delivers the response directly to the Chat component and updates session memory.
In Chat Driven workflows, responses are delivered to the user by Custom Agent nodes with Send as Chat Reply enabled, not by the End Flow node. The End Flow node has no body configuration.

Data model

In a Chat Driven workflow, the Start node provides Chat Session ID, User Message, and an optional UI Flow Context as dedicated input fields β€” you reference them as ${sessionId}, ${userMessage}, and ${context} in downstream nodes. These are not keys you declare in the data model.

mainChat data model

The mainChat workflow does not need any chat-specific keys in its data model β€” everything comes from the Start node fields and from the offer tool’s output.

mortgageOfferCalc data contract

The offer calculation workflow is exposed to the offer agent as a tool, so it declares an explicit input and output contract:
Built-in session memoryChat Driven workflows retrieve the last 30 turns of the conversation automatically and send them to the model in full. Any Custom Agent node with Use conversation memory enabled receives this history as LLM context, so data mentioned in earlier turns (age, income, loan amount) is available to later turns without manual persistence. See Session state management and Chat-driven workflows β€” Session memory.

Prerequisites

Before starting, make sure you have:
  • Access to a FlowX Designer workspace with AI Platform enabled
  • Familiarity with creating workflows in FlowX
  • A Knowledge Base data source with mortgage-related documents uploaded (see Step 4)

Step 1: Build the main orchestration workflow

Create a workflow named mainChat and select Chat Driven as the workflow type.
The workflow type cannot be changed after creation. Make sure you select Chat Driven β€” Output Focused workflows cannot be used from the Chat component.

Review the Start node

The Start node is created automatically with three fields:
  • Chat Session ID β€” a UUID populated by the Chat component at runtime (referenced as ${sessionId})
  • User Message β€” the user’s text message (referenced as ${userMessage})
  • UI Flow Context β€” optional JSON object passed from the UI (referenced as ${context})
No Start body configuration is needed in Chat Driven workflows.

Add the Intent Classification Agent

From the node palette, drag an Intent Classification Agent node onto the canvas and connect it to the Start node. Configure the node: User Message: ${userMessage} Intents: Response Key: intentResult The If No Intent Matches branch is a default output port that fires when the classifier can’t confidently match any intent. It’s always present on the node β€” you connect it to the fallback handler in Step 2.
Intent Classification Agent with four intents, the If No Intent Matches branch, and Include Reason for Selection enabled
Toggle Include Reason for Selection ON while tuning intent labels. When enabled, the agent returns a rationale explaining why it chose each intent β€” useful for diagnosing misclassifications. Turn it off once the intents are stable.
Each intent creates a separate output port on the node. When the agent classifies a message, the workflow continues along the matching branch β€” no Condition node needed. Leave Use conversation memory OFF so each message is classified on its own; turn it ON only if you want the classifier to resolve ambiguous follow-ups against prior turns.

Connect handler nodes to each branch

Add the following nodes and connect each to its corresponding intent output:

Add the End Flow node

Add an End Flow node from the palette (it is not auto-created for Chat Driven workflows) and connect every handler branch to it. The End Flow node has no body configuration β€” responses are already delivered by the Custom Agent nodes upstream.

Step 2: Build the inline handlers

Every handler in this tutorial is a Custom Agent placed directly in the mainChat workflow.
Shared Custom Agent settingsEvery Custom Agent in mainChat uses the same two defaults:
  • Use only referenced values as input: ON β€” keeps each call scoped to the values referenced with ${...} in the Context field and reduces token usage.
  • Include Task for Prompt Suggestions: OFF β€” turn ON only if you want AI-generated follow-up prompts shown in the Chat component.
Only the Use conversation memory and Send as Chat Reply toggles vary per handler, so those are called out on each node below.
Custom Agent node showing Instructions, Use conversation memory, and Send as Chat Reply

answerSmalltalk (Custom Agent)

Add a Custom Agent node named answerSmalltalk to the Greetings branch. Instructions:
Context:
The Instructions field is static β€” the node rejects ${...} references inside it with β€œThis field is static. Use Context for dynamic values.” Put dynamic values in the Context field, which accepts mixed text and ${...} keys. This split applies to every AI node in this tutorial.
Use conversation memory: ON β€” lets the agent tie small talk back to anything the user already shared. Send as Chat Reply: ON β€” sends the response to the Chat component as Markdown.

fallback (Custom Agent)

Add a Custom Agent node named fallback on the No Match branch. Instructions:
Context:
Use conversation memory: OFF β€” the fallback response is self-contained. Send as Chat Reply: ON.

Step 3: Build the data input handler

The Data Input branch is a single Custom Agent named handleDataInput. With built-in session memory, the agent both captures the financial data from the message and confirms it back β€” no separate extraction script is needed. Instructions:
Context:
Use conversation memory: ON β€” so captured values persist across turns and reach the offer agent later. Send as Chat Reply: ON.
If you need strictly deterministic extraction (for example, to write values to a database), add a Script node before this agent to parse the message, and have the agent confirm the script’s result. The single-agent version here is simpler and relies on session memory to carry values forward.

Step 4: Build the knowledge base Q&A handler

The KB question branch is a single Custom Agent node named knowledgeBaseQA, placed inline on the Intent 3 branch, with a Knowledge Base attached and Send as Chat Reply enabled.

Set up the Knowledge Base

1

Create a Knowledge Base data source

In the Integration Designer, add a new Knowledge Base data source. Name it something descriptive like MortgageKnowledgeBase.
2

Upload mortgage documents

Upload PDF documents covering product sheets (rates, terms, eligibility), FAQ documents (DTI, LTV), and regulatory guides (required documents, application process). Wait for automatic chunking and vector indexing to complete.
3

Test queries

Use the Knowledge Base test interface to verify that queries like β€œWhat is DTI?” and β€œWhat documents do I need?” return relevant chunks.
For detailed Knowledge Base setup, see the Knowledge Base integration documentation.

Configure the Custom Agent node

Add a Custom Agent node named knowledgeBaseQA on the Intent 3 branch. Enable the Knowledge Base setting and select your MortgageKnowledgeBase data source. Turn on Enable agentic knowledge base search. Instead of a single lookup, the agent issues several sub-queries per turn and merges the results, which improves recall on multi-part questions. Under Additional controls, keep Filtering options on Manual unless you want the model to write its own metadata filter at run time. SaaS Β·
Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
Retrieval parameters:
Knowledge Base Q&A agent with agentic knowledge base search enabled and Manual/Agentic filtering
Under Hybrid search the Min Relevance Score slider does not filter results β€” a hybrid score is a rank, not a similarity. To gate strictly on relevance, use Semantic search, or bound retrieval with Number of Chunks and re-rank.
Instructions:
Context:
Use conversation memory: ON β€” so the agent can resolve follow-ups like β€œwhat about the second one?” against the previous answer. Send as Chat Reply: ON.
Without explicit grounding rules in the prompt, the LLM may fall back to its general training data and produce inaccurate mortgage information. Always include the β€œONLY from knowledge base” instruction.
For more details on this pattern, see Knowledge base RAG.

Step 5: Build the personalized offer handler

SaaS Β·
Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
This handler implements the Hybrid AI + business rules pattern. In 5.11 you build it as a single Custom Agent that calls a deterministic calculation workflow as a tool: the agent handles the natural-language work (extract the client’s numbers, present the result), while the tool handles the auditable math. This replaces the older pattern of an Output Focused subworkflow followed by a separate terminal agent.

Step 5a: Build the mortgageOfferCalc workflow

Create a workflow named mortgageOfferCalc with Output Focused as the workflow type. Give it an input and output contract so it can be exposed as a tool:
  • Input parameters: age, income, loanAmount, loanDuration (all NUMBER)
  • Output parameter: reportText (STRING)
The output contract is a promise the workflow has to keep. A node writes its result under its own Response Key, and only the parameters declared in the output contract are returned to the caller β€” so if the two do not line up, the workflow returns SUCCESS with every field null and the agent has no way to tell that apart from a genuinely empty result.The Script node below writes to reportText, which is the declared output parameter, so nothing extra is needed. An AI node is the case to watch: its Response Key holds a result object, so add a Script node after it that copies the values into the declared output parameters.
mortgageOfferCalc data model with age, income, loanAmount, loanDuration inputs and reportText output
Add a single Script node (JavaScript) between Start and End Flow. It computes the monthly payment, debt-to-income ratio, and maximum eligible loan, scores the products, and writes the recommendation to reportText.
mortgageOfferCalc workflow: Start, calc-and-rank Script, End Flow returning reportText
Keeping the numbers in a Script node rather than an LLM keeps them deterministic and auditable. For any recommendation, you can trace exactly which formula produced each figure.

Step 5b: Attach the workflow as a tool on the offer agent

Switch back to mainChat. On the Offer branch, add a Custom Agent node named answerPersonalisedOffer. Under Tools, click Add tool and select mortgageOfferCalc.
Offer Custom Agent with the mortgageOfferCalc workflow attached as a callable tool
Instructions:
Context:
Use conversation memory: ON β€” so the agent can reuse age, income, loan amount, and duration shared in earlier turns. Send as Chat Reply: ON. Connect this Custom Agent to the End Flow node on mainChat.
A workflow can be exposed as a tool only if it declares an input and output contract (Step 5a). When you write the tool description, name the arguments it needs and add a stop condition. An agent node is capped at 10 workflow-tool calls per run β€” past the cap the call is not dispatched and the agent is told to answer with what it already has, so the prompt is still what stops a model from re-calling a tool that already succeeded.

Step 6: Connect to the chat UI

1

Create a Chat-Driven UI Flow

Go to UI Flows and create a new UI Flow, selecting Chat-Driven as the experience type. Set mainChat in the AI Conversational Workflow field.
2

Add a Chat component

Add a Chat component to the page. In a Chat-Driven UI Flow it uses mainChat by default β€” no per-component configuration needed.
3

Test the chat

Click Run to preview the UI Flow and interact with the chatbot.
Chat-Driven UI Flow with the Chat component bound to the mainChat conversational workflow
For details on configuring chat experiences with built-in session memory, see Chat-driven workflows. For the Chat component reference, see Chat component.

Testing

1

Test the mainChat workflow directly

Open mainChat and click Run Workflow. In the test modal, provide a valid UUID for Chat Session ID (reuse the same one across runs to verify multi-turn memory) and a User Message.
The Chat Session ID must be a valid UUID. A plain string like test-session-1 causes a runtime error: Invalid UUID string.
2

Test the full chat flow

Run the UI Flow that embeds the Chat component. With built-in session memory, financial details captured in earlier turns are available to later turns:
Mortgage advisor chat returning a recommendation report with payment, DTI, max loan, and ranked products
3

Test edge cases


What you learned

In this tutorial, you built a full-featured Chat Driven app that demonstrates:
  • Chat Driven workflow basics β€” dedicated Start node fields, ${userMessage} interpolation, simplified End Flow (guide)
  • Built-in session memory β€” multi-turn context without manually persisting conversation history
  • Intent classification and routing β€” using an Intent Classification Agent to route messages to handler branches automatically (pattern)
  • Agentic knowledge base search β€” grounding answers in uploaded documents with multi-query retrieval and re-rank (pattern)
  • Workflow-as-tool β€” letting a Custom Agent call a deterministic calculation workflow for auditable, hybrid AI + business-rule recommendations (pattern)

Next steps

Chat-driven workflows

Full reference for Chat Driven workflows, AI Triggers, and session memory

AI patterns

Deep-dive into the patterns used in this tutorial

Node types reference

Detailed configuration reference for all AI node types

Knowledge Base integration

Create and manage Knowledge Bases for RAG
Last modified on August 14, 2026