# 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 your coding agent describes one agent in a `vatio.yml` file and it answers in your app, through the web widget and the iOS, Android and Flutter SDKs, and on WhatsApp and Instagram.

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. [Choosing how to build your app's agent](https://vatio.ai/docs/guides/vatio-vs-frameworks-and-no-code) weighs an agent framework in your own backend, a visual builder and Vatio for your app's agent.

### Agent runtime

A hosted service that runs an agent from a definition you write and operates the machinery around it. Vatio is a runtime: your coding agent writes `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](https://vatio.ai/docs/guides/build-an-ai-agent) walks through building one in your app's project.

### 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, you start in your app's project with `npx @vatio-ai/skills` and `/vatio-init`. 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 pauses the agent when a person takes over. See [Fluid conversations](https://vatio.ai/docs/guides/ai-agent-runtime).

### 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](https://vatio.ai/docs/guides/ai-agent-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](https://vatio.ai/docs/manifest) 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), `send_image` (sends a WhatsApp contact a photo one of your tools returned), `knowledge_write` (writes what the business tells the agent on WhatsApp into its knowledge base), `ask_supervisor`, `answer_customer` and `supervisor_questions` (the agent asks a supervisor what it cannot answer, and relays the answer), `remember` and `recall`. You enable them in `agent.tools`. None of them asks for a person: that is a tool of yours, see [Human handoff](#human-handoff).

### 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 create API keys, 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](https://vatio.ai/docs/tools).

### 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](https://vatio.ai/docs/authentication/sessions#on-whatsapp).

### 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 key

In Vatio, the `vatpub_…` key 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, `ios-app://BUNDLE_ID` or `android-app://PACKAGE_NAME`, which keep it on your site or app but say nothing about who the visitor is. See [An AI chat for your website](https://vatio.ai/docs/guides/ai-chat-widget-for-your-website) and [An AI agent in your iOS app](https://vatio.ai/docs/guides/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 tests from reported 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](https://vatio.ai/docs/knowledge).

### 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, where a save goes live right away.

### 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, links the agent was not given and the model's own reasoning written next to a tool call; 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](https://vatio.ai/docs/safeguards).

## Conversations and channels

### Channel

A place where customers talk to the agent. Vatio's channels are the web widget and browser SDK, the iOS, Android and Flutter SDKs, WhatsApp and Instagram DMs 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, iOS, Android and Flutter SDKs, a stored conversation can be resumed while its chat credentials last, which is 12 hours.

### Human handoff

An agent passing a conversation to a person. In Vatio it is an ordinary tool of yours, listed in `agent.tools`, whose `when_to_use` says in your words when to call it. Its request carries `$chat.url`, which opens the conversation in the inbox, and `$chat.id` if your backend keeps its own record; your backend alerts whoever you choose: a WhatsApp to a supervisor, a Slack channel, an email or a helpdesk ticket. Calling it is the model's judgement, not a rule Vatio enforces. The agent keeps helping until a person replies, and that reply is a human takeover. See [Hand off to a person](https://vatio.ai/docs/handoff).

### 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 last reply from your team.

### 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. See [Fluid conversations](https://vatio.ai/docs/guides/ai-agent-runtime).

### 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 **Try the agent** in the inbox, 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](https://vatio.ai/docs/guides/instagram-ai-agent).

### 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, on any [plan](https://vatio.ai/pricing), and switch **Live** on. See [An AI agent on WhatsApp](https://vatio.ai/docs/guides/whatsapp-ai-agent).

## Supervising and improving

### Digest

In Vatio, the Markdown document `vatio flags` prints for a coding agent: each open report with the conversation up to the reply, that turn's tool calls with what your backend answered, and the note. When there are new reports, a mail also goes out to the workspace's owner and developers at 08:00 America/Santiago with the command to run in their coding agent, `/vatio-improve`; it never quotes a conversation.

### Eval (test)

An eval is an automated test of an agent: conversations replayed against it, with each result graded. In Vatio, each reply reported with a note on live becomes a test case, and so does each one kept with `vatio test add`: a photo of that turn (the conversation as it happened, who the visitor was and when, and what your backend answered) with the note as the expected outcome. `vatio test --wait` has preview's version write each of those turns again and exits 1 if one fails. Tests call your tools for real, so point them at a sandbox first with a test value; see [Improve your agent](https://vatio.ai/docs/improve).

### 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, report replies and read the knowledge.

### Judge

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

### Regression

A change that breaks something that used to work. In `vatio test`, 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, unless someone overrides that check with `vatio publish --force`.

### Report

In Vatio, a mark on a wrong reply in a real conversation, made with **Report this reply** in the inbox by a supervisor, a developer or the owner, with a note saying what should have happened: a different answer, an action, or a tool the agent should have used. A report with a note becomes a test case, shows as fixed in preview once `vatio test` passes it there, and is resolved when live passes it; editing the note reopens it. The CLI calls reports flags: `vatio flags` prints the open ones for a coding agent, with the notes a developer leaves the same way on test conversations, which are not test cases and close with the next push.

### 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 or the SDKs in your app, or on WhatsApp and Instagram.

### 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. While the workspace is a draft (nobody outside the team has talked to it yet), live follows preview on every push, so 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 and has reported cases, it is refused while preview's version is untested, and when it fails a case live passes unless that check is overridden with `--force`; it takes preview's test results live with it. Publishing is the owner's decision: a coding agent runs it only when asked. See [Improve your agent](https://vatio.ai/docs/improve).

### 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.

## Frequently asked questions

### What is the difference between an AI agent and a chatbot?

A traditional chatbot follows flows someone drew: menus, buttons and fixed answers. An AI agent uses a language model to understand free text and decides on each turn whether to answer, look something up or act through a tool, such as checking stock or booking a slot. Many products call both chatbots, so ask what happens when a question falls outside the script.

### What is tool calling in an AI agent?

Tool calling, also called function calling, is how an agent acts. The model picks a tool and fills its parameters, the runtime makes the call, and the model answers from the result. In Vatio each tool is one HTTP request to your API, described in a YAML file.

### What is human handoff in an AI agent?

It is the agent passing a conversation to a person, because the customer asked or because it reached something it should not resolve alone. In Vatio the agent does it with a tool of yours that calls your backend with a link to the conversation; your backend alerts whoever you choose, and their reply from the inbox takes the conversation over. Until someone replies, the agent keeps helping.

### What is an eval for an AI agent?

An eval is an automated test: conversations replayed against the agent, with each reply graded, often by another model acting as a judge. In Vatio the tests are the replies reported with a note on live and the ones kept with vatio test add; vatio test replays them against preview, and vatio publish refuses a version that fails one live passes, unless that check is overridden with --force.

### How do you stop an AI agent from hallucinating?

No setting removes it, but you can leave it little room: tools for facts that change, a knowledge base for policies, explicit rules such as never inventing a price, and tests built from real mistakes. Vatio also strips any link the agent was not given, and shows every tool call so you can see where a wrong answer came from.

## Related guides

- [Build an AI agent for your app](https://vatio.ai/docs/guides/build-an-ai-agent): 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.
- [Choosing how to build your app’s agent](https://vatio.ai/docs/guides/vatio-vs-frameworks-and-no-code): When an agent framework, a no-code builder or a runtime like Vatio is the right call.
- [Best practices](https://vatio.ai/docs/guides/ai-agent-best-practices): Instructions, tools, knowledge, handoff and tests: what works for an agent real users talk to.
- [Your daily improvement routine](https://vatio.ai/docs/improve): Report mistakes in the inbox, /vatio-improve has your coding agent fix them, and you approve the update.