@mastra/mcp-docs-server 1.1.42-alpha.4 → 1.1.42-alpha.5

package/.docs/docs/agent-builder/memory.md

@@ -25,7 +25,7 @@ Observational memory lets the agent learn long-lived facts from past conversatio
 
 ## Observational memory model
 
-Observational memory runs an Observer and Reflector model on top of every conversation. The default model is `google/gemini-2.5-flash`, which requires a `GOOGLE_GENERATIVE_AI_API_KEY` environment variable in any environment where the Builder agent will run.
+Observational memory runs an Observer and Reflector model on top of every conversation. The default model is `google/gemini-2.5-flash`, which requires a `GOOGLE_API_KEY` environment variable in any environment where the Builder agent will run. Mastra also falls back to `GOOGLE_GENERATIVE_AI_API_KEY`.
 
 To use a different model, set `observationalMemory.model` to any model ID supported by the Mastra model router (and provide the matching provider credentials):
 

package/.docs/docs/agents/adding-voice.md

@@ -132,6 +132,37 @@ agent.voice.send(microphoneStream)
 agent.voice.close()
 ```
 
+### Per-session voice for concurrent sessions
+
+A static `voice` instance is shared across every request. For one-shot text-to-speech this is fine, but realtime and speech-to-speech providers store one WebSocket, one set of tools, and one request context per instance. If you deploy a single agent that handles several live sessions at once, a shared instance lets one session overwrite another session's tools, instructions, and request context.
+
+To give each session its own voice, provide `voice` as a resolver. Mastra runs the resolver on every `getVoice()` call and returns a fresh, session-owned instance:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+export const agent = new Agent({
+  id: 'support-line',
+  name: 'Support Line',
+  instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
+  model: 'openai/gpt-5.4',
+  voice: ({ requestContext }) => new OpenAIRealtimeVoice({ apiKey: requestContext.get('apiKey') }),
+})
+
+// Each concurrent session resolves its own voice instance
+const voice = await agent.getVoice({ requestContext })
+await voice.connect()
+```
+
+When you use a resolver:
+
+- Each call to `getVoice()` returns a new instance, so concurrent sessions never share state.
+- Mastra does not add tools or instructions to a resolver instance. Configure those inside the resolver or on the provider.
+- You own the lifecycle of the returned instance, so call `disconnect()` or `close()` when the session ends.
+
+The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.
+
 ### Event System
 
 The realtime voice provider emits several events you can listen for:

package/.docs/docs/agents/agent-approval.md

@@ -86,6 +86,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Conditional approval with a function
+
+Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval dynamically — for example, only for tools whose name matches a pattern:
+
+```typescript
+const stream = await agent.stream('Clean up old records', {
+  requireToolApproval: ({ toolName }) => /^delete_/.test(toolName),
+})
+```
+
+A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above does not override it. If the function throws, the call requires approval (fail-safe).
+
+> **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
+
 ### Runtime suspension with `suspend()`
 
 A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.

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

