---
title: "Add Caveman to a Vercel AI SDK agent"
description: "Keep your AI SDK agent and model client. The Caveman adapter adds native middleware and callbacks around them. Begin with an empty model boundary so the first trial observes behavior without changing "
canonical: https://caveman.so/switch/vercel-ai-sdk
last-updated: 2026-09-07
---

# Add Caveman to a Vercel AI SDK agent

Keep your AI SDK agent and model client. The Caveman adapter adds native middleware and callbacks around them. Begin with an empty model boundary so the first trial observes behavior without changing prompts.

This guide targets the source adapter for `ai@7.0.84` and Node 22.19 or newer. It is experimental and uncertified. The published `@caveman-ai/agent@0.1.0` is an older API, so use [the source setup](/guides/agent-sdk-migration) before copying the imports below.

## Preserve the working agent

Save the dependency lock, model configuration, tools, stopping conditions, callback handlers, and stream consumer. Record a passing task and its final output. Include a failed tool, a cancelled stream, and an early consumer exit in the baseline.

Do not upgrade AI SDK and add Caveman in the same change. If your application uses another version, evaluate the supported pin in an isolated branch or wait for matching adapter support.

Keep [the upstream AI SDK documentation](https://ai-sdk.dev/docs/introduction) beside the [adapter source](https://github.com/caveman-ai/agent-sdk/tree/main/packages/adapters/vercel-ai-sdk). They define different sides of the integration.

## Attach middleware to the existing model

After building the source workspace, adapt your existing agent factory as follows. `model`, `existingCallbacks`, and `record` represent your application's existing model, callbacks, and observation sink:

```ts
import { ToolLoopAgent, wrapLanguageModel } from "ai";
import { createModelBoundary } from "@caveman-ai/agent/model-boundary";
import {
  createVercelAISDKAdapter,
  type VercelModelRequest,
  type VercelModelResponse,
} from "@caveman-ai/adapter-vercel-ai-sdk";

const caveman = createVercelAISDKAdapter({
  modelBoundary: createModelBoundary<
    VercelModelRequest,
    VercelModelResponse
  >([]),
  onLifecycleEvent: event => record(event),
  onModelUsage: observation => record(observation),
});

const agent = new ToolLoopAgent({
  model: wrapLanguageModel({
    model,
    middleware: caveman.middleware,
  }),
  ...caveman.composeAgentCallbacks(existingCallbacks),
});
```

Carry your current tools and other agent options into this factory. Use `composeAgentCallbacks` so adding observations does not silently discard existing handlers or change their return values.

An empty boundary makes no prompt transformation. It also does not add a budget ceiling, proxy hop, or another model loop.

## Check usage before changing context

Run the baseline task and inspect observations alongside native usage. Confirm provider and model identity, call boundaries, input and output counts, and cache fields. Missing fields should remain unknown.

Test a sink that throws in staging. Observation failure should not replace the native model result or error. Verify that your own sink handling does not add another failure path around the adapter.

Do not treat missing `run.error` events as successful runs. That phase is unsupported by this native seam; keep the application's existing error reporting.

## Exercise the stream contract

Compare full consumption, cancellation, early exit, and provider error with the direct baseline. Ensure the UI receives the same content and tools, stops when requested, and does not trigger extra provider calls.

Keep structured outputs and tool call IDs intact. Check latency over the complete agent task, including retries owned by AI SDK. A single successful text response does not validate a tool-driven streaming agent.

## Add one transformation after observation passes

If repeated context is expensive, supply a bounded request transformation through the model boundary. Test it on recorded fixtures before live calls. The adapter supplies the hook; the transformation and its recovery contract are your responsibility.

Use [the evaluation guide](/guides/agent-evaluations) to compare final artifacts, full-task usage, and failure rates. Local adapter reports remain inferred; no certification or verified saving follows from installing the package.

## Roll back

Restore the original unwrapped model and callback configuration. Keep the same agent options and dependency lock. Since AI SDK retained execution ownership, removing the adapter should not require migrating checkpoints, tools, or UI streams.

Read [the comparison](/compare/vercel-ai-sdk) before choosing a full Caveman runtime migration instead of this smaller integration.