---
title: "Add Caveman to a Mastra agent with native processors"
description: "Add the Caveman processor to the Mastra agent you already run. Begin in observation mode with an empty model boundary. Keep Mastra's workflow, memory, tools, and model configuration fixed."
canonical: https://caveman.so/switch/mastra
last-updated: 2026-09-07
---

# Add Caveman to a Mastra agent with native processors

Add the Caveman processor to the Mastra agent you already run. Begin in observation mode with an empty model boundary. Keep Mastra's workflow, memory, tools, and model configuration fixed.

The reviewed adapter requires `@mastra/core@1.63.2`, Node 22.19 or newer, and the source Caveman SDK. Follow [the source setup guide](/guides/agent-sdk-migration); the older published npm SDK is not a substitute for that API. Capabilities remain experimental and uncertified.

## Save processor order and baseline behavior

Record input and output processor arrays, model settings, memory configuration, tools, workflow steps, and response-cache settings. Save the dependency lock and a checked staging task.

Include a normal call, a tool result, a cache hit, a provider error, and a cancelled stream. If existing processors modify context, capture a permitted fixture before and after those changes so their order can be reproduced.

Use [Mastra's documentation](https://mastra.ai/docs) for native behavior and [the adapter source](https://github.com/caveman-ai/agent-sdk/tree/main/packages/adapters/mastra) for the supported seam.

## Add the same processor on input and output

This excerpt belongs in your existing agent factory. `model`, `inputProcessors`, `outputProcessors`, and `record` are application values. Carry the rest of your current agent options into the constructor:

```ts
import { Agent } from "@mastra/core/agent";
import { createMastraAdapter } from "@caveman-ai/adapter-mastra";
import { createModelBoundary } from "@caveman-ai/agent/model-boundary";
import type {
  MastraModelRequest,
  MastraModelResponse,
} from "@caveman-ai/adapter-mastra";

const caveman = createMastraAdapter({
  modelBoundary: createModelBoundary<
    MastraModelRequest,
    MastraModelResponse
  >([]),
  onLifecycle: event => record(event),
  onModelUsage: observation => record(observation),
});

const agent = new Agent({
  id: "support",
  name: "Support",
  instructions: "Answer using the available support tools.",
  model,
  inputProcessors: [...inputProcessors, caveman],
  outputProcessors: [...outputProcessors, caveman],
});
```

Mastra exposes request hooks through input processors and response, stream, tool, and terminal hooks through output processors. Use the same `caveman` instance in both arrays. Choose its position deliberately relative to existing transformations.

## Reconcile provider calls and cache hits

Run the baseline cases and compare native records with observations. Check provider and model identity before attributing usage. Missing identity should not become a guessed model name.

A native response-cache hit should not appear as a fresh provider call. For actual calls, inspect raw input, output, and cache evidence. Missing counters remain unknown; do not normalize them to zero in the sink.

Some retryable model failures and terminal run failures have no complete processor callback in the pinned version. Keep the application's current error reporting and include those calls when measuring full-task cost through other authoritative records.

## Test the stream and tool path

Verify that chunks arrive in the expected order, cancellation reaches the native stream, and tools receive the same arguments. Check that existing processors still run once and retain their return values.

Make the observation sink fail in staging. Confirm that it does not replace native output or errors. Then test a full workflow, including memory access and a repeated turn, rather than stopping after one short model response.

## Add a context policy only after observation works

The empty boundary does not compress. If a specific repeated payload is expensive, add a bounded transformation and test it against saved fixtures and complete tasks. Preserve required fields and define recovery where information is omitted.

Use [agent evaluations](/guides/agent-evaluations) to keep quality checks fixed. Report local results as inferred and preserve incomplete accounting. Installing an adapter does not create certified savings or budget enforcement.

## Roll back

Remove the Caveman instance from both processor arrays and restore the saved dependency lock. Keep the original processor order, tools, memory, and workflow configuration. Confirm the same staging task and cached path still pass.

Read [Caveman vs Mastra](/compare/mastra) before considering a full runtime rewrite. The processor integration is often enough to answer the first usage question.