@@ -0,0 +1,163 @@
+# Code mode
+
+> **Experimental:** This feature is experimental. Breaking changes may occur without a major version bump until the API is stable.
+
+Code mode gives an agent a single tool that runs a short TypeScript program in a sandbox. Instead of calling tools one at a time, the model writes a program that orchestrates your existing tools as `external_*` functions, batching calls with `Promise.all`, aggregating with `reduce`, branching, and doing math in a real runtime, then returns a single result.
+
+`createCodeMode` returns this tool with the default id `execute_typescript`. The id is configurable, so an agent can have several code mode tools at once, each scoped to a different set of tools (see [Scoping tools across multiple code tools](#scoping-tools-across-multiple-code-tools)).
+
+## When to use code mode
+
+Use code mode when a task touches several tools at once or needs real computation between calls:
+
+- Fewer round-trips: a task that touches several tools runs in one tool call instead of one model turn per tool.
+- Correct math: sums, averages, and other arithmetic run as JavaScript, not as token prediction.
+- Planning up front: filtering, aggregation, and branching happen inside the program rather than across separate turns.
+
+## How it works
+
+Your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, so dangerous tools, approvals, and validation behave exactly as they do for normal tool calls.
+
+The program runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the program as a host `node` process with host privileges, so only use it for trusted or local development.
+
+## Quickstart
+
+`createCodeMode` returns the tool plus generated instructions. With no `id`, the tool is named `execute_typescript`. Add both to your agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createCodeMode, createTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+import { z } from 'zod'
+
+const getTopProducts = createTool({
+  id: 'getTopProducts',
+  description: 'Get top selling products',
+  inputSchema: z.object({ limit: z.number() }),
+  outputSchema: z.object({
+    products: z.array(z.object({ id: z.string(), name: z.string(), totalSales: z.number() })),
+  }),
+  execute: async ({ limit }) => fetchTopProducts(limit),
+})
+
+const getProductRatings = createTool({
+  id: 'getProductRatings',
+  description: 'Get ratings for a product',
+  inputSchema: z.object({ productId: z.string() }),
+  outputSchema: z.object({ ratings: z.array(z.object({ score: z.number() })) }),
+  execute: async ({ productId }) => fetchRatings(productId),
+})
+
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(), // required; runs on the host — see "How it works"
+})
+
+const agent = new Agent({
+  name: 'shop-assistant',
+  instructions: ['You are a helpful shopping assistant.', instructions],
+  model: 'openai/gpt-5.4',
+  tools: { execute_typescript: tool },
+})
+```
+
+Asked "What are the top 5 products and the average rating for each?", the model emits one `execute_typescript` call instead of many separate tool calls:
+
+```typescript
+const top = await external_getTopProducts({ limit: 5 })
+const ratings = await Promise.all(
+  top.products.map(p => external_getProductRatings({ productId: p.id })),
+)
+return top.products.map((product, i) => {
+  const scores = ratings[i].ratings.map(r => r.score)
+  const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length
+  return {
+    name: product.name,
+    sales: product.totalSales,
+    averageRating: Math.round(avg * 100) / 100,
+  }
+})
+```
+
+All five rating lookups run in parallel, the averages are computed in JavaScript, and the agent receives one structured result.
+
+## Configuration
+
+```typescript
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings }, // exposed as external_*; only these can be called
+  sandbox, // required WorkspaceSandbox, unless the agent runs in a workspace that provides one
+  timeout: 30_000, // optional execution timeout in ms (default 30000)
+  id: 'execute_typescript', // optional tool id (default "execute_typescript")
+})
+```
+
+| Option    | Type               | Description                                                                                                                                   |
+| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tools`   | `ToolsInput`       | Tools exposed to the program as `external_<id>`. Only these may be called.                                                                    |
+| `sandbox` | `WorkspaceSandbox` | Sandbox to run the program in. Required unless the agent runs in a workspace that provides one. Pass `new LocalSandbox()` to run on the host. |
+| `timeout` | `number`           | Execution timeout in milliseconds. Default `30000`.                                                                                           |
+| `id`      | `string`           | The generated tool's id. Default `execute_typescript`.                                                                                        |
+
+## Result
+
+The tool returns a `CodeModeToolResult`:
+
+```typescript
+type CodeModeToolResult = {
+  success: boolean
+  result?: unknown // value returned by the program
+  logs?: string[] // captured console output
+  error?: { message: string; name?: string; line?: number }
+}
+```
+
+## Inspecting the instructions
+
+The generated `instructions` contain the usage contract and a typed `external_*` declaration for each tool, derived from your tool schemas. Print them to see exactly what the model receives:
+
+```typescript
+import { createCodeModeInstructions } from '@mastra/core/tools'
+
+console.log(createCodeModeInstructions({ tools: { getTopProducts, getProductRatings } }))
+```
+
+## Scoping tools across multiple code tools
+
+`createCodeMode` captures its own allow-list. Call it more than once to give an agent several code tools, each scoped to a different subset of tools. A program can only call the `external_*` functions for the tools passed to its own `createCodeMode` call, so the subsets stay isolated.
+
+Give each tool a distinct `id` so their ids do not collide, and add each tool's instructions to the agent:
+
+```typescript
+const sales = createCodeMode({
+  id: 'sales_code',
+  tools: { listRecentOrders, getCustomer },
+  sandbox,
+})
+
+const inventory = createCodeMode({
+  id: 'inventory_code',
+  tools: { listProducts, getSupplier },
+  sandbox,
+})
+
+const agent = new Agent({
+  name: 'ops-assistant',
+  instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
+  model: 'openai/gpt-5.4',
+  tools: { sales_code: sales.tool, inventory_code: inventory.tool },
+})
+```
+
+A program run by `sales_code` cannot call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
+
+## Tips
+
+- Keep tools focused, so each does one thing well and the model composes them in code.
+- Code mode helps most when calls can be parallelized with `Promise.all`.
+- Use `console.log` for debugging. Logs are captured in the result.
+
+## Related
+
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/signals.md

