Documentation

Builder reference

Every Agent.builder() method, plugins, and the RunResult you get back.

The fluent builder is the primary API. Agent.create({ ... }) accepts the same fields as a config object. After .build(), the config is frozen.

Full builder

builder.ts

Agent.builder()
  .name("ops")
  .instructions("You operate internal tools.")
  .apiKey(process.env.OPENAI_API_KEY!)
  .baseURL(process.env.OPENAI_BASE_URL)
  .model("gpt-4.1")
  .modelRouter({ mode: "hybrid" })
  .provider(openai)
  .fallback(anthropic)
  .tools([search])
  .handoffs([billing])
  .maxHandoffs(3)
  .output(schema)
  .graph(true)
  .mcp()
  .memory({ provider: "in-memory" })
  .session(session)
  .security({ pii: { redact: true } })
  .inputGuardrails([]).outputGuardrails([]).toolGuardrails([])
  .maxTurns(8)
  .timeout(60_000)
  .retry({ maxAttempts: 3 })
  .temperature(0.2)
  .maxTokens(2048)
  .tracing({ enabled: true })
  .use(metricsPlugin)
  .feature("tenant", "acme")
  .build();

Method map

Method	What it does
`.name()` / `.instructions()`	Identity. Instructions may be a string or `(ctx) => string`.
`.apiKey()` / `.baseURL()`	OpenAI-compatible credentials and gateway.
`.model()` / `.modelRouter()`	Pin a model, or classify complexity and pick from a catalog.
`.provider()` / `.fallback()`	Primary `ModelProvider` and ordered backups.
`.tools()` / `.tool()`	Register Zod-validated functions the model can call.
`.handoffs()` / `.maxHandoffs()`	Specialists this agent may transfer to (default max 4).
`.output()`	Zod schema for structured JSON + repair turns.
`.graph()`	`true`, `false`, or a `GraphRuntime` / file graph.
`.mcp()`	Inherit MCP catalogs, filter servers, or disable.
`.memory()` / `.session()`	Long-term provider and short-term conversation store.
`.security()`	Tune or disable built-in jailbreak/PII/leak rails.
`.inputGuardrails()` / `.outputGuardrails()` / `.toolGuardrails()`	Custom rails by stage.
`.maxTurns()` / `.timeout()` / `.retry()`	Loop bounds and provider retries.
`.temperature()` / `.maxTokens()`	Sampling passed to the provider.
`.tracing()`	Enable traces and an `onEvent` sink.
`.use()` / `.feature()`	Plugins (`onBuild`, `onBeforeRun`, `onAfterModel`, `onAfterTool`, `onAfterRun`, `onError`) and feature flags.

Plugins hook onBuild, onBeforeRun, onAfterModel, onAfterTool, onAfterRun, onError.

Run options and result

run.ts

const result = await agent.run("Summarize the latest invoice", {
  userId: "cus_123",
  sessionId: "chat_9",
  metadata: { ticket: "T-204" },
  abortSignal: controller.signal,
  onEvent: (e) => {},
  approval: async () => true,
});

result.output;
result.outputParsed;
result.agentName;
result.handoffs;
result.model;
result.complexity;
result.usage;
result.turns;
result.durationMs;
result.runId;
result.guardrails;
result.traces;
result.events;
result.messages;

Defaults

maxTurns: 10
timeout: 120_000 ms
maxHandoffs: 4
structured repair attempts: 2
graph extract / relate / maintain: 250 / 400 / 2000 ms
security: on (jailbreak, injection, PII, leaks, size)
routing mode: hybrid (if .model() omitted)

Package

shirube-ai ships ESM + CJS + TypeScript declarations. Peer dependency: zod ^3.23 or ^4. Optional peer: mem0ai.

Tracing, reliability, and errors

Examples