In your existing agent

Keep your loop. Vendo adds the guarded tools and renders what they return. The setup command is the same npx vendo init as every path: it reads your repo, asks how people will use your agent, and writes the wiring. Step 1 runs it.

Spread the tools in

The pack takes the caller you already resolved, so it is built inside the handler. Spread it beside your own tools.Already ran vendo init? It installed ai and your model provider, but never @ai-sdk/react — add that one, then pick up at the lib/vendo.ts below.

npm install @vendoai/vendo ai @ai-sdk/react @ai-sdk/anthropic
npx vendo init

pnpm add @vendoai/vendo ai @ai-sdk/react @ai-sdk/anthropic
pnpm exec vendo init

No pins needed. Vendo speaks both live AI SDK majors, so ai@6 and ai@7 are each supported — keep the pair together (ai@7 with @ai-sdk/*@4, ai@6 with @ai-sdk/*@3), which is what a bare install gives you.vendo doctor checks the ai major and nothing else: it reports E-DEP-001 when ai falls outside that pair. It never inspects @ai-sdk/anthropic, so a @ai-sdk/* major that drifts out of step with ai passes doctor clean — keep that pin matched by hand.Answer the first question with Through my own agent loop (AI SDK / Mastra), and take Vendo Cloud on the model one. Init writes the wire route and lands a VENDO_API_KEY in .env.local.Init put that createVendo call in lib/vendo.ts already (src/lib/vendo.ts when your app lives under src/), with the wire route a thin handler over it. Export the caller resolver beside it — your chat route, your wire route, and the pack all need the same instance.

lib/vendo.ts

import { authJs } from "@vendoai/vendo/auth/auth-js";
import { createVendo } from "@vendoai/vendo/server";

const auth = authJs();
export const resolvePrincipal = (req: Request) => auth.principal(req);
export const vendo = createVendo({ auth });

Every snippet on this track imports those two from there. Swap authJs() for your own provider’s preset — Auth lists all five.No provider yet? Then init wrote a demo principal in place of a preset, and the resolver you export beside it hands your chat route that same subject:

lib/vendo.ts

import { createVendo } from "@vendoai/vendo/server";

// init writes the principal; the resolver is
// yours. Swap both for a real session lookup.
const principal = async () => ({
  kind: "user" as const,
  subject: "demo-user",
});
export const resolvePrincipal = (_req: Request) => principal();
export const vendo = createVendo({ principal });

Both sides have to resolve the SAME subject. Your loop and the wire route the embeds call are two different requests, and an app or approval created under one subject is invisible to a surface asking as another — the embed then polls a screen it will never be shown. Everything below stays as written: the demo resolver never returns null, so the 401 guard simply never fires.

AI SDK · app/api/chat/route.ts

import { convertToModelMessages, stepCountIs, 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),
    stopWhen: stepCountIs(5),
    system: "…your system prompt as it is",
    // your own tools spread in here too
    tools: { ...(await vendoTools(vendo, { principal: caller })) },
  }).toUIMessageStreamResponse();
}

That system line is yours and stays yours — Vendo assembles nothing into it, and a turn that loses it answers like a different product. The section at the bottom of this page is what you ADD to it.

Mastra · 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 model choice, unchanged
  tools: async () => ({ ...(await vendoMastraTools(vendo)) }),
});

Every tool lands under a vendo_ prefix, so nothing collides with a tool of your own.

Tool	What your model gets
`vendo_<your action>`	one per registered host action, guard-wrapped per call
`vendo_make`	a live view, returned as an app ref right away while the build streams
`vendo_delegate`	a whole task handed to Vendo’s own agent, back as `{ status, summary, refs }`

Pass include or exclude to trim the pack by final tool name, exact match.

One Mastra definition serves every user, so its pack reads the caller off RequestContext per call instead. Mastra has that route.

Render the embeds

Vendo calls arrive in your chat as dynamic-tool parts. Hand the finished ones to <VendoToolResult>, anywhere under one provider.

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 (
    <VendoProvider baseUrl="/api/vendo">
      {messages.map((message) => message.parts.map((part, i) => {
        const key = `${message.id}-${i}`;
        if (part.type === "text") return <p key={key}>{part.text}</p>;
        if (part.type === "dynamic-tool" && part.state === "output-available") {
          return <VendoToolResult key={key} output={part.output} />;
        }
        return null;
      }))}
    </VendoProvider>
  );
}

Plain data

no envelopeYour model reads the result and answers in words.

App ref

vendo/app-ref@1A live app builds inline, streamed over the wire.

Approval ref

vendo/approval-ref@1An approve or deny card, resolving in place.

One component covers all three, so you never branch on the envelope yourself.

See it live

Run your own chat and ask for something behind your API. The answer comes back as a working card, inside your own bubble.

VENDO_BASE_URL in development — init already asked you for it. A vendo_* tool call is a real HTTP request back at your own API, so something has to name the origin to send it to. Vendo learns that origin from requests that reach the wire route init wrote — but on this path the tool runs in your chat route, which is not one of them, so the variable is what names it:

.env.local

VENDO_BASE_URL=http://localhost:<your-dev-port>

An interactive vendo init writes that line from your answer, prefilled with the port your dev script names. If init ran unattended it wrote nothing — add the line with the port your dev server actually prints. Without it, the first tool call comes back with Cannot execute … set VENDO_BASE_URL, or pass baseUrl, and forwarding the caller’s own credentials is refused. Deployments set the same variable in the hosting platform, to the public URL, path prefix included (environment variables).

A host's own chat thread where the assistant's answer is a working comparison screen rendered inside the message

Teach your model when to build UI

Your system prompt is yours, so nothing Vendo assembles reaches it. A tool your model never reaches for is not a feature, so paste this beside whatever you already say about your other tools.

your agent's system prompt

## Making the person a screen

You have `vendo_make`. It puts a real, live view in front of the person, and it
is the only way you can do that. You never build UI yourself.

USE IT when the honest answer is a shape, not a sentence: more than a handful of
rows, a comparison or trend or breakdown, something they will come back to
("track", "every week"), something they need to act on — a screen carries
buttons; your message cannot.

ANSWER IN WORDS when the answer IS words: one number, one status, one fact, a
yes or no, an explanation. A screen for "what's my balance" is worse than saying
the balance.

`request` is prose — what you would say to a designer sitting next to you.
- Describe the want: "the last three months of spending, broken down by
  category, with a way to jump into any month"
- No component names, no layout grids, no JSON, no field names you guessed at
- No fonts, colors, or branding: it inherits the product's own
- Never paste numbers you looked up or computed ("Total: $4,210"). The screen
  binds live data itself, and hardcoded figures are rejected as invented

`context`: background the product cannot see — what they told you earlier, a
constraint they mentioned, which of several things they meant. A sentence or two.

`app`: ONLY to change one view that already exists, by id or by its name exactly
as they said it. Leave it out and the product decides whether to continue the
last one or start something new, which is usually right.

`slot`: ONLY when they name a place in the product AND you have that place's
exact id — they said it, or an earlier answer carried it. Slot ids belong to the
product, not to you: NEVER invent one. A made-up id puts the screen where nobody
is looking, and that does not look like an error. No id, no `slot`, and it lands
in the person's own list of views.

WHAT COMES BACK is a receipt: id, title, status, and `say` — one line in the
person's voice. Say `say`, close to verbatim. That is the whole report. You never
get the screen; it goes from the server straight to their page, on a channel you
are not on. So:
- NEVER wait for it. Nothing to poll, nothing to check.
- NEVER describe it. You have not seen it. No sections, charts, colors, or
  buttons, and never tell them what to click.
- Never paste a link or an id unless they asked.
- status "failed": try once more on the same `app`, narrower, then stop and say
  so plainly.
- status "building": honest, not an error. Say the line and move on.
- status "partial": the screen is on their page, the server-side part of it is
  not. Say the line and offer to try that part again. Never rebuild it.

Those slot ids are yours to publish. A <VendoSlot id="…"> from @vendoai/vendo/react is a place in one of your own pages a generated view can occupy — without one, every screen lands in the person’s own list of views. Mount the surface has the component. The same guidance ships to Claude Code as a skill, examples/claude-code-plugin/skills/make-a-screen.

The in-process tool pack carries no vendo_apps_* tool. Teaching your model to pin or unpin a view here buys you an invented tool call that nothing answers.Pinning and unpinning live on the door your own agent connects to, in How the door works.

Where to go next

The pack is in your loop. These three are the rest of this track.

AI SDK

Per-request packs, dynamic-tool parts, one Next.js config line.vendoTools(vendo, { principal })

Mastra

A static definition, the request-context caller, warming the store.VENDO_PRINCIPAL_KEY

Embeds in your chat

The envelope your tools return, and the three embeds that render it.<VendoToolResult output={…} />

Get started

In your backend

Install with your agent

Vendo's Full-Stack Agent