An agent framework, the way I'd build it.

Ridiculous speed.
Readable code.

Write the agent in TypeScript, give it tools, and set its limits.
You ship code you can actually read.

Runs on LangGraph.js. You keep the graph.

Get started →

npm create b4-app@latest my-agent

Created my-agent (basic template)

my-agent/

AGENTS.md, guide for your coding agent
b4.config.ts, runtime
src/app/hello/, the agent
- index.ts, model + prompt
- tools/greet.ts, a typed tool
- evals/smoke.eval.ts, behavior check
test/agent.test.ts, passes, no API key

cd my-agent && npm install && npm test

Your first agent

An agent is a folder.

Every file in src/app/hello/ is a feature. The scaffold starts you with three. Add a file and the agent gets the tools that come with it.

my-agent/src/app/hello/

src/app/hello/index.tsscaffolded

One export is the agent.

index.ts picks the model and writes the system prompt. Every TypeScript file in tools/ becomes one of its tools.

Agents →

src/app/hello/index.ts

1import { agent } from "@b4run/sdk"2 3export default agent({4  model: "gpt-5-mini",5  systemPrompt: "You are a friendly assistant. Use greet to greet people by name.",6})

src/app/hello/tools/greet.tsscaffolded

Your types are the tool schema.

The file name is the tool's name, and the JSDoc above it is the description. B4 reads the input type and writes the JSON schema the model sees.

Tool descriptions →

src/app/hello/tools/greet.ts

/** Greet someone by name. */export default async (input: { readonly name: string }) => {  return { message: `Hello, ${input.name}!` }}

export default async (input: { readonly name: string }) => {  return { message: `Hello, ${input.name}!` }}

/** Greet someone by name. */export default async (input: { readonly name: string; readonly language: "en" | "es" }) => {  return { message: `Hello, ${input.name}!` }}

export default async (input: { readonly name: string; readonly language: "en" | "es" }) => {  return { message: `Hello, ${input.name}!` }}

/** Greet someone by name. */export default async (input: { readonly name: string; readonly formal?: boolean }) => {  return { message: `Hello, ${input.name}!` }}

export default async (input: { readonly name: string; readonly formal?: boolean }) => {  return { message: `Hello, ${input.name}!` }}

/** Greet someone by name. */export default async (input: {  readonly name: string  readonly formal?: boolean  readonly language: "en" | "es"}) => {  return { message: `Hello, ${input.name}!` }}

export default async (input: {  readonly name: string  readonly formal?: boolean  readonly language: "en" | "es"}) => {  return { message: `Hello, ${input.name}!` }}

What the model sees

 {   "name": "greet",   "description": "Greet someone by name.",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" }     },     "required": ["name"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" }     },     "required": ["name"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "Greet someone by name.",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "language": { "type": "string", "enum": ["en", "es"] }     },     "required": ["name", "language"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "language": { "type": "string", "enum": ["en", "es"] }     },     "required": ["name", "language"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "Greet someone by name.",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "formal": { "type": "boolean" }     },     "required": ["name"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "formal": { "type": "boolean" }     },     "required": ["name"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "Greet someone by name.",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "formal": { "type": "boolean" },       "language": { "type": "string", "enum": ["en", "es"] }     },     "required": ["name", "language"],     "additionalProperties": false   } }

 {   "name": "greet",   "description": "",   "parameters": {     "type": "object",     "properties": {       "name": { "type": "string" },       "formal": { "type": "boolean" },       "language": { "type": "string", "enum": ["en", "es"] }     },     "required": ["name", "language"],     "additionalProperties": false   } }

src/app/hello/plan.md+ added

Add plan.md and it plans.

A markdown checklist next to index.ts turns planning on and seeds the todo list. The agent gets a writeTodos tool to keep the list current.

Planning →

src/app/hello/plan.md

1- [ ] Understand the customer request2- [ ] Check account context3- [ ] Decide whether to answer or escalate4- [ ] Write the final response

src/app/hello/memory.ts+ added

Add memory.ts and it remembers.

defineMemory declares the shape of the records and where they are scoped. The agent gets remember and recall tools typed from your schema.

Long-term memory →

src/app/hello/memory.ts

