#AI agent glossary

This glossary explains the terms that come up when you build an AI agent that talks to customers, from tool calling and RAG to human handoff, evals and publishing. Each entry gives the general meaning first and then, where it applies, what the term means in Vatio, where you describe one agent in a vatio.yml file and it answers on WhatsApp, Instagram, the web and iOS apps.

Terms are grouped by theme and sorted alphabetically within each group.

#Agents and how they are built

#Agent framework

A library you import into your own backend to build an agent in code, with abstractions for model calls, tools, memory and chained steps. You run it yourself, along with everything a customer-facing agent needs around it: channel webhooks, conversation state, an inbox, deployments and tests. Vatio vs. frameworks and no-code builders compares the three approaches.

#Agent runtime

A hosted service that runs an agent from a definition you write and operates the machinery around it. Vatio is a runtime: you write vatio.yml and one YAML file per tool, and Vatio runs the channels, message grouping, identity checks, safeguards, inbox and deployments.

#AI agent

Software that uses a language model to hold a conversation and decide, turn by turn, whether to answer, look something up or act through a tool. In Vatio, a workspace runs exactly one agent, defined under agent: in vatio.yml, and the same agent answers on every channel. Build an AI agent walks through one from an empty folder.

#Coding agent

An AI assistant that works in your repository and terminal, reading code, editing files and running commands, such as Claude Code, Codex or Cursor. In Vatio, the agent is files and a CLI, so a coding agent can write, test and fix it: vatio init adds a Vatio section to AGENTS.md, and the docs are one Markdown file at https://vatio.ai/docs/docs.md.

#Conversation fulfillment

Vatio’s name for everything between a customer’s message and the reply they receive, by analogy with ecommerce fulfillment. You decide what the agent can do; Vatio receives the messages, groups them, waits for media, paces the reply and brings in a person when one is needed. See Fluid conversations.

#Instructions (system prompt)

The text that tells a model what job it does and which rules it follows, often called the system prompt. In Vatio it is agent.instructions, the only required field of the agent, and Vatio adds business context, contact state, tool descriptions and its own platform instructions around it. Write what the agent must never do as explicit rules; Best practices shows how.

#Manifest (vatio.yml)

The file that defines a Vatio workspace, kept in your repository next to one YAML file per tool under tools/. Its only root keys are workspace, agent and auth, and an unknown root key fails validation. The manifest reference describes each one.

#No-code chatbot builder

A hosted product where you draw conversations as flows in a visual editor and connect channels from a settings screen. It suits teams without a developer and mostly fixed conversations, such as menus or forms; the agent lives in the builder’s editor rather than in a repository.

#Personality

The voice and tone of an agent, kept apart from what it does. In Vatio it is the optional agent.personality, which defaults to warm, brief and clear.

#Workspace

In Vatio, the container for one agent and its conversations, contacts, knowledge, secrets and channel connections. Its slug is the workspace key of vatio.yml, and every CLI command reads it from the nearest vatio.yml.

#Tools, identity and data

#Built-in tools

Tools that come with Vatio, so you write no YAML for them: knowledge_lookup, identify_contact (saves a name the visitor gives), request_contact_info (asks a WhatsApp visitor to share their number), remember and recall. You enable them in agent.tools; handoff is attached by declaring agent.handoff instead.

#Contact

The person behind a conversation, with a name, email and phone number when they are known. In Vatio, a contact is filled by identify_contact, by the number a WhatsApp message comes from, or by the claims of a signed token, and tools read it as $contact.name, $contact.email and $contact.phone_number.

#Developer token

In Vatio, the vat_… token the CLI uses, created when you approve a machine with vatio login. It can deploy, read secrets and mint publishable tokens, so it belongs on your machine or in a CI secret such as VATIO_TOKEN, never in a web page, an app or a repository.

#JWT (visitor identity)

A JSON Web Token: a compact, signed set of claims, commonly used to say who a user is. In Vatio, your backend signs an RS256 JWT with sub (your user id), aud (the workspace slug) and exp, and Vatio verifies it with your public key; it never holds the private key, so it can check an identity but never mint one. The widget and the SDKs pass it as the visitor token: see Connect your backend.

#Memory (remember and recall)

What an agent knows about a person from earlier conversations. In Vatio, a conversation with a known contact is summarized once it has been quiet for 30 minutes, and lasting facts are saved as notes; with the built-in remember and recall enabled, the agent sees up to 20 notes in every conversation, saves new ones with remember and searches summaries and notes with recall. Preview and live contacts never see each other’s memory.