@@ -2,13 +2,13 @@
 
 > **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
-Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
+Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle, drops input into the running agent loop, or queues input for the next turn.
 
-Signals are a context engineering tool for guiding the agent in real time as the agent loop progresses. Use them to add system-generated content from external event sources, such as incoming email notifications, GitHub pull request comments, background task notifications, and similar events.
+Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 
 ## Quickstart
 
-Subscribe to the thread before sending signals. The subscription receives the active stream when the signal wakes the agent or enters a running loop.
+Subscribe to the thread before sending messages. The subscription receives the active stream when the message wakes the agent or enters a running loop.
 
 ```typescript
 const subscription = await agent.subscribeToThread({
@@ -16,33 +16,65 @@ const subscription = await agent.subscribeToThread({
   threadId: 'thread_456',
 })
 
-agent.sendSignal(
+agent.sendMessage('Compare that with the previous option.', {
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+for await (const chunk of subscription.stream) {
+  console.log(chunk)
+}
+```
+
+When the thread has a running agent stream, `sendMessage()` becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the message as the first input.
+
+## Send a message now
+
+Use `sendMessage()` when the user expects the active agent to see the message immediately.
+
+```typescript
+agent.sendMessage(
   {
-    type: 'user-message',
-    contents: 'Compare that with the previous option.',
+    contents: 'Use the latest customer note too.',
+    attributes: { name: 'Jane', sentFrom: 'slack' },
   },
   {
     resourceId: 'user_123',
     threadId: 'thread_456',
   },
 )
+```
 
-for await (const chunk of subscription.stream) {
-  console.log(chunk)
-}
+The model receives attributed messages as XML-wrapped user input:
+
+```xml
+<user name="Jane" sentFrom="slack">Use the latest customer note too.</user>
+```
+
+Messages without attributes are sent as plain user input.
+
+## Queue a message for the next turn
+
+Use `queueMessage()` when a user sends a follow-up but the active model call should finish first. Mastra waits for the active run to complete, then starts a new run on the same thread.
+
+```typescript
+agent.queueMessage('Also check whether the tests need updates.', {
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
 ```
 
-When the thread has a running agent stream, the signal becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input.
+When the thread is idle, `queueMessage()` starts a run immediately. When the thread is active, it preserves turn order by starting a new run after the active run completes.
 
-## Control signal behavior
+## Control low-level signal behavior
 
-By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
+Use `sendSignal()` when you need to send system-generated context instead of user-authored input. For external events, use `type: 'notification'`. By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
 
 ```typescript
 const result = agent.sendSignal(
   {
-    type: 'user-message',
-    contents: 'Store this for later, but do not wake the agent.',
+    type: 'notification',
+    contents: 'GitHub CI failed on PR #123: 3 tests failed.',
   },
   {
     resourceId: 'user_123',
@@ -58,44 +90,43 @@ await result.persisted
 
 The behavior options are:
 
-- `ifActive.behavior: 'deliver'`: Add the signal to the running agent loop. This is the default.
-- `ifActive.behavior: 'persist'`: Save the signal to memory without adding it to the running loop.
-- `ifActive.behavior: 'discard'`: Ignore the signal while the thread is active.
-- `ifIdle.behavior: 'wake'`: Start a stream with the signal as the first input. This is the default.
-- `ifIdle.behavior: 'persist'`: Save the signal to memory without starting a stream.
-- `ifIdle.behavior: 'discard'`: Ignore the signal while the thread is idle.
+- `ifActive.behavior: 'deliver'`: Add the signal or message to the running agent loop. This is the default.
+- `ifActive.behavior: 'persist'`: Save the signal or message to memory without adding it to the running loop.
+- `ifActive.behavior: 'discard'`: Ignore the signal or message while the thread is active.
+- `ifIdle.behavior: 'wake'`: Start a stream with the signal or message as the first input. This is the default.
+- `ifIdle.behavior: 'persist'`: Save the signal or message to memory without starting a stream.
+- `ifIdle.behavior: 'discard'`: Ignore the signal or message while the thread is idle.
 
 Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You do not need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
 
 ```typescript