1import { defineMemory } from "@b4run/sdk"2import { z } from "zod"3 4export default defineMemory({5  kind: "semantic",6  scope: ["workspace", "route"],7  schema: z.object({8    subject: z.string(),9    predicate: z.string(),10    value: z.string(),11  }),12})

src/app/hello/skills/greetings/SKILL.md+ added

Add a skill for long instructions.

The model sees each skill's description, not its body. It loads the full text only when it needs it, with readSkill.

Skills →

src/app/hello/skills/greetings/SKILL.md

1---2description: How to greet someone formally or for the time of day.3---4 5Use this skill when the user asks for a formal greeting or one that fits the time of day.6 71. Say "Good morning", "Good afternoon" or "Good evening" for the local time.82. For a formal greeting, use the person's title and family name.93. Keep the greeting to one sentence.

src/app/hello/subagents/translator/index.ts+ added

Add a subagent to hand work off.

A folder under subagents/ is a full agent with its own prompt and tools. The parent gets a task tool and uses each description to decide when to delegate.

Subagents →

src/app/hello/subagents/translator/index.ts

1import { agent } from "@b4run/sdk"2 3export default agent({4  model: "gpt-5-mini",5  description: "Translate a short greeting into the language the user asks for.",6  systemPrompt: "You translate greetings. Reply with the translation only.",7})

src/app/hello/evals/smoke.eval.tsscaffolded

The scaffold ships an eval.

smoke.eval.ts replays a scripted reply and scores it, so npm run eval needs no API key. Run npm run eval -- --live to try the real model.

Evals →

src/app/hello/evals/smoke.eval.ts

1import { contains, defineEval } from "@b4run/evals"2import { script } from "@b4run/testing"3 4export default defineEval({5  name: "greets by name",6  dataset: [7    {8      name: "ada",9      input: "Say hello to Ada",10      fixtures: script().user("Say hello to Ada").replies("Hello, Ada!"),11    },12  ],13  scorers: [contains("Hello", { threshold: 1 })],14  threshold: 1,15})

Guardrails

Four checks decide what a call can do.

Tool scope, permissions, the sandbox and delegation each answer one question. Pick a call this support agent might make and see which checks it meets.

Pick a call the support agent makes

1 · Tool scope passedreadFile comes with the workspace, and deny doesn't name it.
2 · Permission passedA path inside the workspace needs no approval.
3 · Sandbox containedIt reads the file inside the sandbox container.
4 · Delegation not involvedOnly a task call to a subagent reaches this check.

readFile runs inside the sandbox, and no one is asked.

1 · Tool scope passedrunBash comes with the workspace.
2 · Permission passedAllowed once. No allow rule is saved.
3 · Sandbox containedNetwork mode "deny": Docker starts the sandbox container with --network none, so it has no network at all.
4 · Delegation not involvedOnly a task call to a subagent reaches this check.

The command runs inside the sandbox, where curl can't reach example.com, so the download fails.

src/app/support/index.ts

 import { agent, type DelegationConstraintPredicate } from "@b4run/sdk" import translator from "./subagents/translator/index.js"   // The translator gets one reply at a time, never a whole thread. const oneReply: DelegationConstraintPredicate = ({ input }) =>   input.length <= 2_000 || "Send the translator one reply at a time."   export default agent({   model: "gpt-5-mini",   systemPrompt: "You answer support questions. Refund an order only when the policy allows it.",   tools: {›    approve: ["refund"],›    deny: ["deleteUser"],   },   subagents: { translator },   delegation: {     rules: { translator: { action: "constrain", predicate: oneReply } },   }, })

