# Build an AI agent for your app

This page is for people building an app with a coding agent (Claude Code, Cursor, Codex) or an app builder (Lovable, Bolt, Replit, v0), live or still in progress, and for the coding agent they ask to do the work. You do not need to write code or YAML yourself. Vatio runs the model and the conversations, and your team supervises them in the inbox.

There are two steps. The first is the fastest; the second builds the agent into your app's code.

## Step 1: ask for the agent from a chat

Add `https://vatio.ai/mcp` as a connector in Claude, ChatGPT or Cursor, sign in with your Vatio account, and ask for the agent you want. It is created in a preview you can try. Nothing reaches your users until you publish. Until someone outside your team talks to the agent, the workspace is a draft and live follows preview ([Deployments](https://vatio.ai/docs/deployments)). Setup and what the connector can do are in [Vatio in Claude and ChatGPT](https://vatio.ai/docs/mcp).

## Step 2: build it into your app

You need the app's project on your computer, open in Claude Code, Cursor or Codex, and Node.js 20 or newer. If you built the app in Lovable, Bolt, Replit or v0, connect the project to GitHub and open it from there. If the app's backend is in a repository of its own, use that one: it holds the API the agent can call and the docs it can read.

In the project, run:

```bash
npx @vatio-ai/skills
```

Then, in Claude Code:

```text
/vatio-init
```

In Cursor or Codex, ask it to use vatio-init. You can say what you want after the command, for example `/vatio-init a support agent that answers from our docs and checks a user's order status with our orders API`. With nothing after it, `/vatio-init` reads your code and proposes something concrete.

`vatio-init` looks before it creates. If the project already has a `vatio.yml` or a workspace, it joins that one instead of starting a second agent. It reads the app, asks only what the code does not answer, writes the agent, pushes a preview and gives you a link to try it. The first push opens your browser to sign in with email, Google or GitHub; signing in creates your account.

`npx @vatio-ai/skills` copies the skills into `.claude/skills/` and `.agents/skills/`, where Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot and OpenCode look for them. In Claude Code you can install them as a [plugin that updates itself](https://vatio.ai/docs/integrations/claude-code) instead. The skills are:

- **`vatio-init`** starts with Vatio in a project.
- **`vatio-improve`** (`/vatio-improve`) is the daily routine on replies your team reported ([Improve](https://vatio.ai/docs/improve)).
- **`vatio-analyze`** reads what people asked the agent between two dates, redacted, and reports the topics and what it could not answer.
- **`vatio-share-session`** sends the session to the Vatio team, only if you say yes.

## What vatio-init asks you

It asks only what your code does not say:

- What does your app or business do, and who will write to the agent?
- What must the agent never say or promise? Discounts, delivery dates, diagnoses, anything that would be a problem in writing.
- When does a person have to take over? A complaint, a refund, a user who is upset.
- Which of your systems should it read from? An API, a calendar, a catalog.

A vague answer gets a question back, not a guess. Your coding agent turns the answers into instructions, rules, tools and knowledge in `vatio.yml` and the files beside it, which you can read and review like any other file. Its API keys go into Vatio's secrets, never into the repository. Tools run on Vatio's servers, so they cannot reach `localhost`: the API has to be on the internet, a staging deployment for instance. [Tools](https://vatio.ai/docs/tools) and [Authentication](https://vatio.ai/docs/authentication/) cover both, including tools that read a signed-in user's own data.

## Try it, then publish

The link `vatio-init` gives you opens the inbox with **Try the agent** open:

- **Web chat**, on the page.
- **WhatsApp**: scan the QR code with your phone and send the message it writes. It is Vatio's shared preview number, with no Meta account. Up to five test phones.
- **Instagram**: the same, on a shared preview account.

**Conversations**, in the same inbox, shows the tools the agent called, what your API returned and the knowledge it read under every reply. When a reply is wrong, tell your coding agent what you saw; it changes the agent, pushes again and replays the conversation.

Your coding agent never publishes on its own. When the preview is right, ask it to publish. `vatio rollback` restores the previous live version, configuration and knowledge together. Then put the agent where your users are:

- **Your web app or website:** ask your coding agent to create a publishable key for your domain and add one script tag. See [Web chat](https://vatio.ai/docs/guides/ai-chat-widget-for-your-website).
- **Your own chat UI:** the browser, iOS, Android and Flutter SDKs give you the conversation and the UI is yours. See [iOS](https://vatio.ai/docs/guides/ai-agent-in-your-ios-app), [Flutter](https://vatio.ai/docs/guides/ai-agent-in-your-flutter-app) and [Android](https://vatio.ai/docs/sdk/android).
- **WhatsApp** and **Instagram** are added channels, connected on live from the inbox's **WhatsApp** and **Instagram** pages. See [WhatsApp](https://vatio.ai/docs/guides/whatsapp-ai-agent) and [Instagram](https://vatio.ai/docs/guides/instagram-ai-agent). Plans are on [vatio.ai/pricing](https://vatio.ai/pricing).

Your team joins from **Team** in the inbox as supervisors, who see every conversation, take one over by replying and report wrong replies, or as viewers, who only read. **Activity**, on the **Security** page, records who opened, answered or changed what. From there, read [Improve](https://vatio.ai/docs/improve) and [Best practices](https://vatio.ai/docs/guides/ai-agent-best-practices).

## Pick a use case

- [Bookings](https://vatio.ai/docs/guides/ai-agent-for-bookings): availability, booking, moving and cancelling appointments.
- [Orders](https://vatio.ai/docs/guides/ai-agent-for-orders): order status, changes and returns.
- [Customer support](https://vatio.ai/docs/guides/ai-agent-for-customer-support): answers, account checks and tickets.
- [Onboarding](https://vatio.ai/docs/guides/ai-agent-for-onboarding): helping new users finish setup.

## If you are a coding agent

You were asked to build an agent on Vatio for someone's app, usually with `/vatio-init`. `vatio-init` follows this same procedure. The contract, every field of `vatio.yml` and every command, is in the docs, and the docs win wherever a guide disagrees with them. Read them before you write anything:

```bash
npx @vatio-ai/cli docs
```

The same is one Markdown file at [vatio.ai/docs/docs.md](https://vatio.ai/docs/docs.md), and every docs page is also at its own address plus `.md`. The procedure for reading the contract and joining an existing workspace is under "For coding agents" in the [introduction](https://vatio.ai/docs/). `vatio` below is `npx @vatio-ai/cli` when the CLI is not installed globally. You run these commands, not the person you work for.

### The order that works

1. **Install the skills** unless `.agents/skills/vatio-init` is already in the project: `npx @vatio-ai/skills` from the root.
2. **Look before you create.** Search for a `vatio.yml` at or above the current directory and anywhere in the repository (`git ls-files '*vatio.yml'`). If one exists, the agent exists: never run `vatio init` there, because it writes a starter agent and pushing that replaces the real one. Follow [Joining an existing workspace](https://vatio.ai/docs/#joining-an-existing-workspace). If you only have a workspace slug, ask for the repository: Vatio keeps what was deployed, not the files it came from. `vatio doctor` says whether the CLI is signed in and which workspace this directory resolves to.
3. **Read the app.** What it does and for whom, the API an agent could call, how users sign in, and the docs, FAQs and policies an agent could read.
4. **Say what you found and recommend**, in a few lines, from their code: what is there, what the agent would answer, which endpoint becomes which tool, what goes to a person. Ask for confirmation.
5. **Ask the four questions above, all at once**, and only those. Do not invent prices, hours, policies or delivery times. If the owner does not know yet, write the instruction so the agent says it does not know and offers a person.
6. **Write the agent**: `vatio.yml`, a file per tool under `tools/`, and knowledge. See [Manifest](https://vatio.ai/docs/manifest), [Tools](https://vatio.ai/docs/tools) and [Knowledge](https://vatio.ai/docs/knowledge). Asking for a person is a tool of your own that calls the business's backend with a link to the conversation ([Hand off to a person](https://vatio.ai/docs/handoff)).
7. **Check, push and try it.** `vatio diff` validates and shows what would change; `vatio push` deploys to preview. Try the question most customers ask, something the tools and knowledge do not cover, something the agent must never promise, a case that should go to a person, and `vatio chat --new` as a visitor it has never met. `vatio chat show` prints every tool call with what the API returned; the cause of a wrong reply is often the tool's response, not the instructions.
8. **Hand over the link** that `vatio push` prints after `Try it:`, with what you tried, how it answered and what only the owner can decide.
9. **Publish only when asked**, with `vatio publish`. After the draft, it wants preview's version tested with `vatio test` and refuses one where a reported case that passes on live fails on preview; `vatio publish --force` overrides that check, only when the owner says so.
10. **Before you finish**, if an error or the docs left you guessing, run `vatio feedback "what you were doing and what was missing"`. In Claude Code, run `vatio share-session --should-ask` last: if it prints `yes`, show the person what would go (`vatio share-session --save FILE`) and ask once whether to send it; if it prints `no`, say nothing.

### What the agent does not do

Do not promise these to the owner:

- It replies in text. It reads images, voice notes and PDFs, but sends no files.
- It does not read websites. What it should know, you write as knowledge.
- It writes first only when the business's backend calls the [Messages API](https://vatio.ai/docs/api/messages), on WhatsApp.
- It does not decide who to tell when a conversation needs a person. A tool calls the business's backend, which alerts whoever the owner chooses.

### Mistakes that cost a session

| Mistake | What happens | Instead |
|---|---|---|
| `vatio init` where a `vatio.yml` exists | The starter agent replaces the real one on push | Work from the existing `vatio.yml` |
| A tool file that is not in `agent.tools` | The agent never sees the tool | List every key in `agent.tools` |
| `base_url` on `localhost` | Every call fails | An API reachable from the internet |
| An API key in a tool's YAML | The key is in the repository | `vatio secrets set`, read as `$env.KEY` |
| A failure returned as a 200 | The agent reads the failure as an answer | Return the real status code |
| A `business:` block in `vatio.yml` | Ignored, with a warning | What the business does in `agent.instructions`; its name in **Web chat** in the inbox |
| A `handoff:` block in `vatio.yml` | Ignored, with a warning | A tool that asks for a person |
| A knowledge base that does not exist yet | The push fails | `vatio kb create` first |
| Prices or policies made up to finish the demo | The agent states them to customers | Ask the owner, or have the agent say it does not know |
| Publishing to show progress | Customers get an untested agent | Hand over the preview link and wait |

## Frequently asked questions

### Do I need to know how to code to build an AI agent with Vatio?

You need a coding agent more than you need to code. In your app's project you run npx @vatio-ai/skills and then /vatio-init, and Claude Code, Cursor or Codex writes the agent, deploys it to a preview and tests it; you answer questions about your app and try the result. Connecting it to your own systems needs an HTTP API, and building one where none exists is developer work, which your coding agent can also do in your backend.

### Which coding agents work with the Vatio skills?

Claude Code, Cursor, Codex and any coding agent that reads skills from .agents/skills, such as Gemini CLI, GitHub Copilot and OpenCode. One that reads no skills still finds a Vatio section in the project's AGENTS.md, and you can hand it this page.

### Which channels can a Vatio agent answer on?

Your app first: the web widget with one script tag, or your own chat UI on the browser, iOS, Android and Flutter SDKs. WhatsApp and Instagram DMs work too. The terminal is for testing. It is the same agent everywhere; only the delivery changes.

### How long does it take to build an AI agent?

Getting a first agent onto a preview takes one session with your coding agent, and you need no account until it first pushes. What takes real time is the part only you can do: deciding what the agent must never say and giving it an API to call.

### Which AI model does a Vatio agent use?

DeepSeek V4.1 Flash, through OpenRouter and only on endpoints with zero data retention. Vatio runs the model for you, so there is no model to host and no model key in vatio.yml. The Models and data page in the docs lists every model Vatio uses.

### Can the agent message customers first, for reminders or campaigns?

On WhatsApp, yes, when your backend asks through the Messages API. The agent never decides on its own to write first, and there is no campaign dashboard: your backend picks who and when. Instagram does not let a business write first.

### How do I stop the agent from making things up?

Tell your coding agent what the agent must never do; it writes those as explicit rules, gives the agent tools for anything that changes, such as stock, prices and bookings, and knowledge for the rest, and tells it to say so when neither answers. Vatio strips any link the agent was not given, shows every tool call in the inbox, and turns each reply your team reports with a note into a test.

### What if the business has no API?

Start with an agent that answers from knowledge and offers a person for anything that needs their systems. With nothing to alert them, the team finds those conversations in the inbox. When an action needs data, the endpoint belongs in the backend, one endpoint per job; a coding agent proposes it and builds it only when asked.

### Can the agent be tested on WhatsApp before the business connects its number?

Yes. The inbox's Try the agent panel connects up to five phones to Vatio's shared preview number with a QR code, and needs no Meta account. Instagram has the same kind of shared preview account.

## Related guides

- [An AI agent on WhatsApp](https://vatio.ai/docs/guides/whatsapp-ai-agent): Add WhatsApp to your app's agent: test on a shared number, then connect your business number.
- [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.