#Private tool

In Vatio, a tool marked access: private: it runs only for a visitor whose JWT was verified, and reaches their data through $auth.subject or $auth.token. It cannot take user_id, customer_id, account_id, member_id, patient_id or subject as a parameter, because the model fills parameters; the deploy fails if it does. Private tools run on the web, in apps, and on WhatsApp and Instagram once the contact signs in.

#Public tool

In Vatio, a tool with access: public, or with no access at all, which runs for anyone, including WhatsApp and Instagram contacts who have not signed in. Anything it reveals about one person needs a check in your backend, such as a reference number plus a second detail that must match.

#Publishable token

In Vatio, the vatpub_… token a web page or app carries to talk to one workspace and environment. It works only from its allowed origins, exact scheme://host[:port] values or ios-app://BUNDLE_ID, which keep it on your site or app but say nothing about who the visitor is. See An AI chat for your website and An AI agent in your iOS app.

#Tool (function calling)

An action a model can ask to run, described by a name, a description and parameters: the model fills the parameters, the runtime makes the call and the model answers from the result. It is also called function calling or tool use. In Vatio a tool is one HTTP request to your API, described in tools/<key>.yml and enabled in agent.tools, and any branching belongs behind one endpoint in your backend.

#Knowledge and accuracy

#Hallucination

When a language model states something plausible that is not true: a price, a policy, a stock level, a link. In Vatio, the safeguards strip any URL the agent was not given; the rest is prevented by what you build: rules such as “never invent a price”, tools for facts that change, a knowledge base for policies, and evals from flagged replies. Every tool call is visible in the inbox, so a wrong answer can be traced to its source.

#Knowledge base

A collection of documents an agent reads instead of memorizing. In Vatio, a knowledge base holds Markdown entries you write from the CLI or the inbox, created with vatio kb create and listed under agent.knowledge; Vatio does not read websites. See Knowledge base.

#Knowledge entry

One Markdown document in a knowledge base, written with vatio kb write BASE ENTRY file.md. Its headings split it into sections that are searched separately, so each section should answer a question on its own. Every change is kept as a numbered version, and supervisors can edit entries in the inbox.

#knowledge_lookup

The built-in Vatio tool that searches the knowledge bases the agent lists under knowledge. You enable it in agent.tools and tell the agent in its instructions when to search; each lookup shows up with the turn’s other tool calls.

#Link allowlist

The list of URLs an agent is allowed to send. In Vatio it is agent.links, each a URL or { url, when, values } with placeholders expanded at deploy time. A reply may only carry a URL the agent was given, in links, elsewhere in its prompt or in a tool’s result, and the safeguards strip any other.

#RAG (retrieval-augmented generation)

A technique in which passages relevant to a question are retrieved from a document store and added to the model’s context, so it answers from your text rather than from memory. In Vatio, the closest piece is knowledge_lookup: the agent calls it when it needs your content, and it searches the sections of the entries you wrote, which Vatio indexes in the background after each write. It searches only those entries; Vatio does not crawl websites or connect to other document stores.

#Safeguards

Checks that run on every reply before it is sent. In Vatio they catch empty replies, generated media and links the agent was not given; a failed check triggers a correction attempt, and they cannot be turned off. What the agent must never say is yours to write in the instructions: see Safeguards.

#Conversations and channels

#Channel

A place where customers talk to the agent. Vatio’s channels are the web widget and browser SDK, WhatsApp, Instagram DMs, the iOS SDK and the CLI for testing; it is the same agent on all of them, and only the delivery changes.

#Conversation window

How long a conversation stays open before the next message starts a new one. On WhatsApp and Instagram, Vatio continues a conversation until the visitor’s last message is more than eight hours old. In the web and iOS SDKs, a stored conversation can be resumed while its chat credentials last, which is 12 hours.

#Hours

In Vatio, the business hours set on the inbox’s Business page by whoever runs the business: when a person is on duty, in a timezone, with one or more shifts per day. The agent is given them so it can tell customers when you are open. They do not decide when the agent answers, only what happens after a handoff: inside hours the agent goes quiet, outside them it keeps helping, and a handoff nobody picks up within an hour goes back to the agent.

#Human handoff

An agent passing a conversation to a person. In Vatio, declaring agent.handoff gives the agent that tool, with your own when conditions and an after_turns floor, and a visitor who asks for a person always triggers one. The chat then shows as waiting in the inbox; Vatio does not notify anyone yet. See Hand off to a person.

