> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to AdonisJS agent 2.0.0

> Upgrade from 1.x to explicit integrations and update your helper imports

This guide covers how to:

* Install and register the integrations your application uses
* Preserve recording settings and update helper imports
* Verify telemetry after upgrading

## Overview

Version `2.0.0` stops bundling Mastra, Vercel AI, BullMQ, Bentocache, and MCP integrations. Install and configure only the ones you use.

Node auto-instrumentation and built-in Adonis mail, queue, and CLI tracing stay included. Keep your `mail`, `queue`, `cli`, endpoint, API key, destinations, and sampling options.

## 1. Install the integrations you use

Upgrade the agent, then install the integrations your application needs. Keep their host libraries as direct application dependencies.

```bash title="Terminal" theme={"theme":"vesper"}
npm install @monocle.sh/adonisjs-agent@^2.0.0
```

<CodeGroup>
  ```bash title="BullMQ" theme={"theme":"vesper"}
  npm install @monocle.sh/instrumentation-bullmq
  ```

  ```bash title="Vercel AI SDK" theme={"theme":"vesper"}
  npm install @monocle.sh/instrumentation-vercel-ai
  ```

  ```bash title="Mastra" theme={"theme":"vesper"}
  npm install @monocle.sh/instrumentation-mastra
  ```

  ```bash title="Bentocache" theme={"theme":"vesper"}
  npm install @monocle.sh/instrumentation-bentocache bentocache
  ```

  ```bash title="MCP" theme={"theme":"vesper"}
  npm install @monocle.sh/instrumentation-mcp
  ```
</CodeGroup>

## 2. Register integrations

Replace the top-level `ai`, `mastra`, `bullmq`, and `cache` options with entries in `integrations`. Keep only the imports and entries you use; omit an integration to disable it. Installing a package alone no longer activates it.

```diff title="config/monocle.ts" theme={"theme":"vesper"}
 import { defineConfig } from "@monocle.sh/adonisjs-agent";
+import { bullmq } from "@monocle.sh/instrumentation-bullmq/integration";
+import { vercelAi } from "@monocle.sh/instrumentation-vercel-ai/integration";
+import { mastra } from "@monocle.sh/instrumentation-mastra/integration";
+import { bentocache } from "@monocle.sh/instrumentation-bentocache/integration";
 import env from "#start/env";

 export default defineConfig({
   apiKey: env.get("MONOCLE_API_KEY"),
   serviceName: env.get("APP_NAME"),
   serviceVersion: env.get("APP_VERSION"),
   environment: env.get("APP_ENV"),
-  bullmq: { useProducerSpanAsConsumerParent: false },
-  ai: { recordInputs: false, recordOutputs: false },
-  mastra: {},
-  cache: { includeKeys: false },
+  integrations: [
+    bullmq({ useProducerSpanAsConsumerParent: false }),
+    vercelAi({ recordInputs: false, recordOutputs: false }),
+    mastra({ recordInputs: false, recordOutputs: false }),
+    bentocache({ includeKeys: false }),
+  ],
 });
```

* **AI recording:** Mastra no longer inherits `ai.recordInputs` or `ai.recordOutputs`. Set them on both `mastra()` and `vercelAi()` to preserve disabled recording, as above. Keep your [Mastra OpenTelemetry bridge](/instrumentations/mastra).
* **BullMQ:** The integration inherits the agent's `sampling` callback unless you override it in `bullmq()`. Omitting or disabling it does not bypass [generic job sampling](/features/job-sampling). Keep `useProducerSpanAsConsumerParent` for trace linking; `executionSpanLinkMode` is an Adonis queue option.
* **Cache:** Move existing `cache` options into `bentocache()`. Keep `bentocache` as a direct dependency even when using `@adonisjs/cache`. [Cache defaults and key sanitization](/instrumentations/bentocache) stay the same.

Built-in `mail`, `queue`, and `cli` options stay at the top level. Use `false` or `{ enabled: false }` to disable them. Underlying Node instrumentations, such as Redis tracing, can still emit spans independently.

## 3. Update helper imports

Replace the removed `/ai` and `/mcp` imports. The helpers keep their existing usage.

```diff title="app/services/telemetry.ts" theme={"theme":"vesper"}
-import { withConversationId, getConversationId } from "@monocle.sh/adonisjs-agent/ai";
+import { withConversationId, getConversationId } from "@monocle.sh/instrumentation-vercel-ai";
-import { instrumentMcpServer } from "@monocle.sh/adonisjs-agent/mcp";
+import { instrumentMcpServer } from "@monocle.sh/instrumentation-mcp";
-import type { InstrumentMcpServerOptions } from "@monocle.sh/adonisjs-agent/mcp";
+import type { InstrumentMcpServerOptions } from "@monocle.sh/instrumentation-mcp";
```

[MCP](/instrumentations/mcp-server) stays attached to a server instance: call `instrumentMcpServer()` before connecting a transport, without adding it to `integrations`.

## 4. Verify the upgrade

1. Run your application's type checker to catch old options and imports.
2. Keep `import '../otel.js'` first in `bin/server.ts` and `bin/console.ts` so instrumentation hooks load before application libraries.
3. Restart the application and workers. Exercise each enabled integration and confirm its spans appear in Monocle Cloud or Studio, with the expected input/output recording settings.
4. Remove unused integration packages from your application's dependencies.

If an `/integration` export is missing, upgrade the agent and integration packages together and reinstall dependencies. If initialization fails, the error identifies the integration: check its configuration and compatible host library, or remove the entry if unused.