Agent SDK reference: agent, respond, run, session

Everything on this page is exported from @vendoai/agents.

import { agent, api, e2b, postgres, tool, THREAD_ID_HEADER } from "@vendoai/agents";
import type {
  AgentConfig, AgentReport, AgentRun, AgentSession, ApiOptions, ApprovalEvent,
  HostTool, McpServerConfig, RespondOptions, RunEvent, RunOptions, SessionOptions,
  ToolConfig, ToolSource, UsageTotals, VendoAgent,
} from "@vendoai/agents";

`agent(config)`

export function agent(config: AgentConfig): VendoAgent;

Key	Type	Notes
`name`	`string`	required. Attributes audit rows and the inbox
`harness`	`Harness`	who thinks. Unset → `vendo()`, the in-process loop; also `claudeCode()`, or your own via `defineHarness`
`model`	`LanguageModel`	the `default` seat `vendo()` thinks with. `claudeCode()` brings its own brain and ignores it
`tools`	`readonly ToolSource[]`	`api()`, `tool()`, or any `ToolRegistry`. A name collision is a boot error, never a silent shadow
`mcp`	`readonly McpServerConfig[]`	external MCP servers as tool sources
`guard`	`VendoGuard \| GuardRules`	a built guard wins verbatim; rules are completed with this composition’s store. Unset → `createGuard({ store })`
`skills`	`readonly string[]`	skill folders, boot-loaded and mounted read-only at `/host/skills`
`egress`	`EgressConfig`	outbound allowlist for the box; unset = the harness’s minimum
`store`	`VendoStore`	unset alone → embedded. There is no Cloud store rung today, so unset + `VENDO_API_KEY` is a boot error naming `postgres(url)`
`sandbox`	`SandboxAdapter`	`e2b()`, or unset + `VENDO_API_KEY` → the Cloud pool. Required by a harness declaring `requires.sandbox`
`door`	`DoorConfig`	where a thinker running outside this process dials back for tools; unset → `VENDO_BASE_URL`
`instructions`	`string`	the host’s prompt block
`system`	`SystemPromptHook`	the last word on the per-turn system prompt; `undefined` means the default assembly

The smallest useful composition is two keys:

const support = agent({ name: "support", tools: [api()] });

Credentials

One ladder, everywhere: what you pass always wins, and VENDO_API_KEY fills only the slots you left unset. There are no key-conditional branches and no capability checks — a key problem surfaces on the first real service call.

`VendoAgent`

export interface VendoAgent {
  readonly name: string;
  respond(subject: string, message: string | UIMessage, options?: RespondOptions): Promise<Response>;
  run<T>(task: string, options?: RunOptions<T>): AgentRun<T>;
  session(subject: string, options?: SessionOptions): Promise<AgentSession>;
  readonly door?: (request: Request) => Promise<Response>;
}

door is present exactly when the harness thinks outside this process (requires.toolDoor). Mount it at DOOR_PATH (/api/vendo/mcp).

`respond`

One turn for a waiting person. Returns an AI-SDK UI-message-stream Response with x-vendo-thread-id set.

export interface RespondOptions {
  threadId?: string;
  headers?: Record<string, string> | Headers;
  user?: Record<string, Json>;
  context?: Record<string, unknown>;
  signal?: AbortSignal;
}

Key	Notes
`threadId`	reopen this conversation. Ownership-checked against the same subject; a foreign or unknown id is `not-found`, never a silent new conversation
`headers`	the request’s own headers, forwarded so tool calls reach your API as the signed-in person
`user`	server-trusted identity facts, model-visible as `[User]`
`context`	guard and tool context: functions run at check-time, data survives parking
`signal`	abort the turn

It is session(subject, options) plus stream(message) collapsed into one call, with the header stamped. session() is unchanged and still available for a host that wants the session object — and session.stream() now stamps the same header.

`run`

One non-interactive run.

export interface RunOptions<T> {
  as?: string;
  user?: Record<string, Json>;
  context?: Record<string, unknown>;
  output?: FlexibleSchema<T>;
  maxToolCalls?: number;
  signal?: AbortSignal;
  threadId?: string;
}

Key	Notes
`as`	the subject this run acts as. Give unattended work its own service subject
`user`	server-trusted identity facts, model-visible
`context`	guard and tool context
`output`	an AI-SDK `FlexibleSchema` (a zod schema, typically). The result is validated; `T` is inferred. Unset costs nothing
`maxToolCalls`	bounded at the guard — spent, further calls are refused before the registry. Default 20
`signal`	the only way to cancel. There is no `cancel()` method
`threadId`	continue an existing thread. Ownership-checked against the same subject; otherwise `not-found`

