Agent SDK: a governed agent in any Node backend

@vendoai/agents is Vendo’s agent runtime on its own: your tools, one guard, one store, and a brain — with none of the umbrella’s client surface. You compose it once and reach it through exactly two verbs.

Verb	For	Shape
`respond(subject, message)`	a person waiting on a reply	one turn, streamed back as a `Response`
`run(task, options)`	work nobody is watching	one non-interactive run, awaited or streamed

Everything else — approvals, risk grading, audit, threads — is the same guard the rest of Vendo runs through. There is no second authority path.

Install

npm install @vendoai/agents ai
npx vendo init

vendo init writes .vendo/tools.json — your API read into tool definitions, each with a schema, a risk grade, and its dispatch binding — which is what api() serves. Full inventory: vendo init.

Compose it

Seven lines, and only name is required:

// lib/agent.ts
import { agent, api } from "@vendoai/agents";

export const support = agent({
  name: "support",
  instructions: "Answer in the product's voice; never invent account numbers.",
  tools: [api()],
});

harness is optional and defaults to vendo(), the in-process loop. Pass claudeCode() instead when you want Claude Code thinking on a sandbox machine — see Reference.

Answer a person

respond() is one turn: an AI-SDK UI-message-stream Response, ready to return from a route as-is.

// app/api/support/route.ts
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 { message } = (await req.json()) as { message: string };
  return support.respond(user.id, message, { headers: req.headers });
}

The response carries x-vendo-thread-id. Send it back as threadId on the next turn and the conversation continues — see Converse.

Two credential paths

Pick one. They are the same ladder everywhere in Vendo: what you pass always wins, and VENDO_API_KEY fills only the slots you left unset.

Vendo Cloud — vendo login

npx vendo login

Mints a VENDO_API_KEY into .env.local — never printed. It fills the model seat (through the Cloud gateway) and the sandbox. The store is not one of them: there is no Cloud store rung today, so with a key set you pass one — store: postgres(url) — or agent() refuses to boot.

No Vendo key — bring your own

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

export const support = agent({
  name: "support",
  model: anthropic("claude-sonnet-4-6"),
  store: postgres(process.env.DATABASE_URL!),
  tools: [api()],
});

Your own model key and your own store — no Vendo key anywhere. Drop store and you get the embedded one instead. ANTHROPIC_API_KEY is what the provider you construct authenticates with. It selects nothing on its own.

model is the default seat the built-in vendo() harness thinks with. claudeCode() brings its own brain and ignores it.

Testing

Swap the brain for a scripted one. defineHarness is the same authoring seam a real harness uses, so nothing else in the composition changes — the guard, the tools, and the store are all the ones that ship.

// support.test.ts
import { agent } from "@vendoai/agents";
import { defineHarness } from "@vendoai/harnesses";
import { expect, it } from "vitest";

const scripted = defineHarness({
  name: "scripted",
  async *run() {
    yield { type: "text" as const, delta: "Two invoices are outstanding." };
  },
});

it("reports what the brain said", async () => {
  const support = agent({ name: "support", harness: scripted, tools: [] });

  const report = await support.run("Check the invoices.", { as: "user:test" });

  expect(report.status).toBe("ok");
  expect(report.summary).toBe("Two invoices are outstanding.");
});

defineHarness lives in @vendoai/harnesses. Add it as a devDependency — under strict package linking, importing from a package you have not declared is a TS2307.

The three jobs

Converse with a user

respond() behind a chat route, with your API as tools and a risk-labeled write of your own.

Call it like a function

run() with an output schema returns typed data, and usage is what you meter on.

Ship it as a product surface

Forward run.events to your own UI over SSE and end on the report.

Reference

Every option, every field, every exported name.

Tools and safety

Risk labels, approvals, grants, and the audit trail behind both verbs.

Start here

You already have an agent

Your product has no agent

Agent SDK

Expose your product over MCP

Connect your app

Your brand and your rules

What the agent can do

Go to production

Installing with a coding agent

Reference

Changelog

Agent SDK: a governed agent in any Node backend

Install

Compose it

Answer a person

Two credential paths

Vendo Cloud — vendo login

No Vendo key — bring your own

Testing

The three jobs

Converse with a user

Call it like a function

Ship it as a product surface

Reference

Tools and safety

​Install

​Compose it

​Answer a person

​Two credential paths

Vendo Cloud — vendo login

No Vendo key — bring your own

​Testing

​The three jobs

Converse with a user

Call it like a function

Ship it as a product surface

Reference

Tools and safety

Install

Compose it

Answer a person

Two credential paths

Testing

The three jobs