---
title: "Caveman Agent SDK integration: source setup and migration boundaries"
description: "There are two ways to use Caveman with an agent application. A native adapter attaches to a framework you already run. A Caveman agent definition adopts the SDK's own contract and can use a supported "
canonical: https://caveman.so/guides/agent-sdk-migration
last-updated: 2026-09-07
---

# Caveman Agent SDK integration: source setup and migration boundaries

There are two ways to use Caveman with an agent application. A native adapter attaches to a framework you already run. A Caveman agent definition adopts the SDK's own contract and can use a supported runner lane. Choose that boundary before changing application code.

The documented 0.2 API is available in source. At this review, npm publishes `@caveman-ai/agent@0.1.0`, an older API. Do not expect a registry install to provide the source examples below.

## Build the reviewed source workspace

The reviewed repository revision is `604440f93e43782d22fda561ca169b177a14001a`. It includes the workspace dependencies needed by the SDK and adapters:

```bash
git clone https://github.com/caveman-ai/agent-sdk.git
cd agent-sdk
git checkout 604440f93e43782d22fda561ca169b177a14001a
npm ci
npm run build
```

Use Node 22.19 or newer for the core SDK and native adapters. The Eve runner requires Node 24 or newer; choose Node 24 when evaluating the whole workspace. Follow the repository's package-manager declaration and preserve the lockfile.

This source setup was built during preparation of this guide. The AI SDK, LangGraph, and Mastra adapter test suites also passed at that revision. Those are local integration checks, not live-provider certification.

Run the source CLI directly after building:

```bash
node packages/agent/dist/cli.js doctor --json
```

Doctor makes no model request. Review warnings and failures individually. Missing optional local runtime components can leave an observe-only path, while invalid project or containment checks require attention before execution.

Use [the install reference](https://docs.caveman.so/docs/agent-sdk/install) for the CLI contract. Prototype source imports within the workspace before packaging them for another application; unpublished local dependencies must travel together rather than silently resolving to older registry packages.

## Choose a native adapter when keeping the framework

| Framework | Reviewed upstream pin | Request transformation | Usage |
| --- | --- | --- | --- |
| Vercel AI SDK | `ai@7.0.84` | Explicit model boundary | Available native evidence |
| Mastra | `@mastra/core@1.63.2` | Explicit model boundary | Available native evidence |
| Strands Agents | `@strands-agents/sdk@1.15.0` | Explicit model boundary | Available native evidence |
| OpenAI Agents | `@openai/agents@0.17.0` | Explicit model boundary | Available native evidence |
| LangGraph.js | `@langchain/langgraph@1.4.13` | Unsupported | Available native evidence |
| Cloudflare Agents | `agents@0.22.0` | Unsupported | Unsupported; lifecycle only |

All six native adapters are experimental and uncertified in the reviewed manifests. Tracing, replay awareness, durable observation, and compilation are unsupported. Check lifecycle gaps for the lane you select.

The framework keeps model I/O, retries, tools, streams, and errors. The adapter does not create a second agent loop. An empty model boundary does not compress, and an adapter does not enforce a spend ceiling.

Follow the concrete [AI SDK](/switch/vercel-ai-sdk), [Mastra](/switch/mastra), or [LangGraph](/switch/langgraph) guide, and inspect [all adapter manifests](https://github.com/caveman-ai/agent-sdk/tree/main/packages/adapters) for the other lanes.

## Distinguish runner lanes from native adapters

Runner lanes execute a Caveman agent definition on a particular runtime. They do not promise to import arbitrary agents written directly against that runtime.

| Runner | Reviewed pin | Boundary to understand |
| --- | --- | --- |
| Pi | `@earendil-works/pi-agent-core@0.83.0` | Experimental compilation limited to tool-free agents |
| Claude Agent SDK | `@anthropic-ai/claude-agent-sdk@0.3.220` | Unlocked lane with explicit tool and feature limits |
| Eve | `eve@0.29.2` | Node 24; unsupported compilation and reasoning-plan limits |

Read [the adapter reference](https://docs.caveman.so/docs/agent-sdk/adapters) before choosing a lane. Match its supported features to your agent's tools, state, and execution requirements.

## Map the contracts before a runtime move

Inventory tools and side effects, dependency injection, output schema, history, memory, checkpointing, interrupts, permissions, retries, deployment, and evaluation jobs. Mark each as preserved, explicitly reimplemented, or unsupported in the candidate.

For Python frameworks such as [Pydantic AI](/compare/pydanticai), language and service boundaries also need a plan. There is no native Pydantic AI adapter in this reviewed registry.

Start with a side-effect-free task whose result is easy to check. Do not move a durable production workflow until its resume and failure behavior have been proven.

## Observe before transforming

For a native adapter, start with usage and lifecycle sinks and an empty boundary where supported. Compare native behavior with and without the adapter.

Check model identity, missing cache fields, stream cancellation, early exit, tool errors, and an observation sink that throws. Preserve existing callbacks through the adapter's composition helpers.

Once observation passes, add one bounded context transformation if needed. The policy and recovery behavior are separate from the hook that invokes it. Test the actual model-facing request and the final task artifact.

## Keep accounting claims within the evidence

Missing usage remains unknown. Complete counts for a model without a known price remain unpriced. Adapter observations and local optimization results stay inferred.

Keep budget enforcement in the layer that owns requests and retries. Use [agent evaluations](/guides/agent-evaluations) and [cost measurement](/guides/measure-agent-cost) to check the complete task after adding observations or transformations.

## Make removal part of the trial

For a native adapter, restore the original middleware, processors, or callback configuration and verify native execution. For a runtime migration, keep the original service callable and preserve the state needed to return to it.

Advance from one checked task to the rest of the application only after required contracts pass. The useful endpoint is an agent that still does its job, with better evidence or a tested improvement in cost.