agent-express
agent-express is a minimalist middleware framework for building AI agents in TypeScript, applying the Express.js middleware pattern to AI agents. It solves the complexity of agent frameworks by reducing concepts to Agent, Session, and Middleware, and is for developers familiar with Express who want to build production-ready agents.
✨ Key features
- Middleware architecture with 5 onion hooks and one (ctx, next) pattern
- Built-in guards for budget, validation, timeouts, and HITL approval
- Observability with structured logging, OpenTelemetry, and token tracking
- Support for 12+ model providers via
provider/modelstring - Model routing and memory compaction strategies
- Testing toolkit with TestModel, record/replay, and snapshots
🎯 Use cases
- Building production support bots with RAG and PII redaction
- Creating multi-turn conversational agents with session persistence
- Implementing cost-controlled agents with budget guards
- Developing agents with streaming responses and tool calls
- Testing agents with mocked or recorded LLM responses
📦 Installation
🧰 Requirements: Requires Node.js with TypeScript (ESM only). No API keys needed for basic use, but model providers require their own keys.
npm install agent-express
🚀 Usage
import { Agent, tools } from "agent-express"
import { z } from "zod"
const agent = new Agent({
model: "anthropic/claude-sonnet-4-6",
instructions: "You are a helpful assistant.",
})
agent.use(tools.function({
name: "greet",
description: "Greet someone by name",
schema: z.object({ name: z.string() }),
execute: async ({ name }) => `Hello, ${name}!`,
}))
const { text } = await agent.run({ input: "Greet Alice" })
console.log(text)
❓ FAQ
What are the core concepts of agent-express?
The framework is built on three concepts: Agent, Session, and Middleware. This replaces the 15-20 concepts found in alternative frameworks.
How do I add custom middleware?
You can pass a plain function to .use() for a turn hook, or return a Middleware object with hooks like turn and model. The hooks form an onion pattern where code before next() runs on the way in and after on the way out.
Can I persist sessions across restarts?
Yes, sessions can persist to SQLite, Redis, or Postgres via adapter packages. For example, use @agent-express/session-sqlite with memory.store().
How do I test agents without hitting real APIs?
Use the testing toolkit from agent-express/test, such as TestModel for scripted responses or RecordModel/ReplayModel to record real API calls and replay them later.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.