# How Headroom Integrates with Vercel AI SDK via wrapLanguageModel Middleware

> Learn how Headroom integrates with Vercel AI SDK using wrapLanguageModel middleware for automatic prompt compression, reducing LLM costs and improving performance.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Headroom provides a TypeScript adapter that implements the Vercel AI SDK `LanguageModelV3Middleware` interface, automatically compressing prompts through the Headroom proxy before they reach the underlying LLM.**

The `chopratejas/headroom` repository includes a dedicated adapter for the Vercel AI SDK that enables automatic context compression via the `wrapLanguageModel` middleware pattern. This integration allows developers to reduce token costs and improve latency without changing existing AI SDK code patterns, keeping all heavy processing on the Headroom proxy or Headroom Cloud while maintaining zero runtime dependencies for the client.

## Middleware Architecture and Contract

The integration centers on the `headroomMiddleware` function defined in [`sdk/typescript/src/adapters/vercel-ai.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/adapters/vercel-ai.ts), which conforms to the Vercel AI SDK **LanguageModelV3Middleware** contract.

### The transformParams Hook

Vercel AI SDK middlewares expose a `transformParams` hook that intercepts requests before they reach the language model. According to the source implementation, this hook receives the request parameters—including `prompt` or `messages`—and returns modified parameters. Headroom leverages this hook to compress context windows transparently.

The middleware executes the following sequence:

1. **Intercept** – The SDK calls `transformParams` on `headroomMiddleware` before invoking the underlying model
2. **Normalize** – Convert Vercel's `ModelMessage[]` format to OpenAI-compatible messages using `vercelToOpenAI`
3. **Compress** – Send messages to the Headroom proxy via the `compress()` API
4. **Transform** – Convert compressed OpenAI messages back to Vercel format using `openAIToVercel`
5. **Proceed** – Return transformed parameters to the SDK with the compressed `prompt`

## Data Transformation Pipeline

Headroom operates on OpenAI-style chat schemas, requiring bidirectional format conversion handled by utilities in [`sdk/typescript/src/utils/format.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/utils/format.ts).

### Format Conversion Utilities

The `vercelToOpenAI` function translates Vercel AI SDK message arrays into the OpenAI chat completion format expected by the Headroom compression pipeline. After compression, `openAIToVercel` converts the optimized messages back to Vercel's internal `ModelMessage[]` structure.

These utilities ensure compatibility while allowing Headroom's core components—**SmartCrusher**, **ContentRouter**, and **CacheAligner**—to process the conversation history using their standard OpenAI-oriented logic.

## Implementation Details

The adapter exports two primary interfaces from [`sdk/typescript/src/adapters/vercel-ai.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/adapters/vercel-ai.ts):

- **`headroomMiddleware`** – The core middleware factory accepting configuration options including `baseUrl`
- **`withHeadroom`** – A convenience wrapper that composes `wrapLanguageModel` with the Headroom middleware

Both approaches maintain the **zero-runtime-dependency** design: the TypeScript SDK only requires the optional peer dependency `ai` (Vercel AI SDK), while all compression logic executes remotely on the Headroom proxy.

## Usage Examples

### Using headroomMiddleware with wrapLanguageModel

Import the middleware and wrap your existing model to enable automatic compression:

```typescript
import { headroomMiddleware } from 'headroom-ai/vercel-ai';
import { wrapLanguageModel, generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const model = wrapLanguageModel({
  model: openai('gpt-4o'),
  middleware: headroomMiddleware({ baseUrl: 'http://localhost:8787' }),
});

const { text } = await generateText({
  model,
  messages: longConversation,
});

```

The `transformParams` method inside `headroomMiddleware` intercepts the request, compresses it via the proxy, and returns the optimized `prompt` to the SDK.

### Convenience Wrapper with withHeadroom

For simpler setup, use the `withHeadroom` helper which handles the `wrapLanguageModel` composition internally:

```typescript
import { withHeadroom } from 'headroom-ai/vercel-ai';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const model = withHeadroom(openai('gpt-4o'), {
  baseUrl: 'http://localhost:8787',
});

const { text } = await generateText({ model, messages: longConversation });

```

### Direct Vercel Message Compression

For scenarios requiring manual control, compress Vercel messages directly before passing them to the model:

```typescript
import { compressVercelMessages } from 'headroom-ai/vercel-ai';

const result = await compressVercelMessages(vercelMessages, {
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787',
});

console.log('Tokens saved:', result.tokensSaved);
const compressed = result.messages; // Returns Vercel ModelMessage[]

```

## Summary

- **Headroom implements `LanguageModelV3Middleware`** via `headroomMiddleware` in [`sdk/typescript/src/adapters/vercel-ai.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/adapters/vercel-ai.ts) to intercept Vercel AI SDK requests.
- **Bidirectional format conversion** occurs through `vercelToOpenAI` and `openAIToVercel` utilities in [`src/utils/format.ts`](https://github.com/chopratejas/headroom/blob/main/src/utils/format.ts), enabling compatibility with Headroom's OpenAI-oriented compression pipeline.
- **Zero client-side dependencies** are required beyond the optional `ai` peer dependency; compression executes on the Headroom proxy or Headroom Cloud.
- **The `withHeadroom` wrapper** provides a drop-in replacement for `wrapLanguageModel` calls, maintaining existing code patterns while adding automatic context compression.

## Frequently Asked Questions

### What is the LanguageModelV3Middleware interface?

**LanguageModelV3Middleware** is the Vercel AI SDK contract for intercepting and modifying language model requests. It exposes hooks like `transformParams` that receive the original request parameters and return modified versions. Headroom's `headroomMiddleware` implements this interface to inject compression logic between the SDK and the underlying LLM without altering the developer-facing API.

### Do I need to modify existing Vercel AI SDK code to integrate Headroom?

No. The **Headroom Vercel AI SDK integration** is designed as a transparent middleware layer. You can wrap existing models using either `headroomMiddleware` with `wrapLanguageModel` or the `withHeadroom` convenience function. Your existing `generateText` or `streamText` calls remain unchanged; the middleware automatically compresses messages before they reach the model.

### How does Headroom handle format differences between Vercel AI SDK and OpenAI?

The middleware uses utility functions `vercelToOpenAI` and `openAIToVercel` located in [`sdk/typescript/src/utils/format.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/utils/format.ts). When `transformParams` executes, it first converts Vercel's `ModelMessage[]` to OpenAI format for compression, then converts the resulting compressed messages back to Vercel format. This allows Headroom's core compression engine—which expects OpenAI-style schemas—to work seamlessly with the Vercel AI SDK's native message format.

### Is the compression performed client-side or server-side?

Compression executes **server-side** on the Headroom proxy or Headroom Cloud infrastructure. The TypeScript SDK sends messages to the configured `baseUrl` via the `compress()` API, receives the optimized context, and returns it to the Vercel AI SDK. This architecture keeps client bundles small and offloads the heavy processing of SmartCrusher, ContentRouter, and CacheAligner components to the proxy layer.