@mastra/mcp-docs-server 1.2.3 → 1.2.4-alpha.5

package/.docs/docs/agent-controller/overview.md

@@ -54,6 +54,7 @@ import { AgentController } from '@mastra/core/agent-controller'
 import { LibSQLStore } from '@mastra/libsql'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user plan and complete tasks.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agent-controller/subagents.md

@@ -11,6 +11,7 @@ import { Agent } from '@mastra/core/agent'
 import { AgentController } from '@mastra/core/agent-controller'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Use subagents when a focused task needs a narrower toolset.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agent-controller/threads-and-state.md

@@ -84,6 +84,7 @@ import { AgentController } from '@mastra/core/agent-controller'
 import { z } from 'zod'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user manage a stateful session.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agents/background-tasks.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.29.0`
 
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/agents/agent) option the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
 
 ## When to use background tasks
 
@@ -166,7 +166,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/agents/agent) for the full API.
+> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 
@@ -372,7 +372,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 ## Related
 
-- [`Agent.stream()` reference](https://mastra.ai/reference/agents/agent)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Durable agents](https://mastra.ai/docs/agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)

package/.docs/docs/agents/channels.md

@@ -135,6 +135,7 @@ import { createDiscordAdapter } from '@chat-adapter/discord'
 import { google } from '@ai-sdk/google'
 
 export const visionAgent = new Agent({
+  id: 'vision-agent',
   name: 'Vision Agent',
   instructions: 'You can see images, watch videos, and listen to audio.',
   model: google('gemini-3.1-flash-image-preview'),
@@ -175,10 +176,12 @@ A channel webhook returns a `200` response right away, then the agent runs in th
 On Vercel, pass `waitUntil` from `@vercel/functions`:
 
 ```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
 import { waitUntil } from '@vercel/functions'
 
 export const agent = new Agent({
-  // ...
+  id: 'agent',
   channels: {
     adapters: {
       slack: createSlackAdapter(),

package/.docs/docs/agents/code-mode.md

@@ -59,6 +59,7 @@ const { tool, instructions } = createCodeMode({
 })
 
 const agent = new Agent({
+  id: 'shop-assistant',
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
   model: 'openai/gpt-5.5',
@@ -113,6 +114,7 @@ const inventory = createCodeMode({
 })
 
 const agent = new Agent({
+  id: 'ops-assistant',
   name: 'ops-assistant',
   instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
   model: 'openai/gpt-5.5',

package/.docs/docs/agents/durable-agents.md

@@ -172,7 +172,7 @@ export const durableAgent = createDurableAgent({
 
 ## Streaming with background tasks
 
-Durable agents support the same [`untilIdle`](https://mastra.ai/reference/agents/durable-agent) option as regular agents. When `untilIdle` is set, `stream()` keeps the connection open across background-task continuations until the agent is idle:
+Durable agents support the same [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option as regular agents. When `untilIdle` is set, `stream()` keeps the connection open across background-task continuations until the agent is idle:
 
 ```typescript
 const { output, cleanup } = await durableAgent.stream('Research and summarize the topic', {

package/.docs/docs/agents/file-based-agents.md

@@ -237,7 +237,7 @@ Naming rules:
 File-based and code-based agents coexist with deterministic rules:
 
 - **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
-- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
+- **A folder can hold a code agent:** If `config.ts` exports a configured `new Agent({ id: 'file-based-agent', ... })`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
 - **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
 - **Model:** A missing `model` fails the build and names the agent directory.
 - **Tools:** Tools from `tools/*.ts` merge with `config.tools`. On a key collision, `config.tools` wins and a warning is logged. If `config.tools` is a function, discovered tools are ignored with a warning.

package/.docs/docs/agents/goals.md

@@ -26,6 +26,7 @@ Goals require a configured [storage](https://mastra.ai/docs/memory/storage) back
 import { Agent } from '@mastra/core/agent'
 
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',
@@ -66,6 +67,7 @@ By default the step uses a built-in LLM-as-judge scorer that returns `1` when th
 
 ```typescript
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agents/heartbeats.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.46.0`
 
-> **Beta:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
 A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 

package/.docs/docs/agents/overview.md

@@ -2,6 +2,110 @@
 
 Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or multi-agent systems.
 
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. A complete list of documentation is available at <https://mastra.ai/llms.txt>
+
+Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
+
+Create a tsconfig.json file:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+If you need to add a tool to the agent, create a new file and use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via createTool() with id, description, inputSchema (zod), execute.
+
+Example:
+
+```ts
+// src/mastra/tools/weather-tool.ts
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('City name'),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  execute: async ({ location }) => {
+    return {
+      output: `The weather in ${location} is sunny`,
+    }
+  },
+})
+```
+
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+
+Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
+
+Example:
+
+```ts
+// src/mastra/agents/weather-agent.ts
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool.ts'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: `
+      You are a helpful weather assistant that provides accurate weather information.
+
+      Your primary function is to help users get weather details for specific locations. When responding:
+      - Include relevant details like humidity, wind conditions, and precipitation
+      - Keep responses concise but informative
+
+      Use the weatherTool to fetch current weather data.
+`,
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
+})
+```
+
+The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { weatherAgent } from './agents/weather-agent.ts'
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+})
+```
+
+You're now able to run the agent directly. For this, import the Mastra instance and call the agent.generate() after retrieving the agent by its id. Node.js 22.18.0 and later are able to run TypeScript files directly. Make sure to add file extensions when importing local files. Example:
+
+```ts
+// run.mjs
+import { mastra } from './src/mastra/index.ts'
+
+const agent = mastra.getAgentById('weather-agent')
+const response = await agent.generate('Weather in SF')
+console.log(response.text)
+```
+
+If your tasks requires to add other features, refer to the full list of docs at <https://mastra.ai/llms.txt>
+
 ## When to use agents
 
 Use agents when the task is open-ended and the steps aren't known in advance. An agent decides which tools to call, how many times to loop, and when to stop. You provide the goal and constraints instead of defining each step. For predetermined, multi-step processes with explicit control flow, use [workflows](https://mastra.ai/docs/workflows/overview) instead.

package/.docs/docs/agents/processors.md

@@ -37,6 +37,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModerationProcessor } from '@mastra/core/processors'
 
 export const moderatedAgent = new Agent({
+  id: 'moderated-agent',
   name: 'moderated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5-mini',
@@ -92,6 +93,7 @@ import { Agent } from '@mastra/core/agent'
 import { PrefillErrorHandler, TokenLimiter, ModerationProcessor } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   model: 'openai/gpt-5',
   instructions: '...',
@@ -112,7 +114,7 @@ Each array also accepts a function that returns an array, so processors can be b
 
 ```typescript
 new Agent({
-  // ...
+  id: 'processors-agent',
   inputProcessors: ({ requestContext }) => {
     const limit = requestContext.get('tokenLimit') ?? 4000
     return [new TokenLimiter(limit)]
@@ -381,6 +383,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5.5',
   inputProcessors: [new TokenLimiter(127000)],
@@ -449,6 +452,7 @@ import { ResponseCache } from '@mastra/core/processors'
 const cache = new InMemoryServerCache()
 
 export const searchAgent = new Agent({
+  id: 'search-agent',
   name: 'Search Agent',
   instructions: 'You answer questions concisely.',
   model: 'openai/gpt-5',
@@ -494,7 +498,7 @@ Override explicitly when you need a different scope:
 
 ```typescript
 new Agent({
-  // ...
+  id: 'processors-agent',
   inputProcessors: [
     new ResponseCache({
       cache,
@@ -518,6 +522,7 @@ import { RedisCache } from '@mastra/redis'
 const cache = new RedisCache({ url: process.env.REDIS_URL })
 
 export const agent = new Agent({
+  id: 'cached-agent',
   name: 'Cached Agent',
   instructions: '...',
   model: 'openai/gpt-5',
@@ -617,6 +622,7 @@ import { EnsureFinalResponseProcessor } from '../processors/ensure-final-respons
 const MAX_STEPS = 5
 
 const agent = new Agent({
+  id: 'agent',
   instructions: `You are a helpful assistant.
 
 Some messages you receive may contain <system-reminder>...</system-reminder> tags.

package/.docs/docs/agents/supervisor-agents.md

@@ -351,6 +351,7 @@ Each subagent should have a clear `description` that explains what it does, what
 
 ```typescript
 const supervisor = new Agent({
+  id: 'supervisor',
   instructions: `You coordinate research and writing tasks.
 
 Available resources:

package/.docs/docs/agents/using-tools.md

@@ -242,6 +242,7 @@ Use `hooks` to run custom logic before and after every tool call an agent makes.
 import { Agent } from '@mastra/core/agent'
 
 export const supportAgent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   instructions: 'Help users with their questions.',
   model: 'openai/gpt-5.5',
@@ -260,6 +261,7 @@ export const supportAgent = new Agent({
 
 ```typescript
 const guardedAgent = new Agent({
+  id: 'guarded-agent',
   name: 'guarded-agent',
   instructions: 'Run shell commands for the user.',
   model: 'openai/gpt-5.5',
@@ -392,6 +394,7 @@ Subagents and workflows follow the same pattern. They're converted to tools with
 
 ```typescript
 const orchestrator = new Agent({
+  id: 'orchestrator',
   agents: {
     weather: weatherAgent, // toolName: "agent-weather"
   },

package/.docs/docs/editor/overview.md

@@ -194,6 +194,7 @@ Use the `editor` field on a code-defined agent to control which fields the edito
 import { Agent } from '@mastra/core/agent'
 
 export const supportAgent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   model: 'openai/gpt-5.5',
   editor: { instructions: true, tools: { description: true } },

package/.docs/docs/evals/overview.md

@@ -55,6 +55,7 @@ import { Agent } from '@mastra/core/agent'
 import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals/scorers/prebuilt'
 
 export const evaluatedAgent = new Agent({
+  id: 'evaluated-agent',
   scorers: {
     relevancy: {
       scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),

package/.docs/docs/evals/quick-checks.md

@@ -100,6 +100,7 @@ import { Agent } from '@mastra/core/agent'
 import { checks } from '@mastra/evals/checks'
 
 export const weatherAgent = new Agent({
+  id: 'weather-agent',
   name: 'Weather Agent',
   instructions: 'Answer weather questions using the get_weather tool.',
   model: 'openai/gpt-5.5',

package/.docs/docs/getting-started/build-with-ai.md

@@ -132,13 +132,11 @@ In addition to the [context files](#context-files) each documentation page also
 
 ## MCP docs server
 
-The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
+The `@mastra/mcp-docs-server` package provides direct local access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
 
-These tools are designed to help agents retrieve precise, task-specific information — whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
+These tools are designed to help agents retrieve precise, task-specific information, whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
 
-In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/vciV57lF0og)
+If you're unable to use a local MCP server and need to connect to a remote server, use this URL: `https://mastra.mcp.kapa.ai`. You need to authenticate with your Google Account (only an anonymous ID is transmitted) for rate-limiting purposes. If possible, Mastra recommends using a local MCP server for better performance and reliability.
 
 ### Installation
 

package/.docs/docs/getting-started/manual-install.md

@@ -1,5 +1,7 @@
 # Manual install
 
+**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans.
+
 > **Info:** Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.
@@ -118,12 +120,16 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
    > **Note:** This guide uses Google Gemini, but you can use any supported [model provider](https://mastra.ai/models), including OpenAI, Anthropic, and more.
 
+   You can also use OpenAI (`OPENAI_API_KEY`) or Anthropic (`ANTHROPIC_API_KEY`) instead of Google Gemini. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
 4. Create a `weather-tool.ts` file:
 
    ```bash
    mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts
    ```
 
+   Use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via createTool() with id, description, inputSchema (zod), execute
+
    Add the following code:
 
    ```ts
@@ -139,9 +145,9 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
      outputSchema: z.object({
        output: z.string(),
      }),
-     execute: async () => {
+     execute: async ({ location }) => {
        return {
-         output: 'The weather is sunny',
+         output: `The weather in ${location} is sunny`,
        }
      },
    })
@@ -155,11 +161,13 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
    ```
 
+   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+
    Add the following code:
 
    ```ts
    import { Agent } from '@mastra/core/agent'
-   import { weatherTool } from '../tools/weather-tool'
+   import { weatherTool } from '../tools/weather-tool.ts'
 
    export const weatherAgent = new Agent({
      id: 'weather-agent',
@@ -191,14 +199,16 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
    ```ts
    import { Mastra } from '@mastra/core'
-   import { weatherAgent } from './agents/weather-agent'
+   import { weatherAgent } from './agents/weather-agent.ts'
 
    export const mastra = new Mastra({
      agents: { weatherAgent },
    })
    ```
 
-7. You can now launch [Studio](https://mastra.ai/docs/studio/overview) and test your agent.
+7. **For AI agents:** Do not launch Studio when working on a script that e.g. should print to the console. Studio is a long-running web-based interfaced for humans. Instead, call the agent.generate() method directly. Example: `import { mastra } from './src/mastra/index.ts'; const agent = mastra.getAgentById('weather-agent'); const response = await agent.generate('Weather in SF'); console.log(response.text);`
+
+   You can now launch [Studio](https://mastra.ai/docs/studio/overview) and test your agent.
 
    **npm**:
 

package/.docs/docs/index.md

@@ -2,6 +2,110 @@
 
 Build AI agents your users actually depend on. Mastra is a TypeScript framework that gives you everything you need to prototype fast and ship with confidence. Create your first agent with a single command and start building.
 
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. A complete list of documentation is available at <https://mastra.ai/llms.txt>
+
+Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
+
+Create a tsconfig.json file:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+If you need to add a tool to the agent, create a new file and use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via createTool() with id, description, inputSchema (zod), execute.
+
+Example:
+
+```ts
+// src/mastra/tools/weather-tool.ts
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('City name'),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  execute: async ({ location }) => {
+    return {
+      output: `The weather in ${location} is sunny`,
+    }
+  },
+})
+```
+
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+
+Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
+
+Example:
+
+```ts
+// src/mastra/agents/weather-agent.ts
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool.ts'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: `
+      You are a helpful weather assistant that provides accurate weather information.
+
+      Your primary function is to help users get weather details for specific locations. When responding:
+      - Include relevant details like humidity, wind conditions, and precipitation
+      - Keep responses concise but informative
+
+      Use the weatherTool to fetch current weather data.
+`,
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
+})
+```
+
+The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { weatherAgent } from './agents/weather-agent.ts'
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+})
+```
+
+You're now able to run the agent directly. For this, import the Mastra instance and call the agent.generate() after retrieving the agent by its id. Node.js 22.18.0 and later are able to run TypeScript files directly. Make sure to add file extensions when importing local files. Example:
+
+```ts
+// run.mjs
+import { mastra } from './src/mastra/index.ts'
+
+const agent = mastra.getAgentById('weather-agent')
+const response = await agent.generate('Weather in SF')
+console.log(response.text)
+```
+
+If your tasks requires to add other features, refer to the full list of docs at <https://mastra.ai/llms.txt>
+
 ## Quickstart
 
 Run this command to create a new project:

package/.docs/docs/memory/memory-processors.md

@@ -248,6 +248,7 @@ const contentBlocker = {
 }
 
 const agent = new Agent({
+  id: 'safe-agent',
   name: 'safe-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -287,6 +288,7 @@ const inputValidator = {
 }
 
 const agent = new Agent({
+  id: 'validated-agent',
   name: 'validated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/docs/memory/observational-memory.md

@@ -13,6 +13,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -57,6 +58,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -196,6 +198,7 @@ const memory = new Memory({
 })
 
 export const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -281,6 +284,7 @@ If your Observer model is text-only or its API rejects multimodal input, set `ob
 
 ```typescript
 new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',

package/.docs/docs/memory/overview.md

@@ -174,7 +174,9 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 
 - **Thread ID**: Unique per delegation. The subagent starts with a clean message history every time it's called.
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
-- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
+- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance, including all of its options. If the subagent defines its own, that takes precedence.
+
+> **Note:** Title generation (`generateTitle`) is a top-level thread concern and is **not** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
 The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.