Agents

An agent is a route where the model decides which tools to call. It's the route the scaffold creates, and I recommend it whenever you want the model to decide what to do. When you want to control the steps yourself, use a workflow, graph or chain.

A minimal agentCopy link to section: A minimal agent

A route's index.ts default-exports agent({ model, systemPrompt }). B4.run finds the tools in the route's tools/ directory and wires them into the generated graph:

import { agent } from "@b4run/sdk"
 
export default agent({
  model: "gpt-5-mini",
  systemPrompt:
    "You are a research assistant. Answer questions thoroughly and cite your sources.",
})

index.ts is the agent, and every TypeScript file in tools/ becomes one of its tools. B4.run infers the parameter types from each function signature when you run b4 build.

Model providersCopy link to section: Model providers

An agent() route runs on a LangChain chat model. B4.run infers the provider from known model names and loads the matching LangChain package on demand. The built-in provider ids are openai, anthropic, google, mistral, groq, ollama, xai, and openrouter (see ModelProviderId). Raw graph and chain routes can create any provider themselves.

Set provider yourself when the model name is an alias, ambiguous, local, or routed through a gateway:

src/app/(public)/research/index.ts

import { agent } from "@b4run/sdk"
 
export default agent({
  model: "llama3.1",
  provider: "ollama",
  systemPrompt: "You are a helpful assistant.",
})

B4.run includes the OpenAI integration. Install the other LangChain provider packages as you need them:

bash

npm install @langchain/anthropic     # anthropic
npm install @langchain/google-genai  # google
npm install @langchain/mistralai     # mistral
npm install @langchain/groq          # groq
npm install @langchain/ollama        # ollama
npm install @langchain/xai           # xai
npm install @langchain/openrouter    # openrouter

b4 check and b4 verify warn, with did-you-mean suggestions, when a model id isn't in B4.run's known list for its provider. Only openai, google, anthropic and xai have lists. The runtime prints the same warning once when it creates the model.

It's only a warning. New, proxy and gateway model ids run fine as long as your provider accepts them.

When to pick an agentCopy link to section: When to pick an agent

A route's index.ts exports one of four entry shapes, and different routes in a project can use different shapes:

Agent: the model picks the tools. Use it for chat and open-ended research.
Workflow: a plain async function. Use it when you want to write the steps yourself.
Graph: the full LangGraph DSL with branching, looping and conditional edges. Use it when the flow has structure the model shouldn't decide.
Chain: a LangChain LCEL Runnable. Use it for simple linear pipelines.

Tool auto-bindingCopy link to section: Tool auto-binding

You don't write a tools: [...] array. At build time, B4.run wires every file in the route's tools/ directory into the generated graph:

src/app/(public)/research/tools/search.ts

export default async (input: { readonly query: string }) => {
  return { results: [`Result for: ${input.query}`] }
}

B4.run reads the parameter type and turns it into a JSON schema for the model. When the model decides it needs a search, it calls search with a query.

See Tools for the full input/output rules and the generated declarations.

RetryCopy link to section: Retry

Agents take a retry option for temporary model and provider failures:

src/app/.../index.ts

export default agent({
  model: "gpt-5-mini",
  systemPrompt: "...",
  retry: { maxAttempts: 3, baseDelay: 250 },
})

See Retry for the backoff strategy, what is retried, and the streaming caveat.

Built-in agent featuresCopy link to section: Built-in agent features

You turn on more agent features by adding files or options:

Memory loads workspace/AGENTS.md into the prompt.
Planning adds plan.md, writeTodos, todos, and plan_update.
Skills adds skills/<name>/SKILL.md and readSkill.
Subagents adds child routes and task.
Reasoning tunes effort and streams reasoning on agent() routes, per provider.
Workspace activates workspace tools (listDir, readFile, writeFile, editFile, runBash) when a workspace/ directory exists.