Getting Started

Build your first AI agent in under 5 minutes. Agent Express is a minimalist middleware framework for AI agents in TypeScript — three concepts: Agent, Session, and Middleware.

Prerequisites

Node.js 20+ (ESM only)
npm (or pnpm / yarn)
An API key from Anthropic or OpenAI

Installation

Create a new project (Agent Express is ESM-only):

mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module

Install Agent Express and the provider SDK for your model:

# Anthropic (Claude)
npm install agent-express @ai-sdk/anthropic

# OpenAI (GPT)
npm install agent-express @ai-sdk/openai

Set your API key as an environment variable:

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

Your First Agent

Create a file called agent.ts:

import { Agent } from "agent-express"

const agent = new Agent({
  name: "assistant",
  model: "anthropic/claude-sonnet-4-6",
  instructions: "You are a helpful assistant.",
})

const { text } = await agent.run("What is the capital of France?").result
console.log(text)

Run it with npx tsx agent.ts. That’s a working agent.

The model string uses the "provider/model-name" format. For OpenAI, use "openai/gpt-4o".

Behind the scenes, agent.run() auto-initializes the agent, creates a single-turn session, and returns the result. Default middleware (retry, usage tracking, iteration limits) is applied automatically.

Adding Middleware

Agent Express uses an Express.js-style (ctx, next) middleware pattern. Built-in middleware is organized into namespaces: observe, guard, model, memory, tools, and dev.

Add observability and a cost guard to the agent:

import { Agent, observe, guard } from "agent-express"

const agent = new Agent({
  name: "assistant",
  model: "anthropic/claude-sonnet-4-6",
  instructions: "You are a helpful assistant.",
})

agent.use(observe.usage())            // token tracking
agent.use(guard.budget({ limit: 1 })) // $1 USD cost cap per session

const { text, state } = await agent.run("Explain quantum computing briefly.").result

console.log(text)
console.log(state["observe:usage"])  // { inputTokens: ..., outputTokens: ... }

Middleware composes in registration order. Each hook wraps the next in an onion — the first registered runs outermost.

Using the Scaffold

The fastest way to start a new project is with create-agent-express:

npx create-agent-express --template default      # minimal starter
npx create-agent-express --template coding        # coding assistant
npx create-agent-express --template research      # research agent
npx create-agent-express --template support-bot   # support bot with tools

Or skip all prompts with the default template:

npx create-agent-express --default

Run without arguments for an interactive wizard that walks you through provider, model, and template selection.

Dev Mode

Agent Express includes an interactive terminal chat with hot reload:

npx agent-express dev agent.ts

This starts a REPL session against your agent. Edit the source file and the agent reloads automatically — no restart needed. Your agent file should export the Agent instance as default or named agent.

Next Steps

Concepts — understand Agent, Session, and Middleware in depth
Middleware guide — write custom middleware with the (ctx, next) pattern
Built-in middleware — all available middleware: guards, observers, tools, memory, routing
Testing — test agents without real API calls using TestModel and FunctionModel