# Vatio vs building it yourself with the Claude Agent SDK

The Claude Agent SDK and Vatio both put an agent to work, but for different jobs. The Agent SDK is Claude Code as a library: the same agent loop, built-in tools and context management, in Python or TypeScript, running in a process you host. It suits agents that work through files, commands and code. For a customer-facing chat in your app, the SDK gives you the loop and tool calling, and you build and operate the rest: hosting, conversation storage, user identity, an inbox where your team takes over, channels, tests from real conversations and rollouts. Vatio provides that runtime: your coding agent writes the agent into your app's project, and Vatio runs it for your app's users. If the agent isn't customer-facing, or you want full control of a Claude agent on your own infrastructure, the Agent SDK is the better fit.

## What the Claude Agent SDK is

Anthropic describes the Agent SDK as a way to build production AI agents with Claude Code as a library, with "the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript."

- **Built-in tools** read, write and edit files, run commands and search the web. **Subagents**, **hooks**, **skills** and **MCP servers** work as they do in Claude Code.
- **Custom tools** have a name, a description, an input schema and a handler, and reach the agent through an MCP server that runs inside your application.
- **Permissions** decide which tool calls run on their own and which need approval: permission modes, allow and deny rules, and a `canUseTool` callback.
- **Sessions** keep context across exchanges and can be resumed or forked later.

Where it runs is up to you. Each session starts a Claude Code process that owns a shell, a working directory and session transcripts on local disk. Anthropic's hosting guide recommends a sandboxed container, a `SessionStore` adapter to keep transcripts beyond a restart, and authentication at a gateway in front of the agent: "The agent should receive pre-authenticated requests and should not be the component that validates user tokens." Its examples include a chat bot serving Slack traffic and a customer support agent that loads ticket history. You call Claude with an Anthropic API key, or through Amazon Bedrock or Google Cloud. If you'd rather not host the loop, Anthropic also offers Managed Agents, which runs it for you.

## What Vatio is

Vatio is an agent for the app you're building, with a coding agent or an app builder. It has two steps. The fastest, from any chat: add the remote MCP server `https://vatio.ai/mcp` as a connector in Claude, ChatGPT or Cursor, sign in with a Vatio account and ask for the agent; it is created in a preview to try, and nothing reaches your users until you publish ([Vatio in Claude and ChatGPT](https://vatio.ai/docs/mcp)). To build the agent into the app's code: in the project run `npx @vatio-ai/skills`, then `/vatio-init`, and `/vatio-improve` daily. Your coding agent reads the app, asks what the code doesn't answer and writes the agent into your project: instructions in `vatio.yml`, tools that call your API, and knowledge entries, which you can review like the rest of your code.

Your team follows the conversations in the inbox and takes one over by replying. When a reply is wrong, someone reports it and writes what should have happened, and that note becomes a test. `/vatio-improve` fixes the cause in your project, Vatio replays the reported cases against a preview, and you approve each publish.

## The main differences

