On this page
The AI Agent step lets an AI run a whole customer conversation inside a flow. On every customer message it decides what to send, using only the tools, files, forms and links you allow, and when the conversation is finished it leaves through the exit you chose. This guide covers adding the step, what each setting controls, and how to test it before a customer sees it.
AI Agent step: first 5 of 7 steps
- 1Start from the template, or add the
- 2Write the goal and persona
- 3Choose what it may use
- 4Add the material behind the tools
- 5Define the exits
Before you start
- The step is on every plan, including Free, and runs on AI credits. Each customer message the agent answers is one AI reply and costs 10 AI credits, with 1,000 free each month. See how AI credits work.
- It answers on VGraple AI by default, with no key to add. To use your own provider key, see bring your own AI key.
- Add your business knowledge first (a pasted article, a web page, or question and answer pairs) so the agent has something true to say. See the AI chatbot guide for knowledge sources.
- If the agent should share forms, contact cards, files, templates or products, have them ready: a published WhatsApp form, a saved contact card, uploaded files, approved text templates, a connected product catalog.
Steps
- Start from the template, or add the step yourself. On the Flows page, choose Start with an AI Agent. It creates a normal flow in which any message starts the agent, Handoff and Fallback lead to a Human Handoff step, and Completed and Timeout end the flow. You can edit it like any other flow. Or open a flow and drag AI Agent from the palette.
- Write the goal and persona. In Goal and persona, say who the agent is, what it should achieve in this conversation and how it should speak. For example: you are the studio's assistant, help the customer pick a service, answer from our knowledge, and book them in.
- Choose what it may use. Under Knowledge, pick the knowledge base, and switch on Answer business questions only from knowledge and the catalog if it should never answer from general knowledge. Under Tools, switch on what the agent may do, and add optional guidance for any tool in a few words.
- Add the material behind the tools. Tick the forms the agent may open, the contact fields it may fill in, the contact cards it may share, the files it may send, the templates it may use when the 24 hour window is closed, and the catalog for product messages. Under Allowed link domains, list the websites it may link to, such as your booking page.
- Define the exits. Completed is always there, and you can add your own, each with a line saying when to take it, such as "the customer confirmed a budget and a date". Handoff, Timeout and Fallback are always present. Connect each exit to the next step.
- Set the limits. Choose Max customer turns, the Reply timeout (hours), an optional Disclosure line that is sent before the first reply, and how long to wait before repeating it. Pick the Frustration sensitivity and the Message when the AI is unavailable.
- Test it. Click Test on the step. The flow is saved and a test chat opens, where you type as a customer and see the agent's replies rendered as WhatsApp messages. Nothing is sent to anyone and nothing is charged.
What you will see
In a live conversation the agent's messages appear in the Inbox with the flow's Auto badge. Select Why beside one to see what the agent did on that turn: the tools it used, what each returned, and which exit it chose. On the Flows page, a flow with an AI Agent step has an Insights link showing conversations, how they ended, handoff and fallback rates, and reply time over 7, 30 or 90 days.
Settings and options
| Setting | What it does |
|---|---|
| Goal and persona | The agent's role, aim and tone. This is its main instruction |
| AI connection | VGraple AI by default, or your own provider key from Settings, then AI |
| Knowledge | Which knowledge base the agent searches, and whether it may answer business questions from anything else |
| Tools | Ask with buttons or a list, send a link button, send products, request a location, search knowledge, search the catalog, save a lead, request an appointment, update the contact, store a value for later steps. Hand off to a person and Exit are always on |
| Forms, contact cards, files, templates, catalog | The only items of each kind the agent may send. If you tick none, it cannot send that kind |
| Allowed link domains | Websites the agent may link to. Links to any other site are removed before sending |
| Exits | Where the flow goes when the conversation ends: Completed and your own exits, plus Handoff, Timeout and Fallback |
| Max customer turns | After this many customer messages the agent leaves through Fallback so the flow can hand off |
| Reply timeout (hours) | How long the agent waits for the customer before leaving through Timeout |
| Disclosure line | An optional first line telling the customer they are talking to an AI, with a setting for how many hours pass before it repeats |
| Frustration sensitivity | Low offers a person only when asked, normal on frustration or a third repeat, high on the first sign of it |
| Message when the AI is unavailable | Sent instead of silence when no model can answer; the flow then leaves through Fallback |
Some limits do not change. The agent sends at most three messages in one turn. It will not send a free-form message when the 24 hour window is closed, and uses a template you ticked instead, or leaves through Fallback if there is none. A conversation allows 60 agent turns a day. Safety topics, payment details and an explicit request for a person always go to Handoff, whatever the sensitivity.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| A link in the agent's reply is missing | The site is not in Allowed link domains, so the link was removed | Add the domain, or have the agent describe where to find it |
| The agent never sends a form, card or file | None of that kind is ticked on the step, or no published form or approved template exists yet | Tick it on the step, and publish the form or get the template approved first |
| The agent stopped answering one customer | A person replied or the agent handed over, which pauses the AI on that chat | Resume the AI with the toggle in the conversation header |
| The customer got the unavailable message | No AI connection could answer, or credits ran out | Check Settings, then AI, and the balance. See AI is on but not replying |
| The flow ends right after the agent's last message | The exit it chose has no step connected | Connect the exit to the next step, or to End Flow on purpose |
| A product card does not send | The product is not in the synced catalog, or has no image for a carousel | Check the catalog sync, and that the product has an image |
Related reading
For the simpler single-answer step, see the AI chatbot guide. Every step type is listed in the Flow Builder node reference, and handing a conversation to a person is covered in AI escalation to a human.
Frequently asked questions
What is the difference between the AI Agent step and the AI Reply step?
The AI Reply step writes one answer and moves on, or keeps answering in a simple loop. The AI Agent step runs the whole conversation. On each customer message it decides what to send (plain text, buttons, a list, a link button, product cards, a form, a contact card, a file) and can save a lead, request an appointment or update the contact before it leaves through one of the exits you defined.
Can the agent say anything it likes?
No. It can only use the tools you switch on, the forms, contact cards, files, templates and catalog you tick on the step, and the link domains you allow. A link on a domain you did not allow is removed before the message is sent, and a price is only quoted from your catalog or your services.
What does it cost to run?
Each customer message the agent answers is one AI reply and costs 10 AI credits, the same as an AI Reply step. Testing the agent in the builder's test chat is not charged. You can set a monthly credits budget under Settings, then AI, which warns you at 80 and 100 percent and never stops replies.
What happens when a person should take over?
The agent leaves through the Handoff exit. The conversation is marked as needing a person, the AI is paused on that chat, and everyone in the team who has the mobile app gets a push notification. The agent also hands over without asking the model when a customer asks for a human or raises a sensitive topic or a payment detail.
Does it work on website chat as well as WhatsApp?
Yes. Buttons, lists, product cards, forms and location requests are WhatsApp features, so on website chat the agent uses text and allowed links only.
Can the customer reset the conversation?
Yes. A customer who sends /reset starts from a clean slate, and the running agent closes.