@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

package/.docs/raw/reference/cli/mastra.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: CLI Commands | CLI"
 description: Documentation for the Mastra CLI to develop, build, and start your project.
+packages:
+  - "@mastra/core"
 ---
 
 # CLI Commands
@@ -19,7 +21,7 @@ The command accepts [common flags][common-flags] and the following additional fl
 
 #### `--https`
 
-Enable local HTTPS support. [Learn more](/docs/v1/getting-started/studio#local-https).
+Enable local HTTPS support. [Learn more](/reference/v1/configuration#serverhttps).
 
 #### `--inspect`
 
@@ -41,7 +43,7 @@ You can set certain environment variables to modify the behavior of `mastra dev`
 
 Set `MASTRA_DEV_NO_CACHE=1` to force a full rebuild rather than using the cached assets under `.mastra/`:
 
-```bash copy
+```bash
 MASTRA_DEV_NO_CACHE=1 mastra dev
 ```
 
@@ -51,7 +53,7 @@ This helps when you are debugging bundler plugins or suspect stale output.
 
 `MASTRA_CONCURRENCY` caps how many expensive operations run in parallel (primarily build and evaluation steps). For example:
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=4 mastra dev
 ```
 
@@ -61,7 +63,7 @@ Leave it unset to let the CLI pick a sensible default for the machine.
 
 When using providers supported by the Vercel AI SDK you can redirect requests through proxies or internal gateways by setting a base URL. For OpenAI:
 
-```bash copy
+```bash
 OPENAI_API_KEY=<your-api-key> \
 OPENAI_BASE_URL=https://openrouter.example/v1 \
 mastra dev
@@ -69,7 +71,7 @@ mastra dev
 
 For Anthropic:
 
-```bash copy
+```bash
 ANTHROPIC_API_KEY=<your-api-key> \
 ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
@@ -86,10 +88,16 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](/docs/v1/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](/guides/v1/deployment) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
 It accepts [common flags][common-flags].
 
+### Flags
+
+#### `--studio`
+
+Bundle the Studio UI with the build.
+
 ### Configs
 
 You can set certain environment variables to modify the behavior of `mastra build`.
@@ -98,7 +106,7 @@ You can set certain environment variables to modify the behavior of `mastra buil
 
 For CI or when running in resource constrained environments you can cap how many expensive tasks run at once by setting `MASTRA_CONCURRENCY`.
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=2 mastra build
 ```
 
@@ -124,6 +132,30 @@ The path to your built Mastra output directory. Defaults to `.mastra/output`.
 
 Disable the [OTEL Tracing](/docs/v1/observability/tracing/overview).
 
+## `mastra studio`
+
+Starts [Mastra Studio](/docs/v1/getting-started/studio) as a static server. After starting, you can enter your Mastra instance URL (e.g. `http://localhost:4111`) to connect Studio to your Mastra backend.
+
+### Flags
+
+The command accepts [common flags][common-flags] and the following additional flags:
+
+#### `--port`
+
+The port to run Studio on. Defaults to `3000`.
+
+#### `--server-host`
+
+The host of the Mastra API server to connect to. Defaults to `localhost`.
+
+#### `--server-port`
+
+The port of the Mastra API server to connect to. Defaults to `4111`.
+
+#### `--server-protocol`
+
+The protocol of the Mastra API server to connect to. Defaults to `http`.
+
 ## `mastra lint`
 
 The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
@@ -140,13 +172,13 @@ Read the [Scorers overview](/docs/v1/evals/overview) to learn more.
 
 Add a new scorer to your project. You can use an interactive prompt:
 
-```bash copy
+```bash
 mastra scorers add
 ```
 
 Or provide a scorer name directly:
 
-```bash copy
+```bash
 mastra scorers add answer-relevancy
 ```
 
@@ -196,29 +228,45 @@ Do not include example code. Useful when using the `--default` flag.
 
 Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "cursor-global" | "windsurf" | "vscode"`.
 
+## `mastra migrate`
+
+Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
+
+The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
+
+- **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
+
+```bash
+mastra migrate
+```
+
+See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when migrations are needed.
+
+It accepts [common flags][common-flags].
+
 ## Common flags
 
 ### `--dir`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 The path to your Mastra folder. Defaults to `src/mastra`.
 
 ### `--debug`
 
-**Available in:** `dev`, `build`
+**Available in:** `dev`, `build`, `migrate`
 
 Enable verbose logging for Mastra's internals. Defaults to `false`.
 
 ### `--env`
 
-**Available in:** `dev`, `start`
+**Available in:** `dev`, `start`, `studio`, `migrate`
 
 Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
 
 ### `--root`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 Path to your root folder. Defaults to `process.cwd()`.
 
@@ -246,13 +294,13 @@ By default, Mastra collects anonymous information about your project like your O
 
 You can opt out of the CLI analytics by setting an environment variable:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1
 ```
 
 You can also set this while using other `mastra` commands:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1 mastra dev
 ```
 

package/.docs/raw/reference/client-js/agents.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Reference: Agents API | Client SDK"
 description: Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 # Agents API
@@ -15,19 +19,25 @@ Retrieve a list of all available agents:
 const agents = await mastraClient.listAgents();
 ```
 
-Returns a record of agent IDs to their serialized agent configurations. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
+Returns a record of agent IDs to their serialized agent configurations.
 
 ## Working with a Specific Agent
 
-Get an instance of a specific agent:
+Get an instance of a specific agent by its ID:
+
+```typescript title="src/mastra/agents/my-agent.ts"
+export const myAgent = new Agent({
+  id: "my-agent",
+});
+```
 
 ```typescript
-const agent = mastraClient.getAgent("agent-id");
+const agent = mastraClient.getAgent("my-agent");
 ```
 
 ## Agent Methods
 
-### Get Agent Details
+### details()
 
 Retrieve detailed information about an agent:
 
@@ -35,39 +45,45 @@ Retrieve detailed information about an agent:
 const details = await agent.details();
 ```
 
-Returns the serialized agent configuration. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
-
-### Generate Response
+### generate()
 
 Generate a response from the agent:
 
 ```typescript
-const response = await agent.generate({
-  messages: [
+const response = await agent.generate(
+  [
     {
       role: "user",
       content: "Hello, how are you?",
     },
   ],
-  threadId: "thread-1", // Optional: Thread ID for conversation context
-  resourceId: "resource-1", // Optional: Resource ID
-  output: {}, // Optional: Output configuration
+  {
+    memory: {
+      thread: "thread-abc", // Optional: Thread ID for conversation context
+      resource: "user-123", // Optional: Resource ID
+    },
+    structuredOutput: {}    // Optional: Structured Output configuration
+  }
+);
+```
+
+You can also use the simplified string format with memory options:
+
+```typescript
+const response = await agent.generate("Hello, how are you?", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
 });
 ```
 
-### Stream Response
+### stream()
 
 Stream responses from the agent for real-time interactions:
 
 ```typescript
-const response = await agent.stream({
-  messages: [
-    {
-      role: "user",
-      content: "Tell me a story",
-    },
-  ],
-});
+const response = await agent.stream("Tell me a story");
 
 // Process data stream with the processDataStream util
 response.processDataStream({
@@ -75,8 +91,31 @@ response.processDataStream({
     console.log(chunk);
   },
 });
+```
 
-// You can also read from response body directly
+You can also use the simplified string format with memory options:
+
+```typescript
+const response = await agent.stream("Tell me a story", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
+  clientTools: { colorChangeTool },
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    if (chunk.type === "text-delta") {
+      console.log(chunk.payload.text);
+    }
+  },
+});
+```
+
+You can also read from response body directly:
+
+```typescript
 const reader = response.body.getReader();
 while (true) {
   const { done, value } = await reader.read();
@@ -85,11 +124,150 @@ while (true) {
 }
 ```
 
-### Client tools
+#### AI SDK compatible format
+
+To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
 
-Client-side tools allow you to execute custom functions on the client side when the agent requests them.
+```typescript title="client-ai-sdk-transform.ts"
+import { createUIMessageStream } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+
+const response = await agent.stream("Tell me a story");
+
+const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
+  start(controller) {
+    response
+      .processDataStream({
+        onChunk: async (chunk) => controller.enqueue(chunk as ChunkType),
+      })
+      .finally(() => controller.close());
+  },
+});
+
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(
+      chunkStream as unknown as MastraModelOutput,
+      { from: "agent" },
+    )) {
+      writer.write(part);
+    }
+  },
+});
+
+for await (const part of uiMessageStream) {
+  console.log(part);
+}
+```
+
+### getTool()
+
+Retrieve information about a specific tool available to the agent:
+
+```typescript
+const tool = await agent.getTool("tool-id");
+```
+
+### executeTool()
 
-#### Basic Usage
+Execute a specific tool for the agent:
+
+```typescript
+const result = await agent.executeTool("tool-id", {
+  data: { input: "value" },
+});
+```
+
+### network()
+
+Stream responses from an agent network for multi-agent interactions:
+
+```typescript
+const response = await agent.network("Research this topic and write a summary");
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### approveToolCall()
+
+Approve a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.approveToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### declineToolCall()
+
+Decline a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.declineToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### approveToolCallGenerate()
+
+Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
+### declineToolCallGenerate()
+
+Decline a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
+## Client Tools
+
+Client-side tools allow you to execute custom functions on the client side when the agent requests them.
 
 ```typescript
 import { createTool } from "@mastra/client-js";
@@ -108,14 +286,16 @@ const colorChangeTool = createTool({
 });
 
 // Use with generate
-const response = await agent.generate({
-  messages: "Change the background to blue",
+const response = await agent.generate("Change the background to blue", {
   clientTools: { colorChangeTool },
 });
 
 // Use with stream
-const response = await agent.stream({
-  messages: "Change the background to green",
+const response = await agent.stream("Tell me a story", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
   clientTools: { colorChangeTool },
 });
 
@@ -125,97 +305,143 @@ response.processDataStream({
       console.log(chunk.payload.text);
     } else if (chunk.type === "tool-call") {
       console.log(
-        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(chunk.payload.args, null, 2)}`,
+        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(
+          chunk.payload.args,
+          null,
+          2
+        )}`
       );
     }
   },
 });
 ```
 
