Guide
- 1
What the AI Chat Agent block is
Most blocks do one thing and move on. This one stays. Drop an AI Chat Agent block on the canvas and it reads what the person types, answers in its own words, and keeps listening until the conversation ends.
Two things make the answers worth reading. A knowledge base — documents you upload — gives it facts instead of guesses. Intents give it exits: when the question is really a task, it hands the conversation to a normal block on the canvas.
Add it from the + button on the canvas. On the node you will see one row per intent, plus small tags for the attached knowledge base and the mode. Each of those rows is a real output you can wire somewhere.
- 2
Pick a mode
Click the block and the editor opens on the right. Under the node name sits Agent mode, and it decides what the rest of the editor shows:
- Chat Only — the agent only answers. No branches, no routing.
- Intents + Chat — it answers, and routes when the message matches one of your intents. This is what most support bots want.
- Intents Only — no answers at all. It only decides which intent fits and sends the person down that path. The Knowledge section disappears, because nothing is written.
- 3
Build the knowledge base first
Documents do not live in the block. They live in the workspace, so several blocks and several flows can share them.
Open Settings → AI Settings. Scroll to Knowledge bases and press New knowledge base. Then fill it two ways:
- Upload document — TXT, Markdown, JSON, CSV, TSV, XML, YAML, PDF, DOC, DOCX and XLSX. The accepted list is printed above the buttons, so you never have to guess.
- Create document — type or paste the text in the browser. Good for a FAQ that only exists in someone's head.
Nothing is searchable the moment it finishes uploading. Each document is extracted, split into chunks, embedded and indexed. While that runs you see the stage; when it stops you see one of four statuses — Queued, Processing, Ready, Failed — with the chunk count next to the file name. The four counters above the table (Documents, Ready, Processing, Failed) are the quick version. Only Ready documents are searched.
Edited a document? Reindex re-runs that one file. Reindex all re-runs the whole base.
- 4
Attach it and choose a model
Back in the flow, open the block and go to the Settings tab.
Expand Knowledge. Knowledge bases is a multi-select — pick one or several. What you pick here is what the agent searches on every single turn.
Two fields above it matter just as much.
System prompt, under System Prompt, sets the personality and the rules. You get three choices: Inherit application prompt uses the workspace-wide prompt from that same AI Settings page, Extend application prompt keeps it and appends your instructions, Override prompt replaces it entirely. This is where you write the sentence that keeps the bot honest: answer only from the knowledge base, and say so when the answer is not there.
AI model, under AI Models, sits next to a Balance: 82/100 credits notice. Leave it on Auto unless you have a reason not to. The multiplier printed on every option is what a turn costs — Auto shows
0.50x, because this block bills at half of AI Assistant pricing, with intent recognition and answer generation charged separately. Web search underneath lets supported models look things up online; it stays greyed out on models that cannot.
- 5
Intents send the conversation somewhere else
Switch to the Intents tab. Every intent is a card: an on/off switch, a name, a description.
The description is the whole trick. Nobody sees it — it is what the model reads to decide whether this intent fits. Write it as a sentence about the person, not about your bot: "The customer asks where an order is, or asks about delivery status of an order they already placed."
Each card has two checkboxes. Show as quick reply turns the intent name into a tappable suggestion. Continue AI agent session after completion sends the person back to the agent after the branch has run, instead of dropping them out of the conversation.
Add Intent creates an empty card. The button under it opens a drawer of ready-made examples grouped by business type, so you can start from "Track order" or "Talk to an operator" instead of a blank field.
Nothing routes until you wire it. Every enabled intent grows its own output on the node, labelled with the intent name — drag it to any block. A "talk to a person" intent usually points at an Action block holding the Start Conversation action, which opens a Live Chat conversation for your team.
- 6
When nothing matches
Open the Fallback section. When no intent matches has three answers:
- Stop processing — the agent goes quiet and the flow ends.
- Send a fallback message — one message you write, then stop.
- Hand off to another block — the node grows an extra No Match output. Connect it wherever unanswered questions should land, usually the same handoff block your "talk to a person" intent uses.
Below it is a Frustration Detection section. The editor labels it as under development and tells you what to do instead: write an intent that describes an unhappy customer and route that intent to a human.
- 7
Test the answer
Press Test above the canvas and use the Chat tab. Ask the question your documents answer and read what comes back. If the reply is vague, the fix is almost always the document, not the prompt — the agent can only be as specific as what it was given.
- 8
Let it learn from real conversations
The third tab is Suggestions. Once the bot has handled real chats, Analyze conversations reads back through them. Choose the source — Agent history (unmatched messages) or Live chat conversation history — pick a window, and press Run analysis.
What comes back is grouped into four kinds: New intent (people keep asking something you never routed), Improve intent, Unused intent and Knowledge gap (a question your documents do not answer). Each suggestion shows how many of the analysed messages it covers, plus the real sentences behind it. Accept turns a suggested intent into a real one; Add to knowledge base writes a question-and-answer pair straight into a base, and it warns you first if an existing base already covers it.
- 9
Agent, AI Action, or the OpenAI module?
Three things in FlowCastle call a model. They are not interchangeable.
The AI Chat Agent block is a conversation: it waits for replies, remembers the turn before, searches your documents and can route. Reach for it when the person is going to ask more than one thing.
The AI Action is a single shot inside an Action block — one prompt, one result, stored in a variable, no memory and no routing. Use it to summarise a message or classify an answer mid-flow. The Action Node covers where it lives.
The OpenAI module adds an Ask ChatGPT action that runs on your own OpenAI key. Also one shot, no knowledge base, no intents — the reason to install it is that you want to bring your own key.
- 10
Start from a template
Two ready flows use this block, and both install in one click:
- AI FAQ Assistant + Human Handoff — a support bot that answers order, delivery and return questions from a knowledge base and passes the hard ones to a person.
- Website Chat Assistant (EN/RU) — the bilingual assistant that runs in the chat widget on flowcastle.ai. Pair it with Embed Web Chat on Your Site.
If your bot also sells, Accept Payments in Telegram is the other half of the same conversation.
- 11
Next up
Back to the main path — the outside services your bot can plug into: Modules: Connect Sheets, AI, Payments and More.