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
"google/gemini-2.0-flash"	Google	Gemini 2.0 Flash
"mistral/mistral-large-latest"	Mistral	Mistral Large
"groq/llama-3.1-70b-versatile"	Groq	Llama 3.1 70B

Supported Providers

Agent Express supports any AI SDK v3 provider via dynamic import. Provider packages are optional peer dependencies — install only what you need. No framework code changes required when new providers are published.

Provider	Package	Environment Variable
Anthropic (Claude)	@ai-sdk/anthropic	ANTHROPIC_API_KEY
OpenAI (GPT)	@ai-sdk/openai	OPENAI_API_KEY
Google (Gemini)	@ai-sdk/google	GOOGLE_GENERATIVE_AI_API_KEY
Mistral	@ai-sdk/mistral	MISTRAL_API_KEY
Groq	@ai-sdk/groq	GROQ_API_KEY
Amazon Bedrock	@ai-sdk/amazon-bedrock	AWS credentials
Azure OpenAI	@ai-sdk/azure	AZURE_API_KEY
DeepSeek	@ai-sdk/deepseek	DEEPSEEK_API_KEY
xAI (Grok)	@ai-sdk/xai	XAI_API_KEY
Cohere	@ai-sdk/cohere	COHERE_API_KEY
Together AI	@ai-sdk/togetherai	TOGETHER_AI_API_KEY
Fireworks	@ai-sdk/fireworks	FIREWORKS_API_KEY

Install a provider and use it immediately:

npm install @ai-sdk/google

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

See the full list at AI SDK providers.

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 name contains invalid characters (must be lowercase alphanumeric with hyphens)
• The provider package is not installed (with an actionable npm install command in the error)

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 Provider Configuration

Most providers work with just a string. Pass a LanguageModelV3 object when you need custom configuration (proxy URLs, custom headers, non-standard auth):

import { Agent } from "agent-express"
import { createAzure } from "@ai-sdk/azure"

const azure = createAzure({
  apiKey: process.env.AZURE_API_KEY,
  baseURL: "https://my-deployment.openai.azure.com/openai",
})

const agent = new Agent({
  name: "assistant",
  model: azure("gpt-4o"),
  instructions: "You are a helpful assistant.",
})