01What 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. An intent is a kind of request you want to catch, such as "where is my order". When a message matches one, the agent 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. The block has no plain "next" output: only intents, No Match and Frustration lead to other blocks.

02Pick a mode
Click the block and the editor opens on the left. Under the block 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.
03Build 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 in the left menu (the page is titled AI Settings). Scroll to Knowledge bases and press New knowledge base. Then fill it three ways:
- Upload document — TXT, Markdown, JSON, CSV, TSV, XML, YAML, PDF, DOC, DOCX, XLS 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.
- Import from website — paste your website address and FlowCastle reads the pages itself, one document per page. Usually the fastest way to fill a base, because the answers are already written on your site. Turn Your Website Into a Knowledge Base walks through it.
A new document is not searchable the moment it finishes uploading. FlowCastle first reads it and prepares it for search. While that runs you see the current stage. When it stops you see one of four statuses — Queued, Processing, Ready, Failed — and, next to the file name, how many pieces the document was split into. The four counters above the table (Documents, Ready, Processing, Failed) are the quick version. Only Ready documents are searched.
Edited a document? Reindex prepares that one file again. Reindex all does it for the whole base.

04Attach 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, is the standing instruction the model reads before every answer: who it is and how it should reply. 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. Each option shows its price compared with the standard AI price: Auto shows 0.50x, which means half price. Web search underneath lets supported models look things up online; it stays greyed out on models that cannot.
When the credits run low, and again when they run out, FlowCastle emails the account owner and messages them on Telegram if it is linked. With no credits left, this step answers "The assistant is temporarily unavailable. Please try again later." instead of staying silent, and replies normally again once you add credits. Only AI steps pause: commands, posting and every other block keep working. The AI settings page shows when the balance resets and, once a day of use has passed, how long it will last at the current pace.
On the canvas the block carries a Uses AI credits chip, and in a group flow whose trigger listens to every message it adds Every group message → AI: each member message then reaches this step and spends credits. To answer only when people call the bot, open the trigger and set Group message scope to Mentions, replies, and commands; other messages then cost nothing. When the AI builder makes a group bot for you, it asks which of the two you want.
Thinking, right under the model, sets how long the AI thinks before it answers. Auto is right for chat and is the same as Low. Pick Medium or High for harder work (math, code, planning): answers get better but slower, and each reply costs more (Medium 1.5×, High 2.5× the model's credits). None answers fastest at half the credits. Only models that think use it (GPT-5 and later, Claude Sonnet/Opus 5); other models ignore it and cost the same. With Take the model from a variable on, the level can come from a variable too, so a model menu in your bot can offer a "think harder" choice.
Files the user sends. With Read documents on, the agent reads PDF, Word, Excel, TXT and CSV files and keeps them for that person, with no time limit and no limit on how many. On every reply it sees the list of all of them with their names: the newest are read in full, and it opens the others when a question needs them, so a user can send twelve monthly reports and ask for a year summary later. Up to 10 files are read from one message. A very long file is kept up to its first 200,000 characters, and the agent says so when an answer needs the rest. Scanned PDFs without text cannot be read.
Long conversations. The agent reads the newest messages of a conversation word for word (up to 40). It does not forget the older ones: once a conversation is longer, it keeps a short summary of the earlier part (topic, agreements, numbers, open questions), and when a question needs exact words from earlier it searches the conversation and reads that part before answering. The summary is written in the background and costs you nothing; a reply that has to search costs one more model call. Message texts are kept for 90 days, so a search reaches back 90 days; the summary keeps the gist after that.
Long replies to read cost more. A reply's price covers up to about 32,000 tokens the AI reads (a token is a piece of a word; 32,000 tokens are roughly 100,000 characters: your prompt, the recent conversation and the files in view). Each further 32,000 tokens, or part of them, adds the price once more. Almost every chat message fits in the first 32,000. A chat where the user sent many large files can cost two or three times the price per reply, because the AI reads those files again for each reply.

05Tell it who it is talking to
The agent can know facts about each person it talks to — their plan, when it expires, how many devices they use — without asking. Expand What the AI knows about the contact in the Settings tab and click Add a fact. Pick a variable (an application, bot or contact variable) or a profile field such as First Name or Language, and give it a short label like "Plan". The label starts as the variable's name; change it to what the value means.
On every message the agent gets each value for the person who is writing, under its label. It treats them as true, uses them when they matter ("your Pro plan includes 5 devices") and does not read the list back. Empty values are skipped, so you can add a fact before your flow fills it in. Up to 20 facts; a value longer than 500 characters is cut.
Secret variables are not offered, and a block that uses one — in a fact, in the prompt or in an intent description — cannot be saved: everything the agent reads goes to the AI model provider. Values that exist only while a flow runs (an action's output, the current message, the chat id) have no value here either. Save such a value into a contact variable first and add that variable as a fact.
06Intents 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 conversation in Live Chat so someone on your team can reply. Until they write, the AI assistant keeps answering, so the person can keep asking while they wait.

07When 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 Frustration Detection. It notices when a person is getting upset and reacts before they give up.
- Turn the switch on.
- Set Frustration threshold (0.7 by default). Lower reacts sooner. Higher reacts only when the person is clearly angry. Asking for a human counts as very upset.
- Pick When frustration detected: Stop processing, Send a fallback message (you write a calming message), or Hand off to another block.
- If you chose the hand-off, the block gets a Frustration output. Connect it to your "talk to a person" block.
08Test 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.

09Let it learn from real conversations
Once the bot has handled real chats, open Pulse → AI health. It opens on To fix: each problem with the messages behind it and one button that fixes it right there, without going to the canvas.
- Add answer for a question the agent could not answer. When someone on your team already answered it in live chat, that reply is filled in; otherwise you write it. You pick the knowledge base that keeps it.
- Add intent when people keep asking for something you never routed: name, description and the step or flow it leads to.
- Apply description when the AI picks an intent wrongly, with the old and the new wording side by side. Disable for an intent nobody uses.
- Settings that lose people, such as a no-match reply that sends nothing, or an agent that answers with no knowledge base (Connect a knowledge base).
- Single messages to look at: no answer, answered without knowledge, the answer did not help, asked again, a tool failed. Each one has its own buttons, such as Add answer, Add to intent… and Not a question.
An answer added to a knowledge base the agent already reads works as soon as the document is read. New or changed intents and a newly connected knowledge base are saved in the editor and go live when you deploy; the page says so and has a Deploy button. Next to the tabs of the agent editor, a small counter shows how many fixes are waiting and opens that list.
10Agent, 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: Everything Your Bot Can Do 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.
11Start 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: Stars and Card Providers is the other half of the same conversation.
12Next up
Back to the main path — the outside services your bot can plug into: Modules: Connect Sheets, AI, Payments and More.
