@mastra/mcp-docs-server 1.0.0-beta.7 → 1.0.0-beta.9

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

@@ -15,19 +15,26 @@ 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,9 +42,7 @@ 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:
 
@@ -55,7 +60,16 @@ const response = await agent.generate({
 });
 ```
 
-### Stream Response
+You can also use the simplified string format:
+
+```typescript
+const response = await agent.generate("Hello, how are you?", {
+  threadId: "thread-1",
+  resourceId: "resource-1",
+});
+```
+
+### stream()
 
 Stream responses from the agent for real-time interactions:
 
@@ -75,8 +89,28 @@ response.processDataStream({
     console.log(chunk);
   },
 });
+```
+
+You can also use the simplified string format:
+
+```typescript
+const response = await agent.stream("Tell me a story", {
+  threadId: "thread-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:
 
-// You can also read from response body directly
+```typescript
 const reader = response.body.getReader();
 while (true) {
   const { done, value } = await reader.read();
@@ -85,11 +119,119 @@ while (true) {
 }
 ```
 
-### Client tools
+#### AI SDK compatible format
 
-Client-side tools allow you to execute custom functions on the client side when the agent requests them.
+To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
+
+```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";
+
+const response = await agent.stream({ messages: "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()
+
+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({
+  messages: [
+    {
+      role: "user",
+      content: "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);
+  },
+});
+```
+
+## Client Tools
 
-#### Basic Usage
+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";
@@ -132,90 +274,132 @@ response.processDataStream({
 });
 ```
 
-### 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
 ```

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

@@ -101,8 +101,8 @@ export const mastraClient = new MastraClient({
     },
     {
       name: "saveMessageToMemory(params)",
-      type: "Promise<void>",
-      description: "Saves one or more messages to the memory system.",
+      type: "Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>",
+      description: "Saves one or more messages to the memory system. Returns the saved messages.",
     },
     {
       name: "getMemoryStatus()",

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

@@ -76,7 +76,7 @@ await thread.delete();
 Save messages to memory:
 
 ```typescript
-const savedMessages = await mastraClient.saveMessageToMemory({
+const result = await mastraClient.saveMessageToMemory({
   messages: [
     {
       role: "user",
@@ -90,6 +90,9 @@ const savedMessages = await mastraClient.saveMessageToMemory({
   ],
   agentId: "agent-1",
 });
+
+// result.messages contains the saved messages
+console.log(result.messages);
 ```
 
 ### Retrieve Thread Messages

package/.docs/raw/reference/core/getMemory.mdx

@@ -0,0 +1,73 @@
+---
+title: "Reference: Mastra.getMemory() | Core"
+description: "Documentation for the `Mastra.getMemory()` method in Mastra, which retrieves a registered memory instance by its registry key."
+---
+
+# Mastra.getMemory()
+
+The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
+
+## Usage example
+
+```typescript copy
+const memory = mastra.getMemory("conversationMemory");
+
+// Use the memory instance
+const thread = await memory.createThread({
+  resourceId: "user-123",
+  title: "New Conversation",
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "key",
+      type: "TMemoryKey extends keyof TMemory",
+      description:
+        "The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "memory",
+      type: "TMemory[TMemoryKey]",
+      description:
+        "The memory instance with the specified key. Throws an error if the memory is not found.",
+    },
+  ]}
+/>
+
+## Example: Registering and Retrieving Memory
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+const conversationMemory = new Memory({
+  storage: new LibSQLStore({ url: ":memory:" }),
+});
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+  },
+});
+
+// Later, retrieve the memory instance
+const memory = mastra.getMemory("conversationMemory");
+```
+
+## Related
+
+- [Mastra.listMemory()](/reference/v1/core/listMemory)
+- [Memory overview](/docs/v1/memory/overview)
+- [Agent Memory](/docs/v1/agents/agent-memory)

package/.docs/raw/reference/core/getStoredAgentById.mdx

@@ -0,0 +1,183 @@
+---
+title: "Reference: Mastra.getStoredAgentById() | Core"
+description: "Documentation for the `Mastra.getStoredAgentById()` method in Mastra, which retrieves an agent from storage and creates an executable Agent instance."
+---
+
+# Mastra.getStoredAgentById()
+
+The `.getStoredAgentById()` method retrieves an agent configuration from storage by its ID and creates an executable `Agent` instance. Stored agents allow you to persist agent configurations in a database and dynamically load them at runtime.
+
+## Usage example
+
+```typescript copy
+// Get an Agent instance from storage
+const agent = await mastra.getStoredAgentById("my-stored-agent");
+
+if (agent) {
+  const response = await agent.generate({ messages: "Hello!" });
+  console.log(response.text);
+}
+```
+
+```typescript copy
+// Get the raw storage data instead of an Agent instance
+const storedConfig = await mastra.getStoredAgentById("my-stored-agent", { raw: true });
+
+if (storedConfig) {
+  console.log(storedConfig.instructions);
+  console.log(storedConfig.createdAt);
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description:
+        "The unique identifier of the stored agent to retrieve.",
+    },
+    {
+      name: "options",
+      type: "{ raw?: boolean }",
+      description:
+        "Optional configuration object.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "raw",
+      type: "boolean",
+      description:
+        "When `true`, returns the raw `StorageAgentType` object from storage instead of creating an `Agent` instance. Useful for inspecting stored configuration or metadata.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Agent | StorageAgentType | null",
+      description:
+        "Returns an `Agent` instance by default, or `StorageAgentType` when `raw: true`. Returns `null` if no agent with the given ID exists.",
+    },
+  ]}
+/>
+
+## Primitive Resolution
+
+When creating an `Agent` instance from stored configuration, the method resolves references to registered primitives:
+
+- **Tools**: Resolved from `tools` registered in Mastra config
+- **Workflows**: Resolved from `workflows` registered in Mastra config
+- **Sub-agents**: Resolved from `agents` registered in Mastra config
+- **Memory**: Resolved from `memory` registered in Mastra config
+- **Scorers**: Resolved from `scorers` registered in Mastra config, including sampling configuration
+
+If a referenced primitive is not found in the registry, a warning is logged but the agent is still created.
+
+## StorageAgentType
+
+When using `raw: true`, the returned object has the following structure:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the agent.",
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Display name of the agent.",
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of the agent.",
+      isOptional: true,
+    },
+    {
+      name: "instructions",
+      type: "string",
+      description: "System instructions for the agent.",
+    },
+    {
+      name: "model",
+      type: "Record<string, unknown>",
+      description: "Model configuration with provider and name.",
+    },
+    {
+      name: "tools",
+      type: "Record<string, unknown>",
+      description: "Tool references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "workflows",
+      type: "Record<string, unknown>",
+      description: "Workflow references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "agents",
+      type: "Record<string, unknown>",
+      description: "Sub-agent references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "memory",
+      type: "Record<string, unknown>",
+      description: "Memory reference to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "scorers",
+      type: "Record<string, unknown>",
+      description: "Scorer references with optional sampling config.",
+      isOptional: true,
+    },
+    {
+      name: "defaultOptions",
+      type: "Record<string, unknown>",
+      description: "Default options passed to agent execution.",
+      isOptional: true,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Custom metadata stored with the agent.",
+      isOptional: true,
+    },
+    {
+      name: "createdAt",
+      type: "Date",
+      description: "Timestamp when the agent was created.",
+    },
+    {
+      name: "updatedAt",
+      type: "Date",
+      description: "Timestamp when the agent was last updated.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Mastra.listStoredAgents()](/reference/v1/core/listStoredAgents)
+- [Storage overview](/docs/v1/server-db/storage)
+- [Agents overview](/docs/v1/agents/overview)