Quickstart: your agent

Your loop, your model, your chat UI. Vendo adds a pack of guarded tools to them.

1. Init

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 that selects it, because a key sitting loose in the environment selects nothing. 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.

// 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,
});

// 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,
});

// 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.

// 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();
}

// 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
});

// 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 } });

// 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. Framework notes: AI SDK · Mastra.

4. Render the results

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

// 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>
  );
}

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:

npx vendo doctor

Next: embeds and envelopes.

Start here

You already have an agent

Your product has no agent

Outside agents over MCP

Agent SDK

Make it yours

Capabilities

Go to production

Concepts

Reference

Changelog

Quickstart: your agent

1. Init

3. Spread the pack

4. Render the results

5. Ask for a screen

​1. Init

​2. Share one instance

​3. Spread the pack

​4. Render the results

​5. Ask for a screen

1. Init

2. Share one instance

3. Spread the pack

4. Render the results

5. Ask for a screen