-### Get Agent Tool
+## Stored Agents
 
-Retrieve information about a specific tool available to the agent:
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+
+### listStoredAgents()
+
+Retrieve a paginated list of all stored agents:
 
 ```typescript
-const tool = await agent.getTool("tool-id");
+const result = await mastraClient.listStoredAgents();
+console.log(result.agents); // Array of stored agents
+console.log(result.total); // Total count
 ```
 
-### Get Agent Evaluations
-
-Get evaluation results for the agent:
+With pagination and ordering:
 
 ```typescript
-// Get CI evaluations
-const evals = await agent.evals();
-
-// Get live evaluations
-const liveEvals = await agent.liveEvals();
+const result = await mastraClient.listStoredAgents({
+  page: 0,
+  perPage: 20,
+  orderBy: {
+    field: "createdAt",
+    direction: "DESC",
+  },
+});
 ```
 
-### Stream
+### createStoredAgent()
 
-Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for Mastra's native format.
+Create a new stored agent:
 
 ```typescript
-const response = await agent.stream("Tell me a story", {
-  threadId: "thread-1",
-  clientTools: { colorChangeTool },
+const agent = await mastraClient.createStoredAgent({
+  id: "my-agent",
+  name: "My Assistant",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
 });
+```
 
-// Process the stream
-response.processDataStream({
-  onChunk: async (chunk) => {
-    if (chunk.type === "text-delta") {
-      console.log(chunk.payload.text);
-    }
+With all options:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: "full-agent",
+  name: "Full Agent",
+  description: "A fully configured agent",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
+  tools: ["calculator", "weather"],
+  workflows: ["data-processing"],
+  agents: ["sub-agent-1"],
+  memory: "my-memory",
+  scorers: {
+    "quality-scorer": {
+      sampling: { type: "ratio", rate: 0.1 },
+    },
+  },
+  defaultOptions: {
+    maxSteps: 10,
+  },
+  metadata: {
+    version: "1.0",
+    team: "engineering",
   },
 });
 ```
 
-#### AI SDK compatible format
+### getStoredAgent()
 
-To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
+Get an instance of a specific stored agent:
 
-```typescript title="client-ai-sdk-transform.ts" copy
-import { createUIMessageStream } from "ai";
-import { toAISdkStream } from "@mastra/ai-sdk";
-import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+```typescript
+const storedAgent = mastraClient.getStoredAgent("my-agent");
+```
 
-const response = await agent.stream({ messages: "Tell me a story" });
+## Stored Agent Methods
 
-const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
-  start(controller) {
-    response
-      .processDataStream({
-        onChunk: async (chunk) => controller.enqueue(chunk as ChunkType),
-      })
-      .finally(() => controller.close());
-  },
+### details()
+
+Retrieve the stored agent configuration:
+
+```typescript
+const details = await storedAgent.details();
+console.log(details.name);
+console.log(details.instructions);
+console.log(details.model);
+```
+
+### update()
+
+Update specific fields of a stored agent. All fields are optional:
+
+```typescript
+const updated = await storedAgent.update({
+  name: "Updated Agent Name",
+  instructions: "New instructions for the agent.",
 });
+```
 
-const uiMessageStream = createUIMessageStream({
-  execute: async ({ writer }) => {
-    for await (const part of toAISdkStream(
-      chunkStream as unknown as MastraModelOutput,
-      { from: "agent" },
-    )) {
-      writer.write(part);
-    }
-  },
+```typescript
+// Update just the tools
+await storedAgent.update({
+  tools: ["new-tool-1", "new-tool-2"],
 });
 
-for await (const part of uiMessageStream) {
-  console.log(part);
-}
+// Update metadata
+await storedAgent.update({
+  metadata: {
+    version: "2.0",
+    lastModifiedBy: "admin",
+  },
+});
 ```
 
-### Generate
+### delete()
 
-Generate a response using the enhanced API with improved method signatures and AI SDK v5 compatibility:
+Delete a stored agent:
 
 ```typescript
-const response = await agent.generate("Hello, how are you?", {
-  threadId: "thread-1",
-  resourceId: "resource-1",
-});
+const result = await storedAgent.delete();
+console.log(result.success); // true
 ```