| | Built with the Claude Agent SDK | Vatio |
|---|---|---|
| Built for | Agents that plan and use tools on files, commands and code | A customer-facing agent for your app's users |
| Model | Claude | Vatio picks it ([Models and data](https://vatio.ai/docs/model)) |
| Hosting | Your containers, one process per session | Vatio's servers |
| Conversations | Local transcripts, or a `SessionStore` you configure | Kept by Vatio, encrypted, with a retention period you set |
| User identity | A gateway you put in front of the agent | A token your backend signs; Vatio verifies it |
| Inbox, channels | Yours to build | Inbox with takeover; your app, plus WhatsApp and Instagram |
| Tests and rollouts | Yours to build | Reported replies become tests; preview, live, publish checks, rollback |
| What the agent can do | Built-in tools, your custom tools, MCP | Only its tools: one HTTP request each, plus built-ins such as knowledge and memory |

## When the Claude Agent SDK is the better choice

- **The agent works with files, code or a shell.** That is what its built-in tools are for. A Vatio agent has no files or shell; it calls the tools you declared.
- **The agent isn't customer-facing**: internal automation, research, an operations agent, a coding agent of your own.
- **You want Claude, and Claude Code's harness**, with subagents, hooks and skills. Vatio picks the model, and choosing one per agent isn't available yet.
- **The work takes minutes.** A Vatio tool runs inside the agent's turn and answers in seconds; long work that changes your code goes to a Claude Code routine that your backend starts.
- **You want full control on your own infrastructure** and have the engineering time to run it, or you'd rather have Anthropic host the loop with Managed Agents.

## When Vatio fits better

You want a chat for your app's users, and you'd rather not build what the hosting guide leaves to you. Vatio covers it:

- **Identity.** Vatio verifies who the user is on every channel: your backend signs a short-lived token with the key from `vatio auth --new-key`. A user who signs in mid-conversation keeps the conversation, and a different user gets a new one ([Sessions and channels](https://vatio.ai/docs/authentication/sessions)).
- **A narrow surface.** Private tools forward the verified token as `Bearer $auth.token` and can't take a user id as a parameter, so your API reads the user from the token. The agent can only call the tools you declared, and Vatio checks every draft reply for links it wasn't given ([Safeguards](https://vatio.ai/docs/safeguards)).
- **Conversations and people.** Vatio keeps every conversation, and the inbox shows each reply with the tool calls behind it. Your team takes over by replying. To have the agent ask for a person, you give it a tool that calls your backend, which alerts whoever you choose with a link to the conversation ([Human in the loop](https://vatio.ai/docs/handoff)).
- **Channels.** The web widget and the browser, iOS, Android and Flutter SDKs in your app; WhatsApp and Instagram.
- **Improvement and rollouts.** Reported replies become tests, `/vatio-improve` fixes the cause, Vatio replays the cases on preview, and publishing refuses a version that breaks one live gets right unless you override it with `--force`. Rollback brings back the previous live version.

Claude still has a place: Claude Code builds and improves the agent with the Vatio skills, and from a WhatsApp chat, a tool of the agent can ask your backend to start a [Claude Code routine](https://vatio.ai/docs/guides/give-claude-a-whatsapp) that works on your code.

## Moving from the Claude Agent SDK to Vatio

1. **Start.** In your app's project, run `npx @vatio-ai/skills`, then `/vatio-init` in Claude Code (or, from a chat, connect the Vatio MCP server `https://vatio.ai/mcp` and ask for the agent), and point it at your agent:

   ```text
   /vatio-init move our support agent built on the Claude Agent SDK in agent/support.ts to Vatio: same custom tools, same system prompt
   ```

   The first time it pushes the agent, your browser opens to sign in with email, Google or GitHub; signing in creates your account.
2. **Your system prompt becomes instructions.** The system prompt you pass, and any `CLAUDE.md` your agent loads, becomes `agent.instructions` in `vatio.yml`.
3. **Your custom tools become Vatio tools.** A handler that calls your API becomes a `request` in `tools/NAME.yml`, with the same description and input schema. A handler that does more moves into one endpoint in your backend. The error messages you composed with `isError` become your API's error responses, with a `message` and an `error_key` the agent reads ([Tools](https://vatio.ai/docs/tools)). Each tool the agent may use is listed in `agent.tools`; a tool file alone doesn't enable it. A ticket tool, as your coding agent might write it in `tools/open_ticket.yml`:

   ```yaml
   description: Open a support ticket on the signed-in user's account.
   when_to_use: The steps did not fix the problem and the user agreed to a ticket.
   parameters:
     type: object
     properties:
       summary: { type: string, description: "The problem, with any error message word for word" }
     required: [summary]
   access: private
   request:
     method: POST
     base_url: "$env.APP_API"
     path: /me/tickets
     headers:
       Authorization: "Bearer $auth.token"
     body:
       summary:
   respond:
     data:
       ticket: "$.ticket"
   ```

   When your endpoint can't open the ticket, it answers with a real status and a body such as `{ "message": "This account already has an open ticket.", "error_key": "ticket_open" }`, and the agent says so.
4. **Built-in tools stay behind.** A customer chat doesn't need a shell. Files or pages your agent read to answer become knowledge entries, since Vatio doesn't read websites ([Knowledge](https://vatio.ai/docs/knowledge)).
5. **Approvals become rules.** For calls you gated with `canUseTool`, decide which ones the agent may make on its own, which go to a person (written in the `when_to_use` of a tool that alerts your team), and which your backend refuses.
6. **Your gateway becomes an identity token.** A token your backend signs; your coding agent can add the signing to your backend. Tools that read a user's data become `access: private`. For facts that should carry across conversations, the built-in `remember` and `recall` give the agent memory of each contact.
7. **Put it in your app, try it, publish.** Add the widget or an SDK, with a publishable key that lists your app's origins (`vatio keys create publishable --origin https://your-app.com`, or **Settings → API keys** in the inbox). The inbox's **Try the agent** web chat chats as a visitor who isn't signed in; to try signed-in behavior, put preview's widget in a development build and sign in as a test user. Approve publication, then retire the containers.

## Sources

Checked on 14 October 2026. Features and plans change: check the Claude Agent SDK's own documentation, listed below, for what it offers today.

- Agent SDK overview: https://code.claude.com/docs/en/agent-sdk/overview
- Hosting the Agent SDK: https://code.claude.com/docs/en/agent-sdk/hosting
- Custom tools: https://code.claude.com/docs/en/agent-sdk/custom-tools
- Permissions: https://code.claude.com/docs/en/agent-sdk/permissions

## Frequently asked questions

### Should I build my app's customer chat with the Claude Agent SDK or with Vatio?

The Claude Agent SDK fits agents that work through files, commands and code, internal or autonomous work, and teams that want Claude and its harness on their own infrastructure. For a customer-facing chat, the SDK gives you the loop and tool calling, and you build and operate the rest: hosting, conversation storage, identity, an inbox with takeover, channels, tests from real conversations and rollouts. Vatio provides that runtime, and your coding agent writes the agent into your app's project.

### Does a Vatio agent run on Claude?

Vatio runs the model for every agent and picks it; its Models and data page lists the current models. Choosing one per agent isn't available yet, though you can write to Vatio's support with the model you need and what it is for. Claude comes in on the building side: Claude Code, with the Vatio skills, writes and improves the agent in your app's project.

### Can I reuse my Agent SDK custom tools in Vatio?

Yes, as Vatio tools. A custom tool whose handler calls your API becomes a YAML file describing that request, with the same name, description and input schema. A handler that does more, such as several calls or a calculation, moves into one endpoint in your backend, and the Vatio tool calls that endpoint.

### What would I build around the Agent SDK that Vatio already runs?

Anthropic's hosting guide leaves the containers, session persistence and user authentication to you, and a customer chat also needs somewhere for your team to read and take over conversations, channels such as WhatsApp, tests and a way to roll out changes. Vatio verifies your users' identity, keeps the conversations, gives your team an inbox, answers in your app and on WhatsApp and Instagram, turns reported replies into tests and has preview and live versions with rollback.

### Can a Vatio agent hand work to Claude Code?

Yes, from WhatsApp. An ordinary Vatio HTTP tool calls an endpoint in your backend, which checks the number against its own allowlist and starts a Claude Code routine. The routine works on your code in its own session and answers in the same chat. See [the guide](https://vatio.ai/docs/guides/give-claude-a-whatsapp).

## Related guides

- [Vatio vs the Vercel AI SDK](https://vatio.ai/docs/guides/vatio-vs-vercel-ai-sdk): What you build and run yourself around the AI SDK's loop, what Vatio runs instead, and how to move your tools.
- [Build an AI agent for your app](https://vatio.ai/docs/guides/build-an-ai-agent): The two-step entry, from a chat or in your app's project, and trying the preview before publishing.
- [Tools](https://vatio.ai/docs/tools): Give the agent your API as tools.
- [Safeguards](https://vatio.ai/docs/safeguards): The checks every reply passes before it is sent.