;
};
Your loop, your model, your chat UI. Vendo adds [a pack of guarded
tools](/existing-agents/overview) to them.
Paste this and your coding agent wires the pack against the agent playbook.} prompt={EXISTING_AGENTS_PROMPT} />
## 1. Init
```bash theme={null}
npm install @vendoai/vendo ai @ai-sdk/react
npx vendo init
```
Answer the questions. On the first one, pick **Through my own agent loop (AI
SDK / Mastra)**. On the model one take **Vendo Cloud**: a free key lands in
`.env.local` as `VENDO_API_KEY`, and Vendo's own screen turns run on it with
nothing else to set. Your own provider key works too. Init writes the
[`models:` line](/deploy/model-credentials) that selects it, because a key
sitting loose in the environment selects nothing.
## 2. Share one instance
Init writes `createVendo` inside the wire route. Move it to `lib/vendo.ts` so
your chat route uses the same instance, and export the identity init already
wrote — step 3 needs it to resolve the caller. Keep whichever line init wrote.
`auth` and `principal` fill the same seam, so `createVendo` refuses a config
that sets both.
```ts init wired an auth preset theme={null}
// lib/vendo.ts
import { clerk } from "@vendoai/vendo/auth/clerk";
import { createVendo } from "@vendoai/vendo/server";
const auth = clerk(); // whichever preset init detected
export const resolvePrincipal = auth.principal;
export const vendo = createVendo({
// …the options init wrote
auth,
});
```
```ts init wired no auth preset theme={null}
// lib/vendo.ts
import { createVendo } from "@vendoai/vendo/server";
// the function init wrote — swap in your real session lookup
export const resolvePrincipal = async (req: Request) =>
({ kind: "user" as const, subject: "demo-user" });
export const vendo = createVendo({
// …the options init wrote
principal: resolvePrincipal,
});
```
```ts theme={null}
// app/api/vendo/[...vendo]/route.ts
import { nextVendoHandler } from "@vendoai/vendo/server";
import { vendo } from "@/lib/vendo";
export const { GET, POST, PUT, PATCH, DELETE } = nextVendoHandler(vendo);
```
## 3. Spread the pack
The pack takes the *resolved* caller — a `{ kind, subject }` object — so build
it inside the handler, once you know who is asking. Vendo mints no principals,
so a visitor your resolver can't place gets a 401.
```ts AI SDK theme={null}
// app/api/chat/route.ts
import { convertToModelMessages, streamText } from "ai";
import { vendoTools } from "@vendoai/vendo/ai-sdk";
import { vendoModel } from "@vendoai/vendo/server";
import { resolvePrincipal, vendo } from "@/lib/vendo";
export async function POST(req: Request) {
const { messages } = await req.json();
const caller = await resolvePrincipal(req);
if (!caller) return new Response("Unauthorized", { status: 401 });
return streamText({
model: vendoModel(),
messages: await convertToModelMessages(messages),
// your own tools spread in here too
tools: { ...(await vendoTools(vendo, { principal: caller })) },
}).toUIMessageStreamResponse();
}
```
```ts Mastra · agent theme={null}
// src/mastra/agents/your-agent.ts
import { Agent } from "@mastra/core/agent";
import { vendoMastraTools } from "@vendoai/vendo/mastra";
import { vendo } from "@/lib/vendo";
export const yourAgent = new Agent({
id: "your-agent",
name: "your-agent",
instructions: "…your system prompt as it is",
model: "openai/gpt-4.1-mini", // your own model and your own key
tools: async () => ({ ...(await vendoMastraTools(vendo)) }), // yours spread in too
});
```
```ts Mastra · register theme={null}
// src/mastra/index.ts — agentId below resolves against this instance
import { Mastra } from "@mastra/core/mastra";
import { yourAgent } from "./agents/your-agent";
export const mastra = new Mastra({ agents: { yourAgent } });
```
```ts Mastra · route theme={null}
// app/api/chat/route.ts — the pack reads its caller from here
import { handleChatStream } from "@mastra/ai-sdk";
import { RequestContext } from "@mastra/core/request-context";
import { VENDO_PRINCIPAL_KEY } from "@vendoai/vendo/mastra";
import { createUIMessageStreamResponse } from "ai";
import { resolvePrincipal } from "@/lib/vendo";
import { mastra } from "@/mastra";
export async function POST(req: Request) {
const params = await req.json();
const caller = await resolvePrincipal(req);
if (!caller) return new Response("Unauthorized", { status: 401 });
const requestContext = new RequestContext();
requestContext.set(VENDO_PRINCIPAL_KEY, caller);
params.requestContext = requestContext; // omit this and every vendo_* call fails
const stream = await handleChatStream({ version: "v6", mastra, agentId: "your-agent", params });
return createUIMessageStreamResponse({ stream });
}
```
Your loop keeps its own model credential. `vendoModel()` rides the same ladder
Vendo's internal turns do, so the Cloud key from step 1 pays for both seats;
Mastra's `openai/…` pin needs an `OPENAI_API_KEY` of its own. Either way:
[Two models, two credentials](/deploy/model-credentials#two-models-two-credentials).
Framework notes: [AI SDK](/existing-agents/ai-sdk) · [Mastra](/existing-agents/mastra).
## 4. Render the results
`vendo_*` calls arrive in your chat as `dynamic-tool` parts. Hand the finished
ones to ``, anywhere under one ``.
```tsx theme={null}
// app/page.tsx
"use client";
import { useChat } from "@ai-sdk/react";
import { VendoProvider, VendoToolResult } from "@vendoai/vendo/react";
export default function Chat() {
const { messages } = useChat();
return (
{messages.map((message) => message.parts.map((part, i) => {
const key = `${message.id}-${i}`;
if (part.type === "text") return
{part.text}
;
if (part.type === "dynamic-tool" && part.state === "output-available") {
return ;
}
return null;
}))}
);
}
```
## 5. Ask for a screen
Say **"Make me a dashboard of this month's spending by category"** in your own
chat. A live view builds inline. Then check the wiring:
```bash theme={null}
npx vendo doctor
```
Next: [embeds and envelopes](/existing-agents/embeds).