@b4run/sdk

Use this when#Copy link to section: Use this when

Start here when you build a B4.run application. @b4run/sdk owns the route-authoring types and helpers most application code uses. Use /pure only when an integration needs dependency-free path or hash utilities, and /testing when you write route scenarios for b4 test.

Install and import#Copy link to section: Install and import

npm install @b4run/sdk

import { agent, defineMiddleware, defineMemory } from "@b4run/sdk"
import { pureJoin } from "@b4run/sdk/pure"
import { scenarios } from "@b4run/sdk/testing"

Compatibility and audience#Copy link to section: Compatibility and audience

@b4run/sdk/testing is the route-scoped scenario API used by b4 test. It's not the @b4run/testing package, which provides a programmatic agent harness.

Public exports#Copy link to section: Public exports

@b4run/sdk#Copy link to section: @b4run/sdk

@b4run/sdk/pure#Copy link to section: @b4run/sdk/pure

@b4run/sdk/testing#Copy link to section: @b4run/sdk/testing

@b4run/sdk/tool-step.schema.json#Copy link to section: @b4run/sdk/tool-step.schema.json

The JSON Schema of a b4.step value, as data for tooling and for producers in other languages. It is the same schema as B4_TOOL_STEP_JSON_SCHEMA. It has no TypeScript exports, runtime classification, or purity claim. Don't execute it as application code.

@b4run/sdk/answer.schema.json#Copy link to section: @b4run/sdk/answer.schema.json

The JSON Schema of b4.answer annotations, as data for tooling and for producers in other languages. It is the same schema as B4_ANSWER_JSON_SCHEMA. It has no TypeScript exports, runtime classification, or purity claim. Don't execute it as application code.

Key contracts#Copy link to section: Key contracts

agent() and AgentConfig#Copy link to section: agent() and AgentConfig

Use agent() as a route module's default export. model and systemPrompt are required. Optional policy, retry, reasoning, subagent, and tool fields are preserved on the branded descriptor.

export declare function agent<const Subagents extends SubagentMap = {}>(
  config: AgentConfig<Subagents>,
): B4Agent<Subagents>

export interface AgentConfig<Subagents extends SubagentMap = {}> {
  readonly delegation?: DelegationConfig<NoInfer<Extract<keyof Subagents, string>>>
  readonly description?: string
  readonly model: KnownModelId
  readonly provider?: ModelProviderId
  readonly reasoning?: ReasoningConfig
  readonly retry?: RetryConfig
  readonly recursionLimit?: number
  readonly subagents?: Subagents
  readonly tools?: ToolScope
  readonly systemPrompt: string
}

Fields: @b4run/sdk#.:AgentConfig

Behavior contract sdk.agent.descriptor-shape

agent() returns a branded descriptor and includes optional tool scope only when supplied.

Agent configuration signatures

export interface ReasoningConfig {
  readonly openai?: OpenAIReasoningConfig
  readonly anthropic?: AnthropicReasoningConfig
}

Fields: @b4run/sdk#.:ReasoningConfig

export interface OpenAIReasoningConfig {
  readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh"
  readonly summary?: "auto" | "concise" | "detailed"
}

Fields: @b4run/sdk#.:OpenAIReasoningConfig

export interface AnthropicReasoningConfig {
  readonly budgetTokens: number
}

Fields: @b4run/sdk#.:AnthropicReasoningConfig

export interface RetryConfig {
  readonly maxAttempts?: number
  readonly baseDelay?: number
}

Fields: @b4run/sdk#.:RetryConfig

export declare function isB4Agent(value: unknown): value is B4Agent

allow() and reject()#Copy link to section: allow() and reject()

Middleware returns an explicit continue or reject result. Use allow(context?) to continue and reject(status, body?) to stop the request.

defineMiddleware accepts either the handler function or a lifecycle definition with optional setup(ctx) and dispose() hooks around handle. setup runs once, lazily, before the first gated request and is retried on the next request if it rejects. dispose runs from the Node runtimes' shutdown path. See Lifecycle hooks. The definition may also carry after(run), which receives an AG-UI run's final assistant message with the allowed context and may keep, replace, or reject(...) it before the client sees it. See Validating the final assistant message.

export declare function defineMiddleware<T extends B4Middleware>(middleware: T): T

export declare function allow(context?: Record<string, unknown>): ContinueResult

export declare function reject(status: number, body?: unknown): RejectResult

Behavior contract sdk.middleware.result-shapes

allow() and reject() return discriminated result objects; omitted context and body properties are absent.

defineAuth()#Copy link to section: defineAuth()

src/auth.ts must default-export the result. authenticate runs once per request, before middleware and the thread-access policy, and its principal reaches middleware and the policy as req.principal and every tool as ctx.principal. See Authentication.

export declare function defineAuth<P extends B4PrincipalShape>(definition: AuthDefinition<P>): AuthDefinition<P>
export declare function isAuthDefinition(value: unknown): value is AuthDefinition

validateModelId()#Copy link to section: validateModelId()

Flags likely model-ID typos. It does not restrict custom model IDs.

export declare function validateModelId(opts: {
  readonly model: string
  readonly provider?: string
}): ModelIdValidation

Behavior contract sdk.validate-model-id.advisory

Model validation is advisory: curated near-misses return provider-specific suggestions, while an uncurated or unresolved provider returns ok: true.

Application guidance

Treat ok: false as a warning for application feedback, not a runtime gate.

RouteConfig#Copy link to section: RouteConfig

runtime, streaming, and tags are reserved metadata and don't change execution. Select deployment runtime with build.targets, select streaming through the endpoint or transport, and do not rely on tags for behavior.

export interface RouteConfig {
  readonly runtime?: "node" | "edge"
  readonly streaming?: boolean
  readonly tags?: readonly string[]
}

Fields: @b4run/sdk#.:RouteConfig

defineMemory()#Copy link to section: defineMemory()

Declare the typed schema, kind, and namespace dimensions for a route's memory.ts module. identity is optional. Semantic memory defaults its reconciliation identity elsewhere.

export declare function defineMemory<S extends z.ZodTypeAny>(def: {
  kind: DefinedMemory["kind"]
  scope: readonly MemoryScopeDimension[]
  schema: S
  identity?: readonly string[]
}): DefinedMemory<S>

Choosing a surface#Copy link to section: Choosing a surface

Application routes normally import the root. Use /pure for infrastructure that must avoid runtime dependencies. Use /testing in *.scenario.ts files, and @b4run/testing when a test needs a programmatic harness.

Trusted initial source#Copy link to section: Trusted initial source

An authored tool's optional ctx.workspace is present only for an admitted managed workspace. It exposes id, sourceDigest, the pinned environment, an optional baselineCommit, and readInitialFile(path): Promise<Uint8Array>. Initial reads use the same read permission policy as ordinary file reads and return independently owned bytes. The context has no provider handle or lifecycle methods and cannot select another thread's source.

Use ctx.fs for current files. ctx.fs.stat(path) inspects entry kind, size, executable mode, and a symlink's target without following the leaf link; custom backends must supply lstat to support it.

Examples and related guides#Copy link to section: Examples and related guides

import { agent } from "@b4run/sdk"
 
export default agent({
  model: "gpt-5-mini",
  systemPrompt: "Answer concisely.",
})

Continue with Agents, Middleware, Long-term Memory, Scenario Testing, and Agent Test Harness.