b4.config.ts

 import { config } from "@b4run/cli" import { dockerSandbox } from "@b4run/sandbox"   export default config({   // No bash allow rules: an unknown command pauses for a person.   permissions: { mode: "interactive" },   sandbox: {     provider: dockerSandbox({ scope: "my-agent", image: "node:24-slim" }),     network: { mode: "deny" },   }, })

Neither tools list names readFile, and a path inside the workspace needs no approval.Workspace permissions →

Access control →

You keep the graph

Pick the shape per route.

A route's index.ts exports one of four shapes. Let the model drive with an agent, or write the steps yourself as a workflow, a LangGraph graph or a chain.

Route shapeagentworkflowgraphchain

src/app/hello/index.ts

import { agent } from "@b4run/sdk" export default agent({  model: "gpt-5-mini",  systemPrompt: "You are a friendly assistant. Use greet to greet people by name.",})

import type { RuntimeContext, RuntimeTool } from "@b4run/sdk" // Or use RouteTools from "b4:routes", which b4 typegen writes for you.type Tools = {  readonly greet: RuntimeTool<{ readonly name: string }, { readonly message: string }>} export async function workflow(input: { readonly name: string }, ctx: RuntimeContext<Tools>) {  const name = input.name.trim()  const { message } = await ctx.tools.greet({ name })  return { message }}

import { Annotation, END, START, StateGraph } from "@langchain/langgraph" const Hello = Annotation.Root({  name: Annotation<string>,  message: Annotation<string>,}) export const graph = new StateGraph(Hello)  .addNode("greet", (state) => ({ message: `Hello, ${state.name}!` }))  .addEdge(START, "greet")  .addEdge("greet", END)  .compile()

import { RunnableSequence } from "@langchain/core/runnables" export const chain = RunnableSequence.from([  (input: { readonly name: string }) => input.name.trim(),  (name: string) => ({ message: `Hello, ${name}!` }),])

export default agent({ … })The model decides which tools to call, and when.Agents →

export async function workflow(input, ctx)You write the steps, and the route's tools are plain function calls.Workflows →

export const graph = new StateGraph(…).compile()Raw LangGraph, with your own state, nodes and edges.Graphs →

export const chain = RunnableSequence.from([…])One LangChain chain that runs its steps in order.Chains →

Routes →Migrating from LangGraph →

Test and ship

Test it offline, then pick where it runs.

The scaffold's test and eval answer from script() fixtures instead of a model, so they need no API key. One line of b4.config.ts picks what b4 build emits.

npm test and b4 eval

Recorded in a fresh scaffold, with no OPENAI_API_KEY set.

my-agent

$ npm test -- --reporter=verbose> test> vitest run --reporter=verbose  RUN  v4.1.11 my-agent  ✓ test/agent.test.ts > greets by name  Test Files  1 passed (1)      Tests  1 passed (1)$ npx b4 evalPASS greets by name › ada mean=1.00 [contains(Hello)=1.00]PASS greets by name mean=1.00

b4 build

node and langsmith are the defaults. Setting build.targets replaces them.

b4.config.ts

import { config } from "@b4run/cli" export default config({  build: { targets: ["node"] },})

$ npx b4 buildBuild complete: .b4/build  1 route(s) compiled  targets: node  wrote .b4/build/workspace.json  wrote .b4/build/modules.mjs  wrote .b4/build/server.mjs  wrote Dockerfile

The full B4 HTTP runtime as a Node server, with a Dockerfile.Node and Docker →

b4.config.ts

import { config } from "@b4run/cli" export default config({  build: { targets: ["langsmith"] },})

$ npx b4 buildBuild complete: .b4/build  1 route(s) compiled  targets: langsmith  wrote .b4/build/hello.ts  wrote .b4/build/langgraph.json

A langgraph.json and one graph entry per route, for LangSmith to run.LangSmith →

b4.config.ts

import { config } from "@b4run/cli" export default config({  build: { targets: ["hono"] },})

$ npx b4 buildBuild complete: .b4/build  1 route(s) compiled  targets: hono  wrote .b4/build/modules.edge.mjs  wrote .b4/build/stores.mjs  wrote .b4/build/app.mjs  wrote wrangler.toml

A Hono app over the web-standard runtime. It serves the edge subset of B4.Edge and Hono →

The app must also depend on @b4run/postgres-storage, @neondatabase/serverless, hono and its model provider, here @langchain/openai.

b4.config.ts

import { config } from "@b4run/cli" export default config({  build: { targets: ["vercel"] },})

$ npx b4 buildBuild complete: .b4/build  1 route(s) compiled  targets: vercel  wrote .vercel/output/config.json  wrote .vercel/output/functions/b4.func/.vc-config.json  wrote .vercel/output/functions/b4.func/index.mjs  wrote vercel.json

A Build Output API tree with one streaming function. It serves the edge subset of B4.Vercel →

The app must also depend on @b4run/postgres-storage, @neondatabase/serverless, hono and its model provider, here @langchain/openai.

b4.config.ts

import { config } from "@b4run/cli" export default config({  build: { targets: ["node"] },})

$ npx b4 buildBuild complete: .b4/build  1 route(s) compiled  targets: node  wrote .b4/build/workspace.json  wrote .b4/build/modules.mjs  wrote .b4/build/server.mjs  wrote Dockerfile$ docker build -t ghcr.io/you/my-b4-app:2026-08-10 .$ docker push ghcr.io/you/my-b4-app:2026-08-10$ helm install b4-app oci://ghcr.io/cacheplane/charts/b4-app \    --namespace b4-app \    --set image.repository=ghcr.io/you/my-b4-app \    --set image.tag=2026-08-10

The Node build in an image, pushed to a registry and installed with the b4-app Helm chart.Kubernetes →

Testing agents →Evals →Deployment →

The last mile

The parts you'd write next are already here.

Twelve things an agent needs before real users reach it. Turn a tile over to see the file, config or command that handles it.

12 of 12 openedHandled.

Describe every tool's input as JSON Schema, and keep it in step with the code.
b4 typegen reads the tool's TypeScript types and its doc comment.
src/app/hello/tools/greet.ts
```
/** Greet someone by name. */
export default async (input: { readonly name: string }) => {
```
Tools →
Stream tokens and tool calls to a web client as they happen.
Every route streams over Agent Protocol and AG-UI.
```
POST /threads/:thread_id/runs/stream
POST /agui/{routeId}
```
Agent Protocol →
Check who is calling before a route runs.
One middleware file runs before every route request.
src/middleware.ts
```
export default defineMiddleware(async (req) => {
```
Middleware →
Keep one user out of another user's threads.
One policy file decides who may create, read, change or delete each thread.
src/thread-access.ts
```
export default defineThreadAccess({
```
Thread access →
Pause a risky tool call until a person says yes.
The run pauses, and a person answers once, always or deny.
src/app/support/index.ts
```
tools: { approve: ["refund"] },
```
Permissions →
Run the agent's shell commands away from your host.
The file tools and runBash run in a Docker container, or in a Kubernetes Pod with kubernetesSandbox.
b4.config.ts
```
provider: dockerSandbox({ scope: "my-agent", image: "node:24-slim" }),
```
Sandbox →
Remember facts about a user from one conversation to the next.
A memory.ts file gives the agent remember and recall tools.
src/app/hello/memory.ts
```
export default defineMemory({
  kind: "semantic",
```
Long-term memory →
Retry the model after a rate limit or a server error.
A model call that fails with a rate limit, a server error or a network error, before anything has streamed, retries with backoff.
src/app/support/index.ts
```
retry: { maxAttempts: 5 },
```
Retry →
Share threads and checkpoints across servers, and keep them when a container is replaced.
@b4run/postgres-storage gives you the checkpointer, the thread store and the permission store.
b4.config.ts
```
checkpointer: postgresCheckpointer({ pool }),
threadsStore: createPostgresThreadsStore({ pool }),
```
Postgres backend →
Test the agent without paying for a model call.
script() fixtures stand in for the model, so npm test needs no API key.
test/agent.test.ts
```
fixtures: script().user("Say hello to Ada").replies("Hello, Ada!"),
```
Testing agents →
Score the agent on a dataset before you ship.
b4 eval replays each case offline, and b4 eval --record captures new fixtures from the model.
src/app/hello/evals/smoke.eval.ts
```
export default defineEval({
  name: "greets by name",
```
Evals →
See what the agent has remembered, and govern it.
b4 inspect opens the Inspector, a browser view of the app's long-term memory.
```
b4 inspect
```
Inspector →

Get started

Build your own agent.

Scaffold a new B4 app with one command:

Getting Started →

Ridiculous speed.Readable code.

An agent is a folder.

One export is the agent.

Your types are the tool schema.

Add plan.md and it plans.

Add memory.ts and it remembers.

Add a skill for long instructions.

Add a subagent to hand work off.

The scaffold ships an eval.

Four checks decide what a call can do.

Pick the shape per route.

Test it offline, then pick where it runs.

npm test and b4 eval

b4 build

The parts you'd write next are already here.

Build your own agent.

Ridiculous speed.
Readable code.