#Human takeover

A person replying in a conversation in place of the agent. In Vatio, a reply from the inbox, or from the WhatsApp Business app on your own number, pauses the agent on that chat until someone hands it back, or until 8 hours after the customer’s last message.

#Message grouping (buffering)

Treating several messages someone sends in a row as one question. On WhatsApp and Instagram, Vatio groups fragments that arrive together and waits for a quiet moment, and for media still downloading or being processed, before the agent answers, and keeps messages in the order they were sent. Waiting that adapts to each person is in development and not available yet; see Fluid conversations.

#Pacing

How a reply is delivered on each channel. On WhatsApp and Instagram, Vatio sends a reply as short messages with pauses and typing indicators; on the web, as one reply rendered progressively. The SDKs choose with replyStyle: stream, paced or instant.

#Test phone and test account

A phone or Instagram account you connect from the inbox’s Test page, by sending the shared preview the code it shows, to talk to your agent’s preview before it is live; it never reaches live. Each workspace can have up to five test phones on the shared WhatsApp preview number and up to five test accounts on the shared Instagram preview account. See An AI agent on Instagram.

#WhatsApp preview number

Vatio’s shared WhatsApp number for testing, so you can talk to your agent on real WhatsApp without a Meta account. You add your phone as a test phone by scanning a QR code and sending the message it writes, then message the number; customers reach your own business number once you connect it and switch Live on. See An AI agent on WhatsApp.

#Supervising and improving

#Digest

In Vatio, the Markdown document vatio flags prints for a coding agent: each open flag with the conversation up to the reply, that turn’s tool calls with what your backend answered, and the supervisor’s note. When there are new flags, a mail also goes out to the developers at 08:00 America/Santiago with the prompt to paste into Claude Code, /vatio:vatio-improve; it never quotes a conversation.

#Eval and eval case

An eval is an automated test of an agent: conversations replayed against it, with each result graded. In Vatio, each flag with a note, made on live or on preview, becomes an eval case, with the visitor’s turns as input and the note as the expected outcome, and vatio eval replays every case against preview and exits 1 if one fails. Evals call your tools for real, so point them at a sandbox first with a test value; see Improve your agent.

#Flag

In Vatio, a supervisor’s mark on a wrong reply, made with Report this reply in the inbox, with a note saying what should have happened: a different answer, an action, or a tool the agent should have used. A flag with a note becomes an eval case, shows as fixed in preview once vatio eval passes it there, and is resolved when live passes it; editing the note reopens it.

#Inbox

Where a team reads an agent’s conversations. Vatio’s inbox shows every conversation with each tool call, finds any of them by a name, a number or something that was said, and it is where supervisors take a conversation over, flag replies and edit knowledge.

#Judge

A model that grades an agent’s reply against an expected outcome, an approach often called LLM-as-a-judge. In vatio eval, the judge comes from a different model family than your agent’s and answers pass or fail with one sentence of reasoning, which vatio eval --show RUN_ID prints.

#Regression

A change that breaks something that used to work. In vatio eval, a case that passes on live and fails on preview is a regression: it is listed first, and vatio publish is refused until it passes.

#Supervisor

A person from the business who watches the agent’s conversations. In Vatio, supervisors are invited from Team in the inbox and sign in with a code sent to their email; they see the inbox and the knowledge, and cannot deploy or change tools.

#Deploying and environments

#Environment

A named place an agent is deployed to. In Vatio, an environment points to a deployment, a saved snapshot of the configuration, and there are two: preview for trying changes, live for customers.

#Live

The environment customers talk to. In Vatio, live changes with vatio publish, and customers reach it through the widget on your site, WhatsApp, Instagram or the SDKs.

#Preview

The default environment for trying an agent before customers see it. In Vatio, vatio push deploys to preview and runs no tests, and test phones and test accounts reach preview. Until the first publish, preview is the agent.

#Publish

Making a version live. In Vatio, vatio publish promotes preview to live together with its knowledge changes. Once the agent has been published, it is refused while preview’s version is untested or breaks a flag live passes, and it takes preview’s eval results live with it. See Improve your agent.

#Rollback

Going back to the previous live version. In Vatio, vatio rollback restores the previous live snapshot, configuration and knowledge together; it does not restore secret values or undo what a tool already did.

Updated: October 11, 2026