`AgentRun`

export interface AgentRun<T> extends PromiseLike<AgentReport<T>> {
  readonly threadId: string;
  readonly events: AsyncIterable<RunEvent>;
}

threadId is readable immediately, before the first event. Awaiting the run gives the report; iterating events does not consume it.

`RunEvent`

`type`	What it marks
`text`	the model’s own words, streaming
`status`	where the run is
`tool-call`	a tool the run is about to use
`tool-result`	what that tool answered
`error`	the run failed, with the harness’s own sentence

`AgentReport`

export interface AgentReport<T> {
  status: "ok" | "error" | "stopped";
  summary: string;
  toolCalls: readonly { call: ToolCall; outcome: ToolOutcome["status"] }[];
  refs: { threadId: string; approvals: readonly string[] };
  output?: T;
  usage: UsageTotals;
}

status — "stopped" covers an aborted run and one that spent its maxToolCalls budget. Both still return a full report.
summary — the model’s own closing account, never a sentence of Vendo’s.
refs.approvals — the ids of approvals this run parked. See below.
usage — { inputTokens, outputTokens, cacheReadTokens?, cacheWriteTokens?, model? }. This is what you meter on.

Approvals inside `run`

An ask inside a non-interactive run() parks the approval durably, and the tool call returns denied with the approval’s id. The run continues with that answer and finishes normally. There is no resume. report.refs.approvals is the list of ids to put in front of a human; once someone has decided, re-entry is a fresh run(). The interactive lane is unchanged: a turn driven by respond() waits about 90 seconds for the person to decide, and an approved call re-dispatches byte-for-byte.

Follow-ups

The follow-up to a run() is the same verb plus the thread id:

const next = await support.run("Now shorten it to five bullets.", {
  as: "svc:nightly-digest",
  threadId: first.refs.threadId,
});

Never respond() — that lane opens a turn that will wait on a human who is not there.

`session`

Unchanged. session(subject, options) returns an AgentSession with a threadId, a stream(message, options) that returns a UI-message-stream Response (now carrying x-vendo-thread-id too), and on("approval", handler) for present-user decisions. SessionOptions is { user?, context?, headers?, threadId? }.

Tools

export function api(options?: ApiOptions): ToolRegistry;
export function tool(config: ToolConfig): HostTool;

api() serves .vendo/tools.json with layered overrides, present-header forwarding behind the origin gate, and actAs for away runs ({ dir?, actAs?, baseUrl?, untrustedOriginPolicy?, fetch? }). tool() takes { name, description?, risk?, inputSchema, execute }. risk is your call and it is final — read, write, or destructive. Omit it and the tool is ungraded, which the guard treats like destructive and asks about, which unattended means denied.

Adapters

export function postgres(url: string, options?: PostgresOptions): VendoStore;
export function e2b(options?: E2bOptions): SandboxAdapter;

postgres(url, { blobs?, encryption?, allowUnencryptedSecrets? }) — the blob adapter rides beside the store it was configured with. e2b({ apiKey?, template?, timeoutMs? }) reads E2B_API_KEY as its credential; the harness’s own template always wins over the adapter’s.

Constants

Export	Value
`THREAD_ID_HEADER`	`"x-vendo-thread-id"` — set on every `respond()` and `session.stream()` response
`DOOR_PATH`	`"/api/vendo/mcp"` — where to mount `agent.door`

Tools and safety

Risk grading, guard.bind, approvals, and away-run scopes.

How Vendo works

Where @vendoai/agents sits among the blocks.

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 reference: agent, respond, run, session

`agent(config)`

Credentials

`VendoAgent`

`respond`

`run`

`AgentRun`

`RunEvent`

`AgentReport`

Approvals inside `run`

Follow-ups

`session`

Tools

Adapters

Constants

Tools and safety

How Vendo works

​agent(config)

​Credentials

​VendoAgent

​respond

​run

​AgentRun

​RunEvent

​AgentReport

​Approvals inside run

​Follow-ups

​session

​Tools

​Adapters

​Constants

Tools and safety

How Vendo works

`agent(config)`

Credentials

`VendoAgent`

`respond`

`run`

`AgentRun`

`RunEvent`

`AgentReport`

Approvals inside `run`

Follow-ups

`session`

Tools

Adapters

Constants