> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vendo.run/llms.txt
> Use this file to discover all available pages before exploring further.
# In your backend
> One package, one agent() call, one tool. Answer in a line with chat(), put the same agent on HTTP with handler(), and drive unattended work with run().
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.
Install one package and write one `agent()` call at module scope. Only `name`
is required.
```bash npm theme={null}
npm install @vendoai/agents ai zod
```
```bash pnpm theme={null}
pnpm add @vendoai/agents ai zod
```
```ts lib/agent.ts focus={4-16} theme={null}
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.
`tool()` for your own code, `api()` for your existing HTTP API.
Risk grade, approval, and an audit row on every call.
Threads and audit rows. Embedded, your Postgres, or Cloud.
`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](/capabilities/api-tools).
`chat()` is one turn and the answer, with no route and no stream in the way.
```ts theme={null}
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:
```bash theme={null}
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:
```ts lib/agent.ts focus={1,6} theme={null}
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](/production/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](/backend/converse) covers both.
`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.
```ts app/api/agent/[[...path]]/route.ts focus={4-11} theme={null}
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:
```tsx app/support/page.tsx focus={3} theme={null}
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](/backend/converse) has both.
`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.
```ts app/api/reports/route.ts focus={10,15-18,29} theme={null}
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({
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](/backend/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
statusstarted
tool-calllistInvoices
tool-result42 rows
tool-callgetPayments
tool-result38 rows
textThree 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.
Threads, forwarded credentials, and approvals with a person present.
`support.chat(message)`
Typed output from a schema, plus the usage you meter on.
`await support.run(task)`
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`](https://github.com/runvendo/vendo/tree/main/examples/standalone-agent):
one `agent()`, one `tool()`, `chat()` in the terminal, and `handler()` on a
Node server.