Models

Agent Express uses the AI SDK LanguageModelV3 interface under the hood. You specify a model as a simple string, and the framework resolves it to a provider instance at runtime.

Model String Format

The model field in AgentDef uses a "provider/model-name" format:

import { Agent } from "agent-express"

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

The string is split at the first / into a provider name and a model name. The framework dynamically imports the corresponding @ai-sdk/* package and creates the model instance.

Common model strings:

String	Provider	Model
"anthropic/claude-sonnet-4-6"	Anthropic	Claude Sonnet
"anthropic/claude-haiku-4-5"	Anthropic	Claude Haiku
"anthropic/claude-opus-4-6"	Anthropic	Claude Opus
"openai/gpt-4o"	OpenAI	GPT-4o
"openai/gpt-4o-mini"	OpenAI	GPT-4o Mini

Supported Providers

Agent Express ships with built-in support for Anthropic and OpenAI. Provider packages are optional peer dependencies — install only what you need.

Anthropic (Claude)

npm install @ai-sdk/anthropic

Set the ANTHROPIC_API_KEY environment variable:

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

OpenAI (GPT)

npm install @ai-sdk/openai

Set the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY="sk-..."

Other Providers

Any AI SDK v3 compatible provider works with Agent Express. See Custom Providers below for how to pass model objects directly.

Using Model Objects

The model field accepts either a string or a LanguageModelV3 object. Passing a model object gives you full control over provider configuration:

import { Agent } from "agent-express"
import { createAnthropic } from "@ai-sdk/anthropic"

const anthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: "https://custom-proxy.example.com/v1",
})

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

This is useful when you need to configure custom base URLs, headers, or other provider-specific options.

resolveModel()

Agent Express exports resolveModel() for programmatically resolving a model string to a LanguageModelV3 instance. This is the same function the framework uses internally:

import { resolveModel } from "agent-express"

const model = await resolveModel("anthropic/claude-sonnet-4-6")

resolveModel() is async because it dynamically imports the provider package. It throws if:

• The format is invalid (no / separator)
• The provider is unknown (not anthropic or openai)
• The provider package is not installed

For unknown providers, pass a LanguageModelV3 object directly instead of a string.

Model Routing

The model.router() middleware routes model calls to different models based on complexity. This lets you use cheaper models for simple queries and more capable models for complex ones:

import { Agent, model } from "agent-express"

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

agent.use(model.router({
  routes: {
    simple: "anthropic/claude-haiku-4-5",
    medium: "anthropic/claude-sonnet-4-6",
    complex: "anthropic/claude-opus-4-6",
  },
}))

The default classifier uses a heuristic based on input token count and tool count:

• simple — under 500 tokens and no tools
• complex — over 2000 tokens or 5+ tools
• medium — everything else

You can provide a custom classifier:

agent.use(model.router({
  routes: {
    simple: "anthropic/claude-haiku-4-5",
    medium: "anthropic/claude-sonnet-4-6",
    complex: "anthropic/claude-opus-4-6",
  },
  classify: (ctx) => {
    if (ctx.messages.length <= 2) return "simple"
    if (ctx.toolDefs.length > 3) return "complex"
    return "medium"
  },
}))

For full details on model.router() and other built-in middleware, see the Built-in Middleware guide.

Custom Providers

Any provider that implements the AI SDK v3 LanguageModelV3 interface works with Agent Express. Pass the model object directly to the model field:

import { Agent } from "agent-express"
import { createGoogleGenerativeAI } from "@ai-sdk/google"

const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY,
})

const agent = new Agent({
  name: "assistant",
  model: google("gemini-2.5-pro"),
  instructions: "You are a helpful assistant.",
})

This pattern works with any AI SDK v3 provider — Google, Mistral, Amazon Bedrock, Azure OpenAI, Groq, and others. Check the AI SDK provider list for available packages.