In your backend

A governed agent in any Node backend, from an empty project. One package, no CLI, no init, no files moved around. The UI stays yours.

Compose the agent

Install one package and write one agent() call at module scope. Only name is required.

npm install @vendoai/agents ai zod

pnpm add @vendoai/agents ai zod

lib/agent.ts

import { agent, tool } from "@vendoai/agents";
import { z } from "zod";

export const support = agent({
  name: "support",
  instructions: "Answer in the product's voice; never invent account numbers.",
  tools: [
    tool({
      name: "order_status",
      description: "Look up one order by id and return its shipping status and ETA.",
      risk: "read",
      inputSchema: z.object({ orderId: z.string() }),
      execute: ({ orderId }) => lookupOrder(orderId),
    }),
  ],
});

description is required, and it is the only thing the model reads when it decides whether to call the tool. risk is read, write, or destructive, and your label is final. Grade it: leave risk off and the tool is ungraded, which the guard asks a person about every time — so the very first chat() comes back interrupted with nothing run.Nothing else is configured. Left unset, the agent thinks in this process, and threads and audit rows are persisted automatically, with zero setup.

tools

tool() for your own code, api() for your existing HTTP API.

guard

Risk grade, approval, and an audit row on every call.

store

Threads and audit rows. Embedded, your Postgres, or Cloud.

harness

vendo() by default, claudeCode() on request.

Already have an HTTP API? vendo init reads it into tool definitions and tools: [api()] hands the whole thing to the agent, graded, in one line. It is an addition to this page, not a prerequisite for it — see API tools.

Ask it something

chat() is one turn and the answer, with no route and no stream in the way.

const turn = await support.chat("Where is order A-1001?");

console.log(turn.text);

That is the whole hello world. The agent needs a model to think with, and the shortest way to give it one is npx vendoai@latest login, which mints a VENDO_API_KEY into .env.local and never prints it..env.local is a Next.js convention, and nothing in @vendoai/agents reads it. A plain Node backend — which this page is — has to be handed the variable:

node --env-file=.env.local ./dist/chat.js   # or: export VENDO_API_KEY=…

To bring your own model instead, install @ai-sdk/anthropic — the major that pairs with your ai, 4 with ai@7 and 3 with ai@6 — and pass it beside name. That is two lines:

lib/agent.ts

import { anthropic } from "@ai-sdk/anthropic";
import { agent } from "@vendoai/agents";

export const support = agent({
  name: "support",
  model: anthropic("claude-sonnet-4-6"),
});

Either way the credential is read at the first turn, never at build time — see Model credentials.turn is a TurnResult: read status once and everything you then touch is there. ok carries the typed output; interrupted carries the interruptions a person has to answer and a resume() that carries on from where the turn parked. Converse covers both.

Put it on HTTP

handler() is the whole agent as one fetch handler — the chat turn, the thread list and transcript, and the approvals wire. Mount it on one catch-all route.

app/api/agent/[[...path]]/route.ts

import { support } from "@/lib/agent";
import { auth } from "@/lib/auth";

const handle = support.handler({
  basePath: "/api/agent",
  // Your session, read per request. `null` answers 401.
  resolveUser: async (request) => {
    const user = await auth(request);
    return user === null ? null : { subject: user.id };
  },
});

export { handle as GET, handle as POST, handle as DELETE };

In the browser, useVendoChat from @vendoai/ui speaks to that mount and keeps nothing of its own:

app/support/page.tsx

import { useVendoChat } from "@vendoai/ui";

const { messages, sendMessage, interruptions, resume } = useVendoChat({
  api: "/api/agent",
});

Render messages however your app renders anything else, and interruptions as approve/deny cards that call resume.

Prefer to own the route yourself? respond() is one turn as a streamed Response you return unchanged, and it is not going anywhere. Converse has both.

Run unattended work

run() is work nobody is watching. The same object is awaitable and iterable, so run.events is the live feed and awaiting it is the result.

app/api/reports/route.ts

import { THREAD_ID_HEADER } from "@vendoai/agents";
import { support } from "@/lib/agent";
import { auth } from "@/lib/auth";

export async function POST(req: Request) {
  const user = await auth(req);
  if (user === null) return new Response("unauthorized", { status: 401 });
  const { brief } = (await req.json()) as { brief: string };

  const run = support.run(brief, { as: user.id, signal: req.signal });

  const encoder = new TextEncoder();
  const stream = new ReadableStream<Uint8Array>({
    async start(controller) {
      for await (const event of run.events) {
        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
      }
      const result = await run;
      controller.enqueue(
        encoder.encode(`event: result\ndata: ${JSON.stringify(result)}\n\n`),
      );
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "content-type": "text/event-stream",
      [THREAD_ID_HEADER]: run.threadId,
    },
  });
}

run.threadId is there before the first event, so the header goes out with the response. signal: req.signal ties the run to the connection, and closing the tab stops it.

Away, the menu is already narrower: destructive and ungraded tools are never offered, and a read or write call still needs authority a person captured while they were present — a grant. Without one the call parks, and the run comes back interrupted carrying the cards for someone to answer. Run covers what an unattended run may touch.

One run, seen from your own UI

Events leave your server on the left. Your own progress screen fills on the right.

POST /api/reports · text/event-stream

status started
tool-call listInvoices
tool-result 42 rows
tool-call getPayments
tool-result 38 rows
text Three invoices are overdue.
resultok · 4 tool calls

app.maple.com/reports

Monthly closeDone

August 20264 steps

✓ Pulled invoices 42

✓ Matched payments 38

✓ Drafted the summary 1

Overdue3 invoices

$12,480

your chrome, not Vendo’s

Where to go next

Every verb in depth, and the surface you build around them.

Converse

Threads, forwarded credentials, and approvals with a person present.support.chat(message)

Run

Typed output from a schema, plus the usage you meter on.await support.run(task)

Your own surface

Forward the event feed over SSE and end on the result.for await (const e of run.events)

The whole of this page as a project you can run is examples/standalone-agent: one agent(), one tool(), chat() in the terminal, and handler() on a Node server.

Get started

In your backend

Install with your agent

Vendo's Full-Stack Agent

In your existing agent

From outside agents

Generated UI & apps

Make it yours

Capabilities

Production

Users & orgs

In your backend

tools

guard

store

harness

One run, seen from your own UI

Where to go next

Converse

Run

Your own surface

tools

guard

store

harness

​One run, seen from your own UI

​Where to go next

Converse

Run

Your own surface

One run, seen from your own UI

Where to go next