;
};
Keep your Mastra agent, its model, and your chat UI. Three steps add Vendo
to it: run `vendo init`, spread `vendoMastraTools` into the agent's tools,
and render tool outputs with one component.
## 1. Install and init
```bash theme={null}
npm install @vendoai/vendo
npx vendo init
```
Init scaffolds the wire route (`app/api/vendo/[...vendo]/route.ts`), extracts
your host actions into agent tools, and captures your theme
([what init writes](/connect/vendo-init)). The wire route serves generated
apps and approvals to the embeds; your Mastra agent stays the loop.
Your agent needs the same `vendo` instance the wire route uses, so lift the
generated composition into a shared module both import:
```ts theme={null}
// src/lib/vendo.ts — init's composition, moved so your agent can import it
import { createVendo } from "@vendoai/vendo/server";
import { serverActions } from "./vendo-actions";
export const vendo = createVendo({
policy: "cautious", // run reads, ask before writes
serverActions, // the map init generated from your actions
});
```
```ts theme={null}
// src/app/api/vendo/[...vendo]/route.ts
import { nextVendoHandler } from "@vendoai/vendo/server";
import { vendo } from "@/lib/vendo";
export const runtime = "nodejs";
export const dynamic = "force-dynamic";
export const { GET, POST, PUT, PATCH, DELETE } = nextVendoHandler(vendo);
```
## 2. Spread the pack
The agent definition gains the pack next to its own tools.
`vendoMastraTools` returns a Promise, which is why the agent uses Mastra's
tools-as-function form:
```ts theme={null}
// src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent';
import { vendoMastraTools } from '@vendoai/vendo/mastra';
import { vendo } from '../../lib/vendo';
import { weatherTool } from '../tools/weather-tool';
export const weatherAgent = new Agent({
id: 'weather-agent',
name: 'Weather Agent',
instructions: `…your instructions, plus a short note about the vendo_* tools…`,
model: 'openai/gpt-4.1-mini',
tools: async () => ({ weatherTool, ...(await vendoMastraTools(vendo)) }),
});
```
A Mastra agent definition is static (one definition serves every user), so
the shim takes no principal. Instead, set the caller's principal server-side
on the `RequestContext` in your chat route; a `vendo_*` call without one
fails closed:
```ts theme={null}
// src/app/api/chat/route.ts — Mastra's own Next.js guide route, two additions
import { handleChatStream } from '@mastra/ai-sdk';
import { RequestContext } from '@mastra/core/request-context';
import { createUIMessageStreamResponse } from 'ai';
import { mastra } from '@/mastra';
import { VENDO_PRINCIPAL_KEY } from '@vendoai/vendo/mastra';
import { vendo } from '@/lib/vendo';
export async function POST(req: Request) {
const params = await req.json();
await vendo.store.ensureSchema(); // lets guarded tools run before any wire request
const requestContext = new RequestContext();
// Resolve the caller from your own session — never trust the client.
requestContext.set(VENDO_PRINCIPAL_KEY, { kind: 'user', subject: 'demo-user' });
const stream = await handleChatStream({
version: 'v6',
mastra,
agentId: 'weather-agent',
params: { ...params, requestContext },
});
return createUIMessageStreamResponse({ stream });
}
```
Multi-turn tool use with GPT-5 reasoning models currently fails on history
replay ([mastra-ai/mastra#9005](https://github.com/mastra-ai/mastra/issues/9005));
pin `openai/gpt-4.1-mini` as the workaround those issues document.
## 3. Render the embeds
Wrap the chat once in `VendoProvider` and hand finished tool outputs to
``: it renders the live app embed for a generated app, the
approval card for a parked call, and nothing for plain data. Mastra streams
tool calls as `dynamic-tool` or `tool-*` parts, so match both:
```tsx theme={null}
// src/app/page.tsx — inside your existing message-parts loop
if (part.type === "dynamic-tool" || part.type.startsWith("tool-")) {
const tool = part as ToolLikePart;
return tool.state === "output-available"
?
: Running {tool.toolName ?? part.type.slice("tool-".length)}…;
}
```
The frontend is identical to the [AI SDK quickstart](/existing-agents/ai-sdk):
the embed contract is framework-agnostic.
## Try it
One thread, three asks:
1. **"What's the weather in Paris?"** Your agent's own tool, untouched.
2. **"Make me a dashboard comparing weather in Paris, Tokyo and NYC."**
`vendo_create_app` returns an app ref immediately and the app builds live
inline in the chat.
3. **"Email the report to [ops@example.com](mailto:ops@example.com)."** A write parks on the cautious
policy and renders as an approval card. Approve executes it in place.
## The full example
[`examples/mastra-agent`](https://github.com/runvendo/vendo/tree/main/examples/mastra-agent)
is the unmodified [`create-mastra`](https://mastra.ai/docs) weather starter,
fronted with Next.js per Mastra's own guide, plus exactly this diff (\~60
lines, every Vendo line inside `--- vendo:` comment fences), with a keyless
fixture e2e (`pnpm test`). The concepts behind the pack (approval parking,
the envelope contract, the two-model split) live in
[the overview](/existing-agents) and
[Embeds and envelopes](/existing-agents/embeds).