@mastra/mcp-docs-server 1.2.7-alpha.4 → 1.2.7-alpha.8

package/.docs/docs/capabilities/channels/slack.md

@@ -0,0 +1,225 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Slack
+
+Add your agent to Slack so people can message it in shared channel threads or direct messages. When someone sends a message, Mastra runs your agent through the normal agent pipeline and streams the response back to Slack. The Slack adapter handles Slack AI indicators and interactive cards for you.
+
+## Installation
+
+Install the Slack adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/slack
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/slack
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/slack
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/slack
+```
+
+Add `createSlackAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const yourAgent = new Agent({
+  id: 'your-agent',
+  name: 'Your Agent',
+  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
+  model: 'anthropic/claude-opus-4-7',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+## Create a Slack app
+
+To connect your agent, create a Slack app in the workspace where you want it to run. The Slack app controls how your agent appears in Slack, what it can do, and which events it receives.
+
+This guide uses a [manifest](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/#creating_manifests): a configuration file that creates the Slack app settings for you. This is the fastest path when you are adding your agent to your own workspace. It doesn't cover the platform OAuth flow where other workspaces install your agent.
+
+Create the Slack app from a manifest:
+
+1. Open [api.slack.com/apps](https://api.slack.com/apps).
+2. Select **Create an app**.
+3. Select **From a manifest**.
+4. Choose the workspace where the agent should run.
+5. Paste this manifest, then select **Create**:
+
+```yaml
+display_information:
+  name: mastra-agent
+features:
+  app_home:
+    home_tab_enabled: false
+    messages_tab_enabled: true
+    messages_tab_read_only_enabled: false
+  bot_user:
+    display_name: mastra-agent
+    always_online: true
+oauth_config:
+  scopes:
+    bot:
+      - im:write
+      - app_mentions:read
+      - channels:history
+      - channels:read
+      - chat:write
+      - users:read
+      - im:read
+      - im:history
+  pkce_enabled: false
+settings:
+  event_subscriptions:
+    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+    bot_events:
+      - app_mention
+      - message.channels
+      - message.im
+  interactivity:
+    is_enabled: true
+    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+  is_mcp_enabled: false
+```
+
+This manifest configures:
+
+- `display_information.name` and `features.bot_user.display_name`: Set your agent's name in Slack. You can update it at any time; remember to reinstall the app after changing names or permissions.
+- `app_home.messages_tab_enabled` and `app_home.messages_tab_read_only_enabled`: Enable direct messages from the Slack app's **Messages** tab.
+- `always_online`: Shows the Slack bot user as always available.
+- `oauth_config.scopes.bot`: Grants the bot permission to post messages, read channel messages where it is present, read mentions, read and write direct messages, and look up users.
+- `event_subscriptions`: Tells Slack which message events to send to the webhook.
+- `interactivity`: Enables interactive cards and tells Slack where to send card actions.
+
+After the app is created, open **Install App**, select **Install to Workspace**, and approve the requested scopes.
+
+## Set Slack credentials
+
+Set the Slack credentials in Mastra so it can verify Slack requests and send messages back to Slack.
+
+In the Slack app settings, copy these values:
+
+- **Basic Information** > **App Credentials** > **Signing Secret**
+- **OAuth & Permissions** > **Bot User OAuth Token**
+
+Set them in your Mastra environment:
+
+```bash
+SLACK_SIGNING_SECRET=your-signing-secret
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+```
+
+Mastra reads these environment variables automatically.
+
+## Configure the webhook route
+
+Slack sends channel activity to Mastra through webhooks. A webhook is an HTTP endpoint Slack calls when something happens, such as a new message, a mention, or a user selecting an interactive card.
+
+Mastra automatically registers a Slack webhook route for your agent:
+
+```text
+/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+```
+
+Build the webhook URL from your public Mastra server URL and the generated route:
+
+```text
+https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
+```
+
+Slack can't send events to `localhost`. For local development, keep the Mastra dev server running and expose `http://localhost:4111` with a tunnel before you save the request URL in Slack.
+
+Use a tunnel such as `cloudflared` or `ngrok` for local development:
+
+**npm**:
+
+```bash
+npx cloudflared tunnel --url http://localhost:4111
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Yarn**:
+
+```bash
+yarn dlx cloudflared tunnel --url http://localhost:4111
+```
+
+**Bun**:
+
+```bash
+bun x cloudflared tunnel --url http://localhost:4111
+```
+
+Use the generated tunnel host as `<YOUR-PUBLIC-URL>`, for example:
+
+```text
+https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook
+```
+
+Update the request URLs in Slack:
+
+1. In the Slack app settings, open **Event Subscriptions**.
+2. Replace **Request URL** with the final webhook URL.
+3. Select **Save Changes**.
+4. Open **Interactivity & Shortcuts**.
+5. Replace **Request URL** with the same webhook URL.
+6. Select **Save Changes**.
+7. If Slack asks you to reinstall the app, open **OAuth & Permissions** and select **Reinstall to Workspace**.
+
+## Try it in Slack
+
+Open a direct message with the Slack bot user and send a message. Direct messages work because the manifest includes the `message.im` event and `im:*` scopes.
+
+To use the agent in a channel, invite the Slack bot user first:
+
+```text
+/invite @your-bot-name
+```
+
+Mention the bot in the channel:
+
+```text
+@your-bot-name What can you help me with?
+```
+
+The agent responds in the thread. Response content depends on the model, instructions, memory, and tools configured on the agent.
+
+## Production deployment
+
+When you deploy the Mastra server, update both request URLs in the Slack app settings to the production webhook URL. The tunnel URL used for local development is temporary and changes when the tunnel restarts.
+
+Channels on serverless platforms may need `waitUntil` and shared pub/sub configuration so background responses and thread leases work across short-lived instances. See [serverless deployment](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)
+- [Channels reference](https://mastra.ai/reference/agents/channels)
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)

package/.docs/docs/capabilities/channels/teams.md

@@ -0,0 +1,100 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Microsoft Teams
+
+Microsoft Teams channels let a Mastra agent receive mentions and conversation events from Teams. Mastra handles the agent wiring and webhook route; the Chat SDK Teams adapter docs cover Teams app setup, authentication, and permissions.
+
+## Install the adapter
+
+Install the Teams adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/teams
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/teams
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/teams
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/teams
+```
+
+## Agent configuration
+
+Add `createTeamsAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createTeamsAdapter } from '@chat-adapter/teams'
+
+export const teamsAgent = new Agent({
+  id: 'teams-agent',
+  name: 'Teams Agent',
+  instructions: 'Answer questions and help with tasks in Microsoft Teams.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      teams: createTeamsAdapter({
+        appType: 'SingleTenant',
+      }),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { teamsAgent } from './agents/teams-agent'
+
+export const mastra = new Mastra({
+  agents: { teamsAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK Teams adapter docs](https://chat-sdk.dev/adapters/official/teams) for Teams-specific setup, including Azure bot registration, Teams CLI usage, authentication options, and required permissions.
+
+The adapter reads Teams credentials from environment variables such as:
+
+```bash
+TEAMS_APP_ID=your-azure-bot-app-id
+TEAMS_APP_PASSWORD=your-azure-bot-app-password
+TEAMS_APP_TENANT_ID=your-azure-tenant-id
+```
+
+## Webhook URL
+
+Mastra generates the Teams webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/teams-agent/channels/teams/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/teams-agent/channels/teams/webhook
+```
+
+Use this URL anywhere the Teams adapter docs ask for the bot endpoint or webhook URL. For local development, expose the Mastra dev server with a tunnel and use the tunnel URL as the base URL.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

package/.docs/docs/capabilities/channels/telegram.md

@@ -0,0 +1,98 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Telegram
+
+Telegram channels let a Mastra agent receive direct messages, group messages, and bot mentions from Telegram. Mastra handles the agent wiring and webhook route; the Chat SDK Telegram adapter docs cover bot setup, webhook registration, and polling behavior.
+
+## Install the adapter
+
+Install the Telegram adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/telegram
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/telegram
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/telegram
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/telegram
+```
+
+## Agent configuration
+
+Add `createTelegramAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createTelegramAdapter } from '@chat-adapter/telegram'
+
+export const telegramAgent = new Agent({
+  id: 'telegram-agent',
+  name: 'Telegram Agent',
+  instructions: 'Answer questions and help with tasks in Telegram.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      telegram: createTelegramAdapter(),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { telegramAgent } from './agents/telegram-agent'
+
+export const mastra = new Mastra({
+  agents: { telegramAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK Telegram adapter docs](https://chat-sdk.dev/adapters/official/telegram) for Telegram-specific setup, including BotFather, webhook registration, secret tokens, and polling mode.
+
+The adapter reads Telegram credentials from environment variables such as:
+
+```bash
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
+TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret-token
+TELEGRAM_BOT_USERNAME=your_bot_username
+```
+
+## Webhook URL
+
+Mastra generates the Telegram webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/telegram-agent/channels/telegram/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/telegram-agent/channels/telegram/webhook
+```
+
+Use this URL anywhere the Telegram adapter docs ask for the webhook URL. Telegram also supports polling mode; follow the Chat SDK adapter docs if you want to use polling for local development.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

package/.docs/docs/capabilities/channels/whatsapp.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# WhatsApp
+
+WhatsApp channels let a Mastra agent receive customer messages through WhatsApp Business Cloud. Mastra handles the agent wiring and webhook route; the Chat SDK WhatsApp adapter docs cover Meta app setup, credentials, and webhook configuration.
+
+## Install the adapter
+
+Install the WhatsApp adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/whatsapp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/whatsapp
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/whatsapp
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/whatsapp
+```
+
+## Agent configuration
+
+Add `createWhatsAppAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createWhatsAppAdapter } from '@chat-adapter/whatsapp'
+
+export const whatsappAgent = new Agent({
+  id: 'whatsapp-agent',
+  name: 'WhatsApp Agent',
+  instructions: 'Answer customer questions and help with tasks in WhatsApp.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      whatsapp: createWhatsAppAdapter(),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { whatsappAgent } from './agents/whatsapp-agent'
+
+export const mastra = new Mastra({
+  agents: { whatsappAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK WhatsApp adapter docs](https://chat-sdk.dev/adapters/official/whatsapp) for WhatsApp-specific setup, including Meta app configuration, access tokens, phone number IDs, webhook verification, and message limits.
+
+The adapter reads WhatsApp credentials from environment variables such as:
+
+```bash
+WHATSAPP_ACCESS_TOKEN=your-meta-access-token
+WHATSAPP_APP_SECRET=your-meta-app-secret
+WHATSAPP_PHONE_NUMBER_ID=your-whatsapp-phone-number-id
+WHATSAPP_VERIFY_TOKEN=your-webhook-verify-token
+```
+
+## Webhook URL
+
+Mastra generates the WhatsApp webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/whatsapp-agent/channels/whatsapp/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/whatsapp-agent/channels/whatsapp/webhook
+```
+
+Use this URL for incoming WhatsApp event delivery. The generated Mastra route handles POST events from WhatsApp; follow the Chat SDK WhatsApp adapter docs for the Meta callback and webhook verification flow.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

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

@@ -205,4 +205,5 @@ You can also pin experiments to a version, see [running experiments](https://mas
 - [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [DatasetsManager reference](https://mastra.ai/reference/datasets/datasets-manager)
-- [Dataset reference](https://mastra.ai/reference/datasets/dataset)
+- [Dataset reference](https://mastra.ai/reference/datasets/dataset)
+- 📹 [Mastra evals, datasets, and experiments workshop](https://www.youtube.com/watch?v=Vla5LfmOOrM)

package/.docs/docs/evals/datasets/running-experiments.md

@@ -321,6 +321,8 @@ console.log(experiment.startedAt)
 console.log(experiment.completedAt)
 ```
 
+> **📹 Watch:** Watch [Mastra datasets and experiments workflow](https://www.youtube.com/watch?v=R6pjAdGhxhQ) to see how datasets and experiments help improve reliability.
+
 ### Item-level results
 
 ```typescript

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

@@ -8,6 +8,8 @@ Scorers are automated tests that evaluate Agents outputs using model-graded, rul
 
 Scorers can be run in the cloud, capturing real-time results. But scorers can also be part of your CI/CD pipeline, allowing you to test and monitor your agents over time.
 
+> **📹 Watch:** Watch [Mastra evals overview](https://www.youtube.com/watch?v=12WN6u2DrBk) for an introduction to evals and how to reason about agent quality.
+
 ## Types of scorers
 
 Mastra provides different kinds of scorers, each serving a specific purpose. Here are some common types:
@@ -142,4 +144,5 @@ Once registered, you can score traces interactively within Studio under the **Ob
 - Add [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts) to enforce hard requirements and quality thresholds
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
-- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)
+- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)
+- 📹 [Mastra evals workshop](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)

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

@@ -0,0 +1,114 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# File-based agents
+
+**Added in:** `@mastra/core@1.50.0`
+
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+File-based agents are a new, convention-based way to define Mastra agents and project primitives from a directory structure under `src/mastra/`. You'll like this approach if you want an agent to be self-contained, easy to scan and extend.
+
+Adopting this feature is a fundamental decision about how to structure your project. You'll need to follow the file conventions and be aware of its limitations, namely that you can't use dynamic configuration or runtime wiring.
+
+However, you can use file-based agents, code-defined agents, or both in the same project. All Mastra docs currently use code-first examples. As file-based agents mature, more examples may use this structure where it makes sense.
+
+Under the hood Mastra is assembling code-defined agents and primitives from the files you create. So explanations and concepts you can find on other docs pages apply to file-based agents as well.
+
+## Basic layout
+
+A small file-based agent looks like this:
+
+```text
+src/mastra/
+  agents/
+    weather/
+      config.ts
+      instructions.md
+      tools/
+        get-weather.ts
+      skills/
+        forecast-review.md
+```
+
+The main files in an agent directory are:
+
+- [`config.ts`](https://mastra.ai/reference/file-based-agents/config): Model selection and runtime options
+- [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions): The prompt that applies to every response
+- [`tools/`](https://mastra.ai/reference/file-based-agents/tools): Typed functions the model can call
+- [`skills/`](https://mastra.ai/reference/file-based-agents/skills): Reusable instructions
+
+You need to define `config.ts` and `instructions.md` at a minimum. Add optional files as needed. Learn more in the [add capabilities](#add-capabilities) section.
+
+## Quickstart
+
+Create a folder at `src/mastra/agents/weather`. Inside, add a `config.ts` and an `instructions.md` file with these contents:
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+Start Mastra's development server with `mastra dev`. Inside Studio, you can now call the `weather` agent and ask it about the weather.
+
+## Add capabilities
+
+Map each primitive or feature to its file convention:
+
+| Primitive or feature                                                             | File convention                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [Agent config](https://mastra.ai/reference/file-based-agents/config)             | `src/mastra/agents/<agent-id>/config.ts`                                                  |
+| [Agent instructions](https://mastra.ai/reference/file-based-agents/instructions) | `src/mastra/agents/<agent-id>/instructions.md`                                            |
+| [Tools](https://mastra.ai/reference/file-based-agents/tools)                     | `src/mastra/agents/<agent-id>/tools/`                                                     |
+| [Skills](https://mastra.ai/reference/file-based-agents/skills)                   | `src/mastra/agents/<agent-id>/skills/`                                                    |
+| [Memory](https://mastra.ai/reference/file-based-agents/memory)                   | `src/mastra/agents/<agent-id>/memory.ts`                                                  |
+| [Workspace](https://mastra.ai/reference/file-based-agents/workspace)             | `src/mastra/agents/<agent-id>/workspace.ts` and `src/mastra/agents/<agent-id>/workspace/` |
+| [Processors](https://mastra.ai/reference/file-based-agents/processors)           | `src/mastra/agents/<agent-id>/processors/`                                                |
+| [Subagents](https://mastra.ai/reference/file-based-agents/subagents)             | `src/mastra/agents/<agent-id>/subagents/`                                                 |
+| [Workflows](https://mastra.ai/reference/file-based-agents/workflows)             | `src/mastra/workflows/`                                                                   |
+| [Storage](https://mastra.ai/reference/file-based-agents/storage)                 | `src/mastra/storage.ts`                                                                   |
+| [Observability](https://mastra.ai/reference/file-based-agents/observability)     | `src/mastra/observability.ts`                                                             |
+| [Server config](https://mastra.ai/reference/file-based-agents/server)            | `src/mastra/server.ts`                                                                    |
+| [Studio config](https://mastra.ai/reference/file-based-agents/studio)            | `src/mastra/studio.ts`                                                                    |
+
+## Discovery lifecycle
+
+File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app.
+
+After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
+
+Discovery is source-based and conservative. It skips symlinks, ignores test files, treats workflows and singleton project files as file-routed only when they have a default export, and ignores directories that aren't agent directories.
+
+Start your app through the Mastra CLI so discovery runs:
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+If you import your `mastra` instance directly, `agents/<name>/` directories and the other conventions aren't discovered. When you consume Mastra as a library, register those primitives in code instead.

package/.docs/docs/long-running-agents/signals.md

@@ -10,6 +10,8 @@ Signals are a way to interact with an agent through a thread. Instead of startin
 
 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.
 
+> **📹 Watch:** Watch [Mastra signals overview](https://www.youtube.com/watch?v=7It2y89TVP4) to see how signals wake and steer long-running agents.
+
 ## When to use signals
 
 Use signals when an agent thread needs new input or context outside the original `stream()` call. Signals are useful when users send follow-up messages while a run is active, when background systems need to add context to a thread, or when external events should wake, update, or notify the agent.
@@ -430,4 +432,5 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)
-- [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)
+- [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)
+- 📹 [Mastra signals workshop](https://www.youtube.com/watch?v=KLg6uFKz9aw\&t=3020s)