@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/guides/migrations/upgrade-to-v1/agent.md

@@ -0,0 +1,404 @@
+# Agent Class
+
+The Agent class has been updated with reorganized voice methods, updated property access patterns, and streamlined streaming APIs.
+
+## Changed
+
+### `getAgents` to `listAgents`
+
+The `mastra.getAgents()` method has been renamed to `mastra.listAgents()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
+
+To migrate, replace all calls to `mastra.getAgents()` with `mastra.listAgents()`.
+
+```diff
+- const agents = mastra.getAgents();
++ const agents = mastra.listAgents();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> **npm**:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+>
+> **pnpm**:
+>
+> ```bash
+> pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+>
+> **Yarn**:
+>
+> ```bash
+> yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+>
+> **Bun**:
+>
+> ```bash
+> bun x @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+
+### `RuntimeContext` to `RequestContext`
+
+The `RuntimeContext` class has been renamed to `RequestContext` throughout the codebase. This change provides clearer naming that better describes its purpose as request-specific data and aligns with web framework conventions.
+
+To migrate, update all imports and parameter names from `RuntimeContext`/`runtimeContext` to `RequestContext`/`requestContext`.
+
+```diff
+- import { RuntimeContext } from '@mastra/core/runtime-context';
++ import { RequestContext } from '@mastra/core/request-context';
+
+- const runtimeContext = new RuntimeContext();
+- runtimeContext.set('userTier', 'enterprise');
++ const requestContext = new RequestContext();
++ requestContext.set('userTier', 'enterprise');
+
+- await agent.generate(messages, { runtimeContext });
++ await agent.generate(messages, { requestContext });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/runtime-context .
+> ```
+
+### Direct property access to getter methods
+
+Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. This change provides better encapsulation and consistency with the broader API design.
+
+To migrate, replace property access with the corresponding getter methods.
+
+```diff
+- const llm = agent.llm;
+- const tools = agent.tools;
+- const instructions = agent.instructions;
++ const llm = agent.getLLM();
++ const tools = agent.getTools();
++ const instructions = agent.getInstructions();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/agent-property-access .
+> ```
+
+### Voice methods moved to `agent.voice` namespace
+
+Voice-related methods have been moved from the Agent class to the `agent.voice` namespace. This change provides better organization and clearer separation of concerns.
+
+To migrate, update voice method calls to use the `agent.voice` namespace.
+
+```diff
+- await agent.speak('Hello');
+- await agent.listen();
+- const speakers = agent.getSpeakers();
++ await agent.voice.speak('Hello');
++ await agent.voice.listen();
++ const speakers = agent.voice.getSpeakers();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/agent-voice .
+> ```
+
+### `agent.fetchMemory()` to `(await agent.getMemory()).recall()`
+
+The `fetchMemory()` method has been replaced with a more explicit API. This change provides better clarity about the asynchronous nature of memory access.
+
+To migrate, replace `fetchMemory()` calls with the new API.
+
+```diff
+- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
++ const memory = await agent.getMemory();
++ const result = await memory.recall({ threadId: 'thread-123' });
++ const messages = result.messages;
+```
+
+### Processor method names from `get*` to `list*`
+
+Agent processor methods have been renamed from `get*` to `list*` pattern for consistency with the broader API. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, update processor method names.
+
+```diff
+- const inputProcessors = await agent.getInputProcessors(runtimeContext);
+- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
++ const inputProcessors = await agent.listInputProcessors(requestContext);
++ const outputProcessors = await agent.listOutputProcessors(requestContext);
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/agent-processor-methods .
+> ```
+
+### Default options method renames for AI SDK versions
+
+Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5+) APIs. This change helps developers understand which AI SDK version they're targeting.
+
+To migrate, update method names based on which AI SDK version you're using.
+
+```diff
+// For legacy AI SDK v4
+- const options = await agent.getDefaultGenerateOptions();
+- const streamOptions = await agent.getDefaultStreamOptions();
++ const options = await agent.getDefaultGenerateOptionsLegacy();
++ const streamOptions = await agent.getDefaultStreamOptionsLegacy();
+
+  // For new AI SDK v5+ (default)
+  const streamOptions = await agent.getDefaultStreamOptions();
+```
+
+### `modelSettings.abortSignal` to top-level `abortSignal`
+
+The `abortSignal` option has been moved from `modelSettings` to the top level of stream/generate options. This change provides a clearer separation between model-specific settings and execution control.
+
+To migrate, move `abortSignal` from `modelSettings` to the top level.
+
+```diff
+agent.stream('Hello', {
+-   modelSettings: {
+-     abortSignal: abortController.signal,
+-   },
++   abortSignal: abortController.signal,
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/agent-abort-signal .
+> ```
+
+### `output` to `structuredOutput.schema`
+
+The deprecated `output` and `experimental_output` options have been removed. This change consolidates on a single, stable API for structured output.
+
+To migrate, update from `output` or `experimental_output` to `structuredOutput.schema`.
+
+```diff
+agent.stream('Hello', {
+-   output: z.object({ result: z.string() }),
++   structuredOutput: {
++     schema: z.object({ result: z.string() }),
++   },
+  });
+```
+
+### Agent `id` field is now required
+
+The `id` field is now required when creating an Agent. Previously, agents could be created without an explicit ID, but this is no longer supported.
+
+To migrate, add an `id` field to all Agent configurations.
+
+```diff
+const agent = new Agent({
++   id: 'my-agent',
+    name: 'My Agent',
+    instructions: 'You are a helpful assistant',
+    model: 'openai/gpt-4',
+  });
+```
+
+The `id` can be the same as the `name`, or you can use a different identifier. The ID will be used when calling `mastra.getAgentById()` and must be unique within your Mastra instance.
+
+```typescript
+// Register agent with Mastra
+const mastra = new Mastra({
+  agents: {
+    myAgent: agent, // key can differ from id
+  },
+})
+
+// Retrieve by ID
+const agent = mastra.getAgentById('my-agent')
+```
+
+### Stream API responses now redact sensitive data
+
+The Mastra server now automatically redacts sensitive information from agent stream responses. This prevents accidental exposure of system prompts, tool definitions, and API keys in `step-start`, `step-finish`, and `finish` stream chunks.
+
+**What's redacted:**
+
+- `request.body` containing LLM request payloads (system prompts, tool schemas)
+- `metadata.request` in step results
+- `output.steps[].request` in nested step data
+
+This behavior is enabled by default. If you need access to the full request data (e.g., for debugging or internal services), you can disable redaction when using server adapters directly (e.g., `@mastra/hono` or `@mastra/express`).
+
+## Removed
+
+### `generateVNext` and `streamVNext` methods
+
+The deprecated `generateVNext()` and `streamVNext()` methods have been removed. These methods were previously used for AI SDK v5+ compatibility but are now the standard implementation.
+
+To migrate, use the standard `generate()` and `stream()` methods.
+
+```diff
+- const result = await agent.generateVNext('Hello');
+- const stream = await agent.streamVNext('Hello');
++ const result = await agent.generate('Hello');
++ const stream = await agent.stream('Hello');
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/agent-generate-stream-v-next .
+> ```
+
+### `format` parameter from `stream()` and `generate()`
+
+The `format` parameter has been removed from `agent.stream()` and `agent.generate()` methods. AI SDK stream transformations are now handled by the `@mastra/ai-sdk` package. This change improves tree-shaking by moving AI SDK-specific code to a dedicated package.
+
+To migrate, use the `toAISdkStream()` function from `@mastra/ai-sdk` for AI SDK format conversion.
+
+```diff
+- const stream = await agent.stream(messages, {
+-   format: 'aisdk',
+- });
+
++ import { toAISdkStream } from '@mastra/ai-sdk';
++
++ const stream = await agent.stream(messages);
++ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });
+```
+
+### `agent.toStep()` method
+
+The `toStep()` method has been removed from the Agent class. Agents can now be added directly to workflow steps without explicit conversion.
+
+To migrate, add agents directly to workflow steps. Workflows handle the transformation automatically.
+
+```diff
+- const step = agent.toStep();
+- const workflow = new Workflow({
+-   steps: [step],
+- });
+
++ const workflow = new Workflow({
++   steps: [agent],
++ });
+```
+
+### `TMetrics` generic parameter from Agent
+
+The `TMetrics` generic parameter has been removed from `AgentConfig` and the `Agent` constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system.
+
+To migrate, remove the `TMetrics` generic parameter and configure scorers using the new API.
+
+```diff
+- const agent = new Agent<AgentId, Tools, Metrics>({
++ const agent = new Agent<AgentId, Tools>({
+    // ...
+  });
+```
+
+### Tripwire response format changed
+
+The tripwire response format has changed from separate `tripwire` and `tripwireReason` fields to a single `tripwire` object containing all related data.
+
+To migrate, update your code to access tripwire data from the new object structure.
+
+```diff
+const result = await agent.generate('Hello');
+
+- if (result.tripwire) {
+-   console.log(result.tripwireReason);
+- }
++ if (result.tripwire) {
++   console.log(result.tripwire.reason);
++   // New fields available:
++   // result.tripwire.retry - whether this step should be retried
++   // result.tripwire.metadata - additional metadata from the processor
++   // result.tripwire.processorId - which processor triggered the tripwire
++ }
+```
+
+For streaming responses:
+
+```diff
+for await (const chunk of stream.fullStream) {
+    if (chunk.type === 'tripwire') {
+-     console.log(chunk.payload.tripwireReason);
++     console.log(chunk.payload.reason);
++     // New fields available:
++     // chunk.payload.retry
++     // chunk.payload.metadata
++     // chunk.payload.processorId
+    }
+  }
+```
+
+The step results now also include tripwire information:
+
+```diff
+const result = await agent.generate('Hello');
+
+  for (const step of result.steps) {
+-   // No tripwire info on steps
++   if (step.tripwire) {
++     console.log('Step was blocked:', step.tripwire.reason);
++   }
+  }
+```
+
+### `prepareStep` messages format
+
+The `prepareStep` callback now receives messages in `MastraDBMessage` format instead of AI SDK v5+ model message format. This change unifies `prepareStep` with the new `processInputStep` processor method, which runs at each step of the agentic loop.
+
+If you need the old AI SDK v5+ format, use `messageList.get.all.aiV5.model()`:
+
+```diff
+agent.generate('Hello', {
+    prepareStep: async ({ messages, messageList }) => {
+-     // messages was AI SDK v5+ ModelMessage format
+-     console.log(messages[0].content);
++     // messages is now MastraDBMessage format
++     // Use messageList to get AI SDK v5+ format if needed:
++     const aiSdkMessages = messageList.get.all.aiV5.model();
+
+      return { toolChoice: 'auto' };
+    },
+  });
+```
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from `agent.stream()` and `agent.generate()`. Use the `memory` option instead, which provides a cleaner API for memory configuration.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+```diff
+await agent.stream('Hello', {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.stream('Hello', {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+})
+```

package/.docs/guides/migrations/upgrade-to-v1/cli.md

@@ -0,0 +1,57 @@
+# CLI
+
+The CLI has been simplified by removing deployment commands, configuration flags, and starter files. A new migration command has been added to help with database schema upgrades.
+
+## Added
+
+### `mastra migrate` command
+
+A new `mastra migrate` command helps run database migrations when upgrading Mastra versions. This is particularly useful when upgrading from older versions that may have data incompatibilities.
+
+```bash
+npx mastra migrate
+```
+
+The command bundles your project, connects to your configured storage, and runs any necessary migrations. Currently supports migrating duplicate spans entries that may prevent unique constraint creation.
+
+See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details on when this migration is needed.
+
+## Removed
+
+### `mastra deploy` command
+
+The `mastra deploy` command has been removed from the CLI. This change simplifies the CLI by removing vendor-specific deployment logic.
+
+To migrate, choose one of the [deployment platforms](https://mastra.ai/docs/deployment/overview) of your choice.
+
+### `--env` flag from `mastra build`
+
+The `--env` flag has been removed from the `mastra build` command. This change simplifies the build command.
+
+To migrate, use `mastra start --env <env>` to start the build output with a custom environment.
+
+```diff
+- mastra build --env production
++ mastra build
++ mastra start --env production
+```
+
+### `--port` flag from `mastra dev`
+
+The `--port` flag has been removed from the `mastra dev` command. Port configuration is now handled through the Mastra instance configuration. This change centralizes port configuration.
+
+To migrate, use `server.port` on the Mastra instance instead of the CLI flag.
+
+```ts
+const mastra = new Mastra({
+  server: {
+    port: 3001,
+  },
+})
+```
+
+### Telemetry options from CLI
+
+The `telemetry` option has been removed from CLI commands including the `--no-telemetry` / `-nt` flag. Telemetry configuration has been removed from the CLI. This change reflects the move of telemetry features to the observability package.
+
+To migrate, remove telemetry flags from CLI commands. Use `@mastra/observability` for tracing features.