-agent.sendSignal(
-  {
-    type: 'user-message',
-    contents: 'Continue with the next step.',
-  },
-  {
-    resourceId: 'user_123',
-    threadId: 'thread_456',
-    ifIdle: {
-      behavior: 'wake',
-      streamOptions: {
-        maxSteps: 3,
-      },
+agent.sendMessage('Continue with the next step.', {
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
     },
   },
-)
+})
 ```
 
-## Identify users with attributes
+## Send notification context
+
+Signals have a semantic `type` and an LLM-facing `tagName`. Use `type` to describe the signal category. Use `tagName` to control the XML tag the model sees.
 
-Use `attributes` to tag each signal with user identity. The signal type and attributes are rendered as XML so the model can distinguish who said what in a multi-user thread:
+For external events, use `type: 'notification'`. Reactive signals are reserved for processor- or runtime-generated context, such as policy guidance, background task results, and auto-loaded instructions.
 
 ```typescript
 agent.sendSignal(
   {
-    type: 'user',
-    contents: 'Can we simplify the API surface?',
-    attributes: { name: 'Devin', from: 'slack' },
+    type: 'notification',
+    contents: 'PR #123 has a new review comment from User X about the API surface.',
+    attributes: {
+      source: 'github',
+      pr: '123',
+    },
   },
   {
     resourceId: 'user_123',
@@ -104,51 +135,67 @@ agent.sendSignal(
 )
 ```
 
-The model receives:
+The model receives the signal as context like this:
 
 ```xml
-<user name="Devin" from="slack">Can we simplify the API surface?</user>
+<notification source="github" pr="123">PR #123 has a new review comment from User X about the API surface.</notification>
 ```
 
-The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+Use XML-safe `tagName` and attribute names. They can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
+
+## Send processor context
 
-## Send external event context
+Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
 
-Use custom signal types for system-generated context. Non-user signal types are rendered as XML-style user-role context so they can appear inside conversation history without looking like assistant output.
+The following example demonstrates a processor that injects `AGENTS.md` instructions after a tool call reads an `AGENTS.md` file.
 
 ```typescript
-agent.sendSignal(
-  {
-    type: 'system-reminder',
-    contents: 'User X has left a new PR comment asking for a smaller API surface.',
-    attributes: {
-      source: 'github',
-      pr: '123',
-    },
-  },
-  {
-    resourceId: 'user_123',
-    threadId: 'thread_456',
+import type { Processor, ProcessInputStepArgs } from '@mastra/core/processors'
+
+export const agentsMdReminderProcessor: Processor = {
+  id: 'agents-md-reminder',
+  async processInputStep({ messageList, sendSignal }: ProcessInputStepArgs) {
+    const messages = messageList.get.all.db()
+    const agentsMdPath = findAgentsMdPathFromToolCalls(messages)
+
+    if (!agentsMdPath || hasAlreadySentAgentsMdReminder(messages, agentsMdPath)) {
+      return messageList
+    }
+
+    await sendSignal?.({
+      type: 'reactive',
+      contents: readAgentsMdInstructions(agentsMdPath),
+      attributes: {
+        type: 'dynamic-agents-md',
+        path: agentsMdPath,
+      },
+      metadata: {
+        path: agentsMdPath,
+      },
+    })
+
+    return messageList
   },
-)
+}
 ```
 
-The model receives the custom signal as context like this:
+Reactive signals default to `tagName: 'system-reminder'`, so the model receives this context as
 
 ```xml
-<system-reminder source="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+<system-reminder type="dynamic-agents-md" path="packages/ui/AGENTS.md">
+  $agentsMdFileContents
+</system-reminder>
 ```
 
-Use XML-safe signal type names and attribute names. Signal type names and attribute names can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
+Awaiting `sendSignal()` preserves stream echo ordering when a subscribed thread is active.
 
-## Delivery attributes
+## Conditional attributes
 
-Use `ifActive.attributes` and `ifIdle.attributes` to tag a signal with context that depends on whether the agent is active or idle at delivery time. Mastra resolves the correct branch when the signal is accepted.
+Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Mastra resolves the correct branch when the input is accepted.
 
 ```typescript
-agent.sendSignal(
+agent.sendMessage(
   {
-    type: 'user-message',
     contents: 'Also cover the edge cases.',
     attributes: { source: 'chat' },
   },
@@ -156,7 +203,7 @@ agent.sendSignal(
     resourceId: 'user_123',
     threadId: 'thread_456',
     ifActive: { attributes: { delivery: 'while-active' } },
-    ifIdle: { attributes: { delivery: 'message' } },
+    ifIdle: { attributes: { delivery: 'new-message' } },
   },
 )
 ```
@@ -164,24 +211,35 @@ agent.sendSignal(
 When the agent is working, the model sees:
 
 ```xml
-<user-message source="chat" delivery="while-active">Also cover the edge cases.</user-message>
+<user source="chat" delivery="while-active">Also cover the edge cases.</user>
 ```
 
 When the agent is idle:
 
 ```xml
-<user-message source="chat" delivery="message">Also cover the edge cases.</user-message>
+<user source="chat" delivery="new-message">Also cover the edge cases.</user>
 ```
 
-Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `ifActive.attributes` branch merges when the signal is delivered to a running agent loop. The `ifIdle.attributes` branch merges when the signal wakes an idle thread. If the selected branch or its `attributes` field is `undefined`, no extra attributes are added.
+Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example, you can add any attribute names that suit your use case.
+
+## Compatibility
+
+Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `type: 'system-reminder'`. It normalizes them internally to the new category and tag shape:
+
+- `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
+- `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
+
+Existing stored signal rows and older clients continue to load through the compatibility layer.
+
+> **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
-Delivery attributes work with any signal type and can carry any key-value pairs. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example; you can use any attribute names that fit your application.
+## Use HTTP routes
 
-> **Note:** Visit [Agent.sendSignal() reference](https://mastra.ai/reference/agents/agent) for the full signal input and options types.
+If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
 
 ## Use the client SDK
 
-The JavaScript client exposes the same thread signal APIs. Use `subscribeToThread()` before `sendSignal()` so the client can render the stream that wakes from, or receives, the signal.
+The JavaScript client exposes thread signal APIs. Use `subscribeToThread()` before sending thread input so the client can render the stream that wakes from, or receives, the input.
 
 ```typescript
 const agent = client.getAgent('supportAgent')
@@ -230,7 +288,10 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 
 ## Related
 
+- [`Agent.sendMessage()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
+- [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)

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

@@ -113,7 +113,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    Add your API key:
 
    ```bash
-   GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
+   GOOGLE_API_KEY=<your-api-key>
    ```
 
    > **Note:** This guide uses Google Gemini, but you can use any supported [model provider](https://mastra.ai/models), including OpenAI, Anthropic, and more.

package/.docs/docs/memory/semantic-recall.md

@@ -247,7 +247,7 @@ const agent = new Agent({
 })
 ```
 
-The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENROUTER_API_KEY`).
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY`). Google models also fall back to `GOOGLE_GENERATIVE_AI_API_KEY`.
 
 ### Using AI SDK Packages
 

package/.docs/docs/observability/metrics/overview.md

@@ -110,6 +110,7 @@ Before storage, all metric labels pass through a cardinality filter that blocks
 ## Next steps
 
 - [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
 - [Studio observability](https://mastra.ai/docs/studio/observability)
 - [Observability overview](https://mastra.ai/docs/observability/overview)