AI Agent Node
A customer named Priya asks Acme Diagnostics, "Is my blood test ready, and how much do I owe?" One node reads that message, looks up her record, grounds the answer in your price list, and writes back — in a couple of seconds. That node is the AI Agent, and this page covers everything you can set on it.
It's for Asha, the admin who builds agents. The AI Agent owns the conversation: it decides which tools to call, grounds its answers in your data, and replies. Its identity, model, tools, knowledge and your team attach to it as parts wired to its ports.

The AI Agent and its parts
Go to Build → Agents, open an agent, and add an AI Agent from the Core category (or open the one Build with AI or a template created). A working agent needs:
- one AI Agent,
- a Personality (required, exactly one), and
- an AI Model (required, exactly one).
Everything else is optional: Integrations (your MCP servers as tools), Knowledge (Knowledge Base folders), Actions (senders, HTTP, databases, documents…), an Operator for your team (who answers, the hand-off to a person, supervision), and Steps for a scripted sub-flow.
The ports
Seven colour-coded ports run along the bottom of the AI Agent card, left to right:
| Port | Required? | How many | What you attach |
|---|---|---|---|
| Personality | Required (red asterisk) | Exactly one | Personality — who the agent is and how it behaves |
| AI Model | Required (red asterisk) | Exactly one | AI Model — which models it uses for chat, voice, documents and images |
| Integration | Optional | One or more | Integrations — your MCP servers; their actions become the agent's tools |
| Knowledge | Optional | One or more | Knowledge — Knowledge Base folders the agent answers from |
| Action | Optional | One or more | Action tools — Email / SMS / WhatsApp Sender, Chat Sender (Telegram and other messaging apps), Phone Caller, HTTP Request, Google Sheets, Postgres / MySQL / MongoDB, document extraction, Upload Document — or an Action that runs another agent |
| Operator | Optional | At most one | Operator — your people on this agent: who answers, the hand-off to a person or another agent, supervision and the copilot. The agent can hand off only when this node sets up a hand-off |
| Steps | Optional | One sub-flow | A Steps sub-flow — Ask agent, Tool, Condition, Human Handoff, Render View and Collect Info steps the agent follows in order |
Each port's + is also its drag handle: click it to open a picker filtered to that port (Add Personality, Add Action, Add a step…), drag it to an existing node to connect it, or drag it to empty canvas to add and connect a new node at once. A one-of-a-kind port that's already filled doesn't offer a second +.
The card also has a flow input on its left edge (where triggers connect — hover it for What triggers this? to add another trigger) and a flow output on its right edge (What happens next?).
Personality and AI Model in brief
- Personality holds the agent's name, role, tone and language, its greeting, and the system prompt — the single place you write how the agent behaves. See Personality.
- AI Model has one section per job: Chat agent model (model, creativity, max reply length, thinking level), Voice agent model (Live — one speech-to-speech model — or Pipeline — speech-to-text → model → text-to-speech — plus the voice), While the caller waits (what a caller hears during lookups and holds), Document extraction model, and Image / vision model. Each defaults to the platform default, so an agent works without touching it. See AI Model.
The AI Agent's own settings
Double-click the AI Agent to open its properties modal. The Config tab has five collapsible sections, top to bottom: Performance, Knowledge & Grounding, Advanced, Safety and Memory. Every setting has a sensible default.
Performance — Speed vs accuracy
A one-click starting point that fills in several settings below:
| Preset | What it sets |
|---|---|
| Fastest | Knowledge is looked up on demand instead of before every reply, at most 6 steps per turn, and the memory features that run every turn (searching earlier messages, key facts, learning over time) are switched off. Best for high-volume chat with simple questions. |
| Balanced (default) | What every agent does unless you change it: knowledge attached to every reply (12 passages), up to 20 steps per turn, full memory, and fact-checking as set in Compliance. |
| Most accurate | Attaches more of your knowledge base to every reply (20 passages) and turns fact-checking on for this agent. Noticeably slower, and roughly doubles the cost per reply. |
Change any of those settings afterwards and the preset reads Custom. Reasoning effort and retrieval quality aren't part of the presets — they live on the AI Model and Knowledge panels.
Knowledge & Grounding
This section controls what the agent may answer from, on top of your business data (your Knowledge Base, your integrations' tools, and the persona). An amber note at the top summarises the order: Business Data › Web Search › General Knowledge.
| Control | Default | Effect |
|---|---|---|
| Allow general (LLM) knowledge | On | When your business data doesn't cover a question, the agent may answer from the model's own knowledge. Off = strict "closed book" — the agent answers only from your data and says so when it can't. |
| Allow web search | Off | Lets the agent search the live web for current or external facts (competitors, news, pricing) and cite its sources. |
| Source priority | Knowledge Base › Web search › LLM knowledge | Drag (or use the arrows) to change how general and external questions are resolved. A disabled source shows OFF — SKIPPED. |
| Knowledge lookup | Always attach | Always attach searches the knowledge base before every reply and adds the best passages to the prompt — most reliable, but it costs a search and several thousand tokens every turn, even on "hi". On demand lets the agent search only when it decides it needs to — faster and cheaper on turns that need no knowledge. |
| Passages to attach | 12 | (Always attach only) How many passages go with each reply. More means better recall and a bigger prompt. |
| Only attach when relevance is at least | 0 (always) | (Always attach only) A relevance threshold, so a greeting doesn't pull in passages that don't match. Below it, nothing is attached — the agent can still search. |
Business facts always win
Your own prices, policies and records always come from your business data, whatever the source order. The order only decides general and external questions.
Advanced

Information to collect. A list of structured details the agent must gather during the conversation — click + Add Variable for each. Every field has a name, a type (text, number, yes/no, date, a fixed list of choices (enum), phone, email, PAN or Aadhaar), whether it's required, how the agent should ask for it, and an optional validation pattern. Anything already known about the customer counts as collected, so the agent never re-asks. For step-by-step collection with a read-back confirmation, use the separate Collect Info node.
Stage gate. A fixed, multi-stage flow the agent must follow in order — for example log in → verify → book — where each stage sees only its own tools and instructions until it moves on. Open the Stage Flow Builder and either Describe your flow in plain English (the AI drafts the stages for you), start from a template, or start blank. Then refine each step:
- What the step does — collect answers (the customer picks from choices, types a value, or it's looked up with one of your tools), or let the assistant handle the step itself until a signal says it's done.
- Final step — marks the step that performs the final action (for example, making the booking) through a tool you choose; it runs exactly once. Steps can also be marked repeatable or optional.
- Tools the assistant may use in this step — All tools (not restricted) by default, or Only these tools. A restricted step reads back as "🔒 only: …". Tools the gate runs itself are shown as "(fired by the gate)" and can't be picked.
- Instructions for this step (optional) — extra guidance the agent follows only while that step is current.
The Stage gate needs an Integration on the agent so its steps can use your tools. A ⚙ Raw editor is there for fine control.
Per-stage tools on voice calls
If an agent limits tools per stage and its voice model runs on OpenAI Realtime, every tool stays visible in every stage on a call (text chats are still limited). Activate shows a warning. Use a Gemini Live or Pipeline voice model to enforce the limit on calls too.
Max steps per turn (default 20, up to 50). How many actions — tool calls, lookups, sends — the agent may take before it must reply. It's a ceiling, not a target: simple agents reply well within it. If an agent ever hits it, it stops calling tools and answers with what it has.
Rich replies. Which visual formats the agent may use — tables, charts, cards, pickers:
- All formats (default) — every format is available;
- Text only — plain-text answers;
- Choose — tick the specific formats you want.
Each format the agent can use is described to the model on every step, so switching off the ones you don't need makes replies start sooner and cost less.
Once the agent has been answering customers, a note under the picker shows how often it actually used a visual format — for example "Last 30 days: a visual format in 12 of 4,210 replies (0.3%)" — and, with All formats selected, roughly how many tokens the formats add to every model step. If fewer than 2% of at least 30 replies used one, the note turns amber and offers Switch to text only.
Built-in capabilities. Six extra abilities, each switched on per channel (WhatsApp, Phone, Web, SMS, Email, Mobile, and each messaging app: Telegram, Slack, Messenger, Instagram, Teams, Discord, Google Chat, RCS):
| Capability | Default | What it does |
|---|---|---|
| Create a PDF | Off | Builds a PDF and gives the customer a link — useful on chat and email, pointless on a phone call. |
| Create a spreadsheet | Off | Builds a spreadsheet of data and gives the customer a link. |
| Write a report | Off | Writes a longer structured document with headings. |
| Search past conversations | Off | Looks up exactly what was said in this customer's earlier conversations — an order number, a date, a promise — and reads the original messages back. Only ever this customer's own history. |
| Schedule a follow-up | Off | When a customer asks to be contacted later ("message me Friday at 4"), the agent schedules it on the channel the customer is using. |
| Hand off to a human | Allowed on every channel | Says on which channels a hand-off may be offered. The hand-off itself exists only when the agent's Operator node sets one up. |
The link at the top-right of each card switches that capability on for All channels or Off everywhere in one click. Leave off anything the agent won't use — each one costs a little on every step.
Search past conversations complements the Memory setting Search earlier messages, which finds messages that are similar in meaning but is poor at exact facts like "order 4417". This one searches for the exact words and returns up to 10 matching messages, newest first, each with its date, channel and who said it (the customer, the agent or one of your people). Whose history is searched is decided by Perfox from the conversation, never by the AI: by default it's the customer's history with all your agents, and with Keep this agent's memory separate only their conversations with this agent. Runs with no real customer — webhook and scheduled runs — have no history to search.
Schedule a follow-up gives the agent the ability to book a later message and to cancel one. Perfox enforces the rules, whatever the AI asks for:
- at most 30 days ahead, and at most 3 pending follow-ups per customer;
- a time between 21:00 and 09:00 IST moves to the next 09:00, and the agent tells the customer the time it will actually happen;
- only on the channel the customer is using — Web Chat, SMS, WhatsApp or email. Phone call-backs aren't available yet;
- on SMS, WhatsApp and email the channel's sender must be wired to the agent, or the agent is told it can't schedule;
- the customer's own request in the conversation is kept as their consent.
At the due time the agent sends one message through its normal reply path, so your opt-out list and sending limits still apply; it waits while one of your people is handling the conversation, and doesn't send if your workspace is out of credits. The customer can ask the agent to cancel, and you can cancel from the conversation in Conversations.
MCP renders its own UI cards. Tick this when your integration's tools already return ready-made cards (address pickers, carts, slot pickers). The agent then stops drawing its own cards, so the customer never sees the same card twice.
Safety

| Control | Default | Effect |
|---|---|---|
| Block offensive content | Off | Turns on the model's content filters for this agent, blocking harassment, hate speech and dangerous content. |
| Fact-check replies before sending | Inherit from Compliance | Re-reads each reply against your knowledge base with a second AI call and replaces it if it isn't supported. Accurate, but it adds noticeable delay and stops replies appearing word by word. Choose Always on for this agent for agents that quote policies, prices or records, or Off for this agent. |
| Screen messages for manipulation attempts | Inherit from Compliance | Screens each incoming message with a second AI call for attempts to override the agent's instructions. It can be worth turning off for an internal agent with no tools and no sensitive data — but turning it off is a security decision, not a speed one. Leave it on for any public-facing agent or any agent with tools. |
Over-blocking
Block offensive content can wrongly refuse legitimate health, medical, legal or frank conversations. Leave it off unless you specifically need harassment or hate-speech blocking — medical and clinical agents should keep it off. The model's built-in baseline protections still apply.
PII redaction and topic boundaries aren't set per agent — they apply to every agent from your Compliance settings, which is also where "Inherit" takes its value from.
Memory
Every agent remembers the recent conversation automatically. These switches control the extra memory features (see Memory settings for more detail):
| Setting | Default | What it does |
|---|---|---|
| Search earlier messages | On | Before replying, the agent searches earlier messages in the conversation and pulls in the relevant ones — useful when something important was said long ago. Off is faster and cheaper; while it's off, new messages aren't indexed, so turning it back on only finds messages from then on. |
| Keep a running set of key facts | On | The agent keeps a short profile of what matters about the person and carries it into every turn, so it doesn't re-ask. |
| Learn from conversations over time | On | The agent periodically reflects on past conversations and keeps what it learned. The most expensive memory feature — turn it off for agents that answer one-off questions. |
| Remember only the current conversation | Off | Off: the agent also uses what it remembers from this customer's earlier conversations. Turn it on for agents with steps the customer must answer each time — a delivery address, who a booking is for, a time slot, a payment method. When on, the three features above work within the current conversation only, so a choice made last time is never reused without asking again. The customer's profile (name, phone, email) is still known. |
| Keep this agent's memory separate | Off | By default your agents share what they know about a customer — one customer, one company. Turn this on only for an agent in an unrelated area that shouldn't see what the customer told your other agents. It starts this agent with a clean slate. |
Settings and Notes tabs
Settings holds the node's label and description, and its retry behaviour — Max attempts (default 1), Backoff (default 1000 ms) and Timeout (default 30000 ms). Notes is free text for your team. See The Properties Modal.
What the AI Agent produces
The Output pane lists the variables later nodes can use — the agent's reply (ai_response), how the turn ended (__exit_reason__), and, when produced, attachments, charts, cards and rich content. An agent may also set its own variables through its tools; their names appear in a run's data.
How the agent waits between messages
You don't set this — it follows the canvas. If a node is connected after the AI Agent, the flow continues to it once the agent's stage is done. If nothing follows, the AI Agent is the end of the flow and simply keeps the conversation going, one message at a time.
A worked example — the Acme Diagnostics report agent
Setup. Asha adds an AI Agent and wires:
- a Personality — name "Ana", role "diagnostics assistant", tone "warm and precise", with a system prompt telling Ana to confirm the patient's name first and only discuss reports and billing;
- an AI Model, left on the platform defaults;
- a Knowledge part pointing at the "Test catalogue & prices" folder;
- an Integration for Acme's lab-records MCP server, which has a tool that looks up a report.
She leaves Allow general (LLM) knowledge on and Allow web search off, and sets Fact-check replies before sending to Always on for this agent, because Ana quotes prices. Then she clicks Activate.
Action. Priya writes in the web chat: "Hi, is my blood test ready, and what's the cost?"
Result. Ana asks her to confirm her full name and date of birth. Priya does. Ana calls the lab-records tool, sees the Complete Blood Count is ready, finds its price in the catalogue folder and replies:
Your Complete Blood Count is ready as of this morning. The charge is ₹450, and it's already settled — nothing due. Would you like me to email you the report?
What just happened. The Personality made Ana confirm identity first. The Integration fetched Priya's real record — a business fact, so it always wins. The Knowledge folder supplied the ₹450 price, and fact-checking confirmed the reply against it before it was sent. Two tool calls used two of Ana's 20 steps.
Options
Performance
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Speed vs accuracy | A starting point that fills in the settings below. You can change any of them afterwards — the label then reads "Custom". Reasoning effort and retrieval quality are not included here: they live on the Chat Model and Knowledge Base panels. |
Knowledge & Grounding
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Knowledge sources | ||||
| Knowledge lookup | Always attach (default): the knowledge base is searched before every reply and the best passages are added to the prompt — most reliable, but it costs a search and several thousand tokens on every turn, including greetings. On demand: the agent searches only when it decides it needs to, which is faster and cheaper on turns that need no knowledge. |
Advanced
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Information to collect | Structured details the agent should collect during the conversation | |||
| Stage gate | A deterministic multi-stage flow (e.g. login → verify → book): each stage sees only its own allowed tools + instructions until it advances. | |||
| Max steps per turn | Most actions the agent may take before it must reply (default 20). A ceiling — simple agents reply well within it; raise it for complex multi-tool flows. | 20 | ||
| Rich replies | Which visual formats this agent may produce — tables, charts, cards, pickers. Every format it can produce is described to the model on each step, so switching off the ones you do not need makes replies start sooner and cost less. Choose None for an agent that answers in plain text. | |||
| Built-in capabilities | Extra abilities this agent can use, and on which channels. Each one is described to the model on every step, so leave off anything this agent will not use. A PDF is useful on chat or email; on a phone call there is nowhere for the customer to open it. | |||
| MCP renders its own UI cards | Enable when this agent’s MCP tools return ready-made cards (address/cart/slot pickers). Removes the model’s generate_* view tools so it can’t draw the same card twice. |
Safety
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Guardrails | ||||
| Fact-check replies before sending | Inherit (default) uses your organisation setting from Compliance. This check re-reads each reply against your knowledge base with a second AI call and replaces it if it is not supported — accurate, but it adds noticeable delay AND stops replies appearing word-by-word, because a reply that may be withdrawn cannot be streamed. On is worth it for agents that quote policies, prices or records. | Inherit from Compliance · Always on for this agent · Off for this agent | inherit | |
| Screen messages for manipulation attempts | Inherit (default) uses your organisation setting from Compliance. This screens every incoming message with a second AI call for attempts to override the agent's instructions. It costs delay on every turn, so it can be worth turning off for an internal agent that has no tools and handles no sensitive data. ⚠️ Turning this OFF is a security decision, not a speed one — leave it on for any agent that is public-facing or can use tools. | Inherit from Compliance · Always on for this agent · Off for this agent | inherit |
Memory
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Answer cache | ||||
| Search earlier messages | ON (default): before replying, the agent searches earlier messages in this conversation and pulls in the relevant ones — useful for long chats where something important was said far back. Turning it OFF makes every turn faster and cheaper, and suits short conversations that fit in recent history anyway. Note: while OFF, messages are not indexed for search, so switching it back on will only find messages from that point forward. | true | ||
| Keep a running set of key facts | ON (default): the agent maintains a short profile of what matters about this person and carries it into every turn, so it does not re-ask. Turning it OFF removes those instructions and the tool that maintains them from every turn — slightly faster, but the agent will only know what is in the recent messages. | true | ||
| Learn from conversations over time | ON (default): the agent periodically reflects on past conversations and keeps what it learned, which it then includes in every turn (typically a few thousand characters). This is the most expensive memory feature — the reflection is an extra AI call that the customer waits for. Turn it OFF for agents that answer one-off questions and do not need to build up knowledge of a person. | true | ||
| Remember only the current conversation | OFF (default): the agent also uses what it remembers from this customer's earlier conversations. Turn ON for agents with steps the customer must answer each time, such as a delivery address, who a booking is for, a time slot, or a payment method. When ON, all three memory features above work within the current conversation only, so a choice made last time is never reused without asking again. The customer's profile (name, phone, email) is still known. | |||
| Keep this agent's memory separate | OFF (default): this agent shares what it knows about a customer with your other agents — one customer, one company. Turn ON only when this agent covers an UNRELATED domain and should not see what the customer told your other agents. Note: switching this on starts this agent with a clean slate, it does not filter existing memory. It does not change which agent answers. | false |
Block offensive content and the Settings-tab retry fields (Max attempts, Backoff, Timeout) are generic to every node, not specific to the AI Agent's own config — see the Safety and Settings and Notes tabs sections above for their defaults.
Where to go next
- Personality — identity, greeting and the system prompt.
- AI Model — models for chat, voice, documents and images.
- Integration — give the agent your own tools.
- Knowledge — pick folders and tune retrieval quality.
- Operator — your team on this agent: who answers, the hand-off, supervision and the copilot.
- Steps — script an ordered sub-flow for the agent.
- Collect Info — step-by-step collection with confirmation.
- Canvas Basics — adding and connecting nodes.