Getting Started

Learn how to build your first agent with B4.run.

In B4.run, an agent is a folder. The folder is the route, and the files in its tools/ folder are the functions the agent can call. B4.run reads your TypeScript types and writes the tool schemas for you.

Prefer to build with a coding agent? Copy the prompt above and paste it into Claude Code, Cursor or your agent of choice.

What will we build?#Copy link to section: What will we build?

We'll start with a small agent that greets people by name. Then we'll give it a second tool that tells the time in any city. It takes about five minutes.

You need Node.js 24 or later and npm 11. The last step calls a real model, so you also need an OpenAI API key.

Create the app#Copy link to section: Create the app

First, scaffold the app and install its dependencies:

npm create b4-app@latest my-agent
cd my-agent
npm install

Look at the agent#Copy link to section: Look at the agent

The agent lives in src/app/hello/. Let's look at the two files that matter:

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.",
})

A few things to note:

• The folder name is the route. This agent answers at /hello.
• index.ts default-exports the agent. We choose a model and write a system prompt.
• Each file in tools/ is one tool. The file name is the tool name.
• The comment above the function is the tool description the model reads.
• The input type is the tool's schema. We never write a JSON schema by hand.

Add a tool#Copy link to section: Add a tool

Now, let's give the agent a second tool. Create src/app/hello/tools/getLocalTime.ts:

/** Get the current local time in an IANA time zone, such as "Asia/Tokyo". */
export default async (input: { readonly timeZone: string }) => {
  const time = new Date().toLocaleTimeString("en-US", { timeZone: input.timeZone })
  return { timeZone: input.timeZone, time }
}

That's it. We don't register the tool anywhere. The agent picks it up because it lives in the route's tools/ folder.

Check the app#Copy link to section: Check the app

Next, check the app:

npx b4 check

check validates the routes, tools and configuration:

B4.run app is valid: 1 routes discovered.
- /hello (agent)

We don't generate anything by hand. b4 run, npm test and the dev server write the tool schemas and types to .b4/ before they run.

Run the agent#Copy link to section: Run the agent

Set your API key and send the agent a message:

export OPENAI_API_KEY=sk-...
echo '{"messages":[{"role":"user","content":"Say hello to Ada and tell her the time in Tokyo."}]}' | npx b4 run /hello

b4 run prints the whole run as JSON. The messages show the model calling greet with { "name": "Ada" } and getLocalTime with { "timeZone": "Asia/Tokyo" }. The last message is the answer:

Hello, Ada! The time in Tokyo is 9:19:32 AM.

Test it offline#Copy link to section: Test it offline

The scaffold includes a test in test/agent.test.ts. It replays a recorded model response, so it runs without an API key:

npm test

Tests like this one keep your agent working as you change it. See Agent Test Harness to write more.

Where to go next#Copy link to section: Where to go next

When you want a dev server, run npm run dev. It serves your agents over Agent Protocol and AG-UI, and it reloads as you edit.