#The AI agent runtime

The runtime is everything between a customer's message and your agent's reply that you do not write. You and your coding agent decide what the agent knows, which tools it can call and what it should do. Vatio receives the message on WhatsApp, Instagram, the web widget or your app, decides when to answer, builds the prompt, runs the model and your tools, checks the reply, delivers it the way the channel expects and follows up afterwards. This guide walks through that path once, step by step, so you know what happens to each message and where to look when a reply is wrong.

#Three ways a turn starts

A turn is one reply from the agent: everything from reading what the customer said to sending the answer. Most turns start when a person writes, on WhatsApp or Instagram through Meta's webhooks, or in the web widget or your iOS, Android or Flutter app through the SDK. The third way is your backend: it calls the Messages API with a brief, such as "order 1042 shipped, offer the tracking link", and the agent writes the opening message itself. That turn skips the next two steps, because nobody wrote anything.

A turn also starts when a customer comes back from signing in through the button the agent sent them, so the conversation picks up where it stopped, and when a job a long-running tool started in the background finishes, so the agent can give the customer its result.

#Before the agent reads anything

#Intake

Vatio finds the contact and the conversation they are in; on WhatsApp and Instagram a conversation continues until eight hours pass without a message from the customer. Photos, PDFs and videos are downloaded, and voice notes are transcribed, before the agent reads them. Not everything starts a turn: a reaction, an edit or a message deleted for everyone changes what the conversation shows, and the agent reads the new state next time, without answering it.

#The response buffer

On WhatsApp and Instagram people write in bursts, so Vatio waits for a quiet moment and answers everything they sent at once, including a voice note still being transcribed. On the web and in apps the agent starts at once. A conversation has one turn at a time, so a message that arrives while the agent is answering gets its own turn right after. While a person from your team has taken over a conversation, the agent stays out of it. The next section covers this step in detail.

#Fluid conversations: grouping messages

A fluid conversation is one where the agent answers what the person meant, not each message as it lands. People write in fragments: "hi", the problem across two messages, a voice note because typing is slow, then a photo. To them that is one turn. A system that treats every inbound message as a request sees four requests and answers each one.

#Why answering every fragment fails

An agent that answers each message as it arrives:

Customer: hi

Agent: Hi! How can I help you today?

Customer: the lamp I ordered arrived today

Agent: Great to hear it arrived! Is there anything else I can help you with?

Customer: the base is cracked

Agent: I'm sorry about that. Can you send me your order number so I can start a refund?

Customer: (photo of the cracked base)

Customer: it's 4471. I'd rather have a replacement than a refund

Each reply answered a question that did not exist yet: it celebrated a delivery that was a complaint, asked for an order number the customer was about to give, and offered a refund to someone who wanted a replacement. Each was also a model call, sometimes a tool call, spent on half a question.

The same customer on an agent running on Vatio:

Customer: hi

Customer: the lamp I ordered arrived today

Customer: the base is cracked

Customer: (photo of the cracked base)

Customer: it's 4471. I'd rather have a replacement than a refund

Agent: Sorry about that, I can see the crack in the photo.

Agent: Order 4471 can be replaced. I've requested it: the new lamp ships with a prepaid label to return the broken one.

The messages arrived close together, so Vatio treated them as one turn. It waited for the photo to download, the agent made one call to the store's tool that checks an order and requests a replacement, and the reply went out as two short messages with typing indicators in between.

#Fragments are grouped, then Vatio waits for a quiet moment

Vatio groups messages that arrive together and waits for a quiet period before generating a response. The wait is a quiet period, not mind-reading: someone who stops long enough gets an answer to what they had sent, and whatever they add afterwards is the next turn.

The wait applies to WhatsApp and Instagram, where people write in bursts and replies go out as paced messages. On the web, in an iOS, Android or Flutter app and in the CLI the agent starts answering right away, and a message that arrives while it is answering gets an answer too.

#Media still in flight is waited for

A voice note has to be downloaded and transcribed; a photo or a PDF has to be downloaded before the model can read it. Vatio waits for attachments still being downloaded or processed instead of answering the text that came with them. Supported images, audio and PDFs up to 8 MB per file, and videos up to 14 MB, reach the agent. Anything unsupported or larger stays available to supervisors in the inbox, and the agent is told it cannot read it.

#Messages stay in the order they were sent

A voice note can take longer to process than the text sent after it. Vatio keeps each message's send time, shows the conversation in the order it happened, and checks for messages still in transit before answering.

#Replies are paced for the channel

These are delivery styles, not separate agents: one set of instructions, and Vatio handles each channel's mechanics. On every channel the reply is text: the agent reads media but does not generate or send files.

#What Vatio cannot know

WhatsApp does not tell anyone that a person has started recording a voice note: the Cloud API exposes no recording-start signal. Vatio learns about the audio when the sent message arrives, and can then wait while it is downloaded and transcribed. The wait also does not learn each person's rhythm: it depends on the channel's reply style and on whether media is still being processed, so nothing in your agent should rely on it.

#A person can step in, in the same thread

When a supervisor replies from the inbox, or from the WhatsApp Business app on your own number, Vatio pauses the agent on that conversation and keeps the whole history in the same thread. The supervisor hands it back from the inbox, or the takeover expires 8 hours after the last reply from your team, and the agent picks up the next time the customer writes. The agent can also ask for a person itself, through a tool that calls your backend with a link to the conversation (Human in the loop).

#Inside one turn

#The prompt is built for this turn

If your workspace has an identify_url, Vatio first asks your backend who the WhatsApp number belongs to, so the first answer already knows. Then it builds the prompt, fresh on every turn: the instructions and personality in your vatio.yml, the business name from the inbox, the tools and links the agent may use, who the contact is and whether they are signed in, what the agent remembers about them, the brief behind a message your backend asked it to send, and the rating, once the customer gave one. Because it is rebuilt each turn, a fix you publish applies to the next message in a conversation already under way.

#The model and your tools

The model that writes replies is listed on the model page, and every call goes through OpenRouter to endpoints that keep nothing. When the model calls a tool, Vatio runs it and gives the result back to the model, which can call another tool or answer. Your own tools are HTTP calls to your backend, defined in tools/*.yml, with your secrets and the contact's details filled in, and the signed-in person's token for a tool marked access: private. The built-in ones search your knowledge, remember and recall facts about the contact, and ask a WhatsApp contact for their phone number. A turn has a limited number of tool calls: when it runs out, the model answers with what it has and says what it could not do, instead of calling a broken tool again and again.

#Safeguards check the reply

Before anything is sent, Vatio clears text the model wrote for itself next to a tool call, and checks three things: the reply only carries links the agent was given, it embeds no image or file (replies are text), and it is not empty. A reply that fails is discarded, with the reason kept where the inbox and vatio chat show can show it, and the model writes it again with a note on what to fix. Safeguards covers each check.

#Nobody is left without an answer

If a turn ends with nothing to send, because the model provider failed or a safeguard left nothing of the reply, Vatio sends a short reply of its own and records why. When someone reports that reply, its diagnosis says whether the cause was something in your agent or Vatio itself, so you never rewrite instructions for an outage.

#Delivery

On WhatsApp and Instagram a long reply goes out as two or three short messages, with a typing indicator shown from the moment the turn started, the way a person texts. On the web and in apps the reply is one message in Markdown. Delivery happens inside the turn, so the next turn cannot slip a message in between two parts of this one.

#After the reply

• The rating question. When a conversation wraps up, a few seconds after the customer closes the topic or two minutes after they go quiet with what they asked for, Vatio asks once how it went. On WhatsApp the customer's tap is their message and the agent answers it, so your instructions can tell it to ask a happy customer for a review (Ratings).
• Memory. Once a conversation with a known contact has been quiet for 30 minutes, Vatio summarizes it and keeps the lasting facts. An agent with remember or recall starts the next conversation with them (Memory).
• Webhooks. Your backend hears what happened to each message it sent and every rating a customer gives, signed with your endpoint's secret (Webhooks).

#Write for how the conversation arrives

A few lines in the agent's personality and instructions work with the runtime. Ask your coding agent to add them to vatio.yml:

• Ask for brevity. A personality such as "brief, short messages" suits paced delivery on WhatsApp and Instagram; a wall of text arrives as many messages.
• Answer the whole turn. Fragments arrive together, so tell the agent to address everything the customer raised, not only their last message.
• Do not ask for what was already sent. "Check the conversation and any photo or voice note before asking for an order number" saves a round trip.
• Never promise a file. The agent reads media but replies only in text, so the instructions should never offer a PDF, an image or a voice reply.

#Test it the way people write

vatio chat answers as soon as a reply is ready, so it tests what the agent says, not how it is delivered. To see grouping and pacing, use a real channel: add your phone as a test number on the shared WhatsApp preview number, with no Meta account needed, as the WhatsApp guide shows. Then send what customers send: "hi", two half-sentences, a voice note, a photo.

#What you control at each step

Everything else on the path, from transcribing a voice note to keeping two parts of a reply in order, is the same for every agent and runs without code.

#See what a turn did

Open the conversation in the inbox to see the tool calls behind each reply. From your terminal, vatio chat show CHAT_ID prints the conversation with its tool calls and any reply a safeguard discarded, and vatio tools --env live shows how often each tool fails and how slow it is across every conversation. When a reply is wrong, report it in the inbox; your coding agent picks it up with /vatio-improve, and improving your agent covers that loop.

#Frequently asked questions

#What is an AI agent runtime?

It is everything that runs between a customer's message and the agent's reply that is not the agent's own instructions, tools and knowledge: receiving the message, downloading and transcribing media, deciding when to answer, building the prompt, calling the model and the tools, checking the reply, delivering it on the channel and following up. On Vatio you describe the agent in vatio.yml and the runtime does the rest.

#Does the agent remember earlier conversations?

It can. Once a conversation with a known contact has been quiet for 30 minutes, Vatio summarizes it and keeps the lasting facts as notes. Give the agent the remember or recall tool and it starts every conversation with those notes, saves new ones as the customer mentions them, and searches older conversations when it needs to.

#What happens if a tool keeps failing?

Each turn has a limited number of tool calls. When it runs out, the model is told to answer with what the tools did return and to say what it could not do, so the person gets an answer instead of silence. vatio tools --env live shows how often each tool fails across every conversation.

#Can the agent reply with nothing, or with an error?

No. If a turn ends with nothing to send, because the model failed or a safeguard left nothing of the reply, Vatio sends a short reply of its own and records why. A report on that reply says whether the cause was the agent or Vatio.

#Does the agent see the rating a customer gives?

Yes. When a WhatsApp customer taps Good, So-so or Bad, the tap is their message and the agent answers it knowing the rating, so your instructions can tell it to ask a happy customer for a review. Your backend hears every rating as a feedback.submitted webhook.

#Why does my WhatsApp bot answer every message separately?

Because it treats each inbound message as a complete request. People write in fragments, so a bot that replies to each one answers half-questions. Vatio groups messages that arrive together and waits for a quiet moment before generating one reply.

#Does Vatio know when someone is recording a voice note on WhatsApp?

No. The WhatsApp Cloud API does not expose a signal for when someone starts recording. Vatio learns about the audio when the sent message arrives, and can then wait while it is downloaded and transcribed.

#Does the wait adapt to how each person writes?

No. The wait depends on the channel's reply style and on whether media is still being downloaded or processed, not on the person writing.

#Do I have to program message buffering and delivery myself?

No. Grouping messages, waiting for media, keeping send order and pacing replies are part of the runtime. Your coding agent describes the agent, its tools and its knowledge in vatio.yml when you run /vatio-init, after npx @vatio-ai/skills in your app's project.

#What happens to the conversation when a person takes over?

Vatio pauses the agent on that conversation and keeps the whole history in the same thread, so the customer never starts over. A supervisor takes over by replying from the inbox or from the WhatsApp Business app, and hands it back from the inbox when done.

#Related guides

• An AI agent on WhatsApp: Add WhatsApp to your app's agent: test on a shared number, then connect your business number.
• Safeguards: The checks every reply passes before it is sent, and the rules you add on top so the agent never says what it must not.
• Connect your backend: Give the agent your API as tools, and let signed-in users reach their own data with a token your backend signs.
• Your daily improvement routine: Report mistakes in the inbox, /vatio-improve has your coding agent fix them, and you approve the update.
• Best practices: Instructions, tools, knowledge, handoff and tests: what works for an agent real users talk to.
• Build an AI agent for your app: Run npx @vatio-ai/skills and /vatio-init in your app's project, answer what the code can't, and try the preview before publishing.