@mastra/mcp-docs-server 1.1.39-alpha.1 → 1.1.39-alpha.11

package/.docs/docs/agents/a2a.md

@@ -1,64 +1,126 @@
 # A2A (Agent-to-Agent)
 
-Mastra supports the Agent-to-Agent (A2A) protocol for exposing agents as remote agents that other agents and services can discover, call, and track over time. A2A is useful when an agent needs to cross a network boundary without exposing the remote agent's internal tools, memory, prompts, or implementation.
+Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+
+A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 
 ## When to use A2A
 
-- A parent agent should delegate work to a specialized agent owned by another service or team.
-- A remote agent should keep its tools, prompts, memory, workflows, and infrastructure private.
+- A parent agent should delegate work to a specialized remote agent.
+- A remote agent is owned by another service, team, vendor, or runtime.
 - A backend, browser app, or another A2A-compatible system needs programmatic access to a Mastra agent.
 - Long-running remote work needs task IDs, status updates, artifacts, cancellation, resubscription, or push notifications.
 
 ## How A2A works
 
-A2A maps to the roles described in the [A2A core concepts](https://a2a-protocol.org/latest/topics/key-concepts/):
+A2A uses an agent card for discovery. The card is a JSON document served from a well-known URL. It describes the remote agent and includes the execution URL that accepts A2A JSON-RPC requests.
 
-- **User**: The human, service, or process that asks for work.
-- **Client agent**: The caller that discovers a remote agent, sends messages, and listens for task updates.
-- **Remote agent**: The Mastra agent running behind an A2A endpoint.
+When using the default Mastra Server `apiPrefix` of `/api`, an agent registered as `weather-agent` exposes:
 
-Any registered Mastra agent can be called as an A2A remote agent. It keeps using its own instructions, tools, memory, workflows, and server configuration; A2A changes how the agent is reached, not how it's authored.
+- Agent card: `/api/.well-known/weather-agent/agent-card.json`
+- Execution endpoint: `/api/a2a/weather-agent`
 
-The flow is:
+An agent card includes fields like the agent name, description, endpoint URL, provider, capabilities, security metadata, and skills:
 
-1. Register a standard Mastra agent in your `Mastra` instance.
-2. Start Mastra Server or mount Mastra routes into your own server.
-3. Mastra exposes the agent through an agent card at `/.well-known/:agentId/agent-card.json` and an execution endpoint at `/a2a/:agentId`.
-4. A client reads the card, sends A2A JSON-RPC methods such as `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, or `tasks/resubscribe`, then receives task, artifact, and status events.
+```json
+{
+  "protocolVersion": "0.3.0",
+  "name": "Weather Agent",
+  "description": "Provides weather information.",
+  "url": "https://agent.example.com/api/a2a/weather-agent",
+  "version": "1.0",
+  "provider": {
+    "organization": "Acme",
+    "url": "https://acme.example.com"
+  },
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": true,
+    "stateTransitionHistory": false
+  },
+  "defaultInputModes": ["text/plain"],
+  "defaultOutputModes": ["text/plain"],
+  "skills": [
+    {
+      "id": "weather",
+      "name": "weather",
+      "description": "Gets weather conditions for a location.",
+      "tags": ["tool"]
+    }
+  ]
+}
+```
 
-Agent cards describe the remote agent's name, description, provider, endpoint URL, capabilities, security metadata, and skills. Capabilities advertise features such as streaming and push notifications. Skills describe what the remote agent can do so callers can decide whether it fits the task.
+A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect.
 
-A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect. Remote agents can also return artifacts, such as text, files, or structured data, during or after a task.
+## Get started
 
-## Quickstart
+A2A has two common paths in Mastra:
 
-Start with any agent registered in your `Mastra` instance. When Mastra Server runs, the agent is available as a remote A2A agent through its registered ID.
+- Consume a remote A2A agent as a Mastra subagent with `A2AAgent`.
+- Send requests to a Mastra A2A endpoint with `MastraClient.getA2A()`.
 
-For an agent registered as `research-agent`, Mastra exposes:
+Use `A2AAgent` when another Mastra agent should delegate work to a remote agent. Use the client SDK when application code needs to call an A2A-enabled Mastra endpoint directly.
 
-- Agent card: `/.well-known/research-agent/agent-card.json`
-- Execution endpoint: `/a2a/research-agent`
+## Consume A2A agents as subagents
 
-Use `MastraClient.getA2A()` to fetch the agent card and call the remote agent:
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
+  headers: {
+    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
+  },
+})
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Answer user questions and delegate weather questions when needed.',
+  model: 'openai/gpt-5.4',
+  agents: {
+    remoteWeatherAgent,
+  },
+})
+```
+
+If `url` points to a domain, `A2AAgent` fetches the agent card from `/.well-known/agent-card.json`. Use a domain URL for single-agent servers that follow that discovery path. For multi-agent servers, pass the full card URL, such as `https://agent.example.com/api/.well-known/weather-agent/agent-card.json`.
+
+During execution, `A2AAgent`:
+
+- Fetches and caches the remote agent card.
+- Reads the execution URL and capabilities from the card.
+- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
+- Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
+- Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
+
+If the remote card doesn't advertise streaming support, `A2AAgent.stream()` falls back to the non-streaming generate path and returns a buffered stream result.
+
+## Send requests with the client SDK
+
+Use `MastraClient.getA2A()` when you want application code to call an A2A-enabled Mastra agent. Configure `baseUrl` for the server origin and `apiPrefix` when the server doesn't use the default `/api` prefix.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
 
 const client = new MastraClient({
   baseUrl: 'https://agent.example.com',
+  headers: {
+    Authorization: `Bearer ${process.env.AGENT_API_TOKEN}`,
+  },
 })
 
-const a2a = client.getA2A('research-agent')
+const a2a = client.getA2A('weather-agent')
 const card = await a2a.getAgentCard()
 
 console.log(card.name, card.capabilities)
 ```
 
-## Discover and call remote agents
-
-A2A discovery starts with the agent card. The [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/) describes well-known URI discovery, registries, and direct configuration. Mastra supports the well-known route for registered agents at `/.well-known/:agentId/agent-card.json`.
-
-Use `sendMessageStream()` to receive task status and artifact updates over Server-Sent Events (SSE):
+Use `sendMessageStream()` to send a message and receive task status and artifact updates over Server-Sent Events (SSE):
 
 ```typescript
 const stream = a2a.sendMessageStream({
@@ -66,7 +128,7 @@ const stream = a2a.sendMessageStream({
     kind: 'message',
     role: 'user',
     messageId: crypto.randomUUID(),
-    parts: [{ kind: 'text', text: 'Summarize this incident report.' }],
+    parts: [{ kind: 'text', text: "What's the weather in Prague?" }],
   },
 })
 
@@ -89,7 +151,26 @@ for await (const event of updates) {
 }
 ```
 
-Agent cards can contain sensitive information, such as internal URLs or private skill descriptions. Protect restricted cards with access controls, and use agent card verification when a client needs to validate that a card came from a trusted source.
+## Configure subagent calls
+
+`A2AAgent` accepts request options for authenticated or constrained environments:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
+  headers: {
+    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
+  },
+  retries: 2,
+  backoffMs: 250,
+  maxBackoffMs: 1000,
+  timeoutMs: 30_000,
+})
+```
+
+You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
 
 ## Push notifications
 
@@ -144,67 +225,13 @@ const card = await a2a.getAgentCard({
     },
   },
 })
-```
-
-Use client-side signature verification to enforce trusted keys before calling the remote agent.
-
-## Use remote agents as subagents
-
-Use `A2AAgent` when a Mastra parent agent should call a remote A2A agent as a subagent. Create an `A2AAgent` with a remote agent card URL or single-agent domain, then register it in the parent agent's `agents` map.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { A2AAgent } from '@mastra/core/a2a'
-
-const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com',
-})
-
-export const supportAgent = new Agent({
-  id: 'support-agent',
-  name: 'Support Agent',
-  instructions: 'Answer user questions and delegate weather questions when needed.',
-  model: 'openai/gpt-5.4',
-  agents: {
-    remoteWeatherAgent,
-  },
-})
-```
-
-> **Tip:** If `url` points to a domain, `A2AAgent` fetches the agent card from `/.well-known/agent-card.json`. Use this for single-agent servers. For multi-agent servers, pass the explicit card URL, such as `https://agent.example.com/.well-known/:agentId/agent-card.json`. If `url` already ends with `/agent-card.json`, Mastra uses that URL directly. `A2AAgent` doesn't discover agent IDs beyond the URL you provide.
-
-`A2AAgent` implements Mastra's subagent interface. The parent agent can call it like any other subagent, while `A2AAgent` handles the protocol details.
 
-During execution, `A2AAgent`:
-
-- Fetches and caches the remote agent card.
-- Reads the execution URL and capabilities from the card.
-- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
-- Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
-- Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
-
-If the remote card doesn't advertise streaming support, `A2AAgent.stream()` falls back to the non-streaming generate path and returns a buffered stream result.
-
-## Configure subagent calls
-
-`A2AAgent` accepts request options for authenticated or constrained environments:
-
-```typescript
-import { A2AAgent } from '@mastra/core/a2a'
-
-const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com',
-  headers: {
-    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
-  },
-  retries: 2,
-  backoffMs: 250,
-  maxBackoffMs: 1000,
-  timeoutMs: 30_000,
-})
+if (!card.signatures?.length) {
+  throw new Error('Expected a signed A2A agent card.')
+}
 ```
 
-You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
+Use client-side signature verification when a client must enforce trusted keys before calling the remote agent.
 
 ## Verify subagent cards
 
@@ -214,7 +241,7 @@ Use `verifyAgentCard` when a parent agent should validate a remote agent before
 import { A2AAgent } from '@mastra/core/a2a'
 
 const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com/.well-known/agent-card.json',
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
   verifyAgentCard: {
     verify: async (card, context) => {
       if (card.provider?.organization !== 'Weather Inc') {

package/.docs/docs/agents/acp.md

@@ -0,0 +1,238 @@
+# ACP (Agent Client Protocol)
+
+Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
+
+ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements the Agent Client Protocol over standard input and output.
+
+## When to use ACP
+
+- A Mastra agent should delegate code inspection, editing, or repository tasks to an external coding agent.
+- An ACP-compatible agent process should stay alive across calls so it can keep session context.
+- A parent agent needs real-time output from a coding agent while the task runs.
+- An ACP-compatible agent needs permission prompts before it reads files, writes files, or runs actions.
+- File access should go through Mastra's workspace abstraction instead of direct process-only file access.
+
+## How ACP works
+
+`@mastra/acp` starts the configured ACP agent command as a child process and communicates with it using newline-delimited JSON over standard input and output.
+
+The flow is:
+
+1. Configure `command`, `args`, and optional connection settings.
+2. `@mastra/acp` spawns the ACP agent process on first use.
+3. The client sends ACP `initialize` and `session/new` requests.
+4. Mastra sends the user task to the ACP agent with `session/prompt`.
+5. The ACP agent streams session updates and message chunks back to Mastra.
+6. Mastra returns the buffered output, emits streaming chunks, or suspends for permission input.
+7. The ACP process stays alive by default, or stops after the prompt when `persistSession` is `false`.
+
+During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
+
+## Getting started
+
+Install `@mastra/acp` in a project that already uses `@mastra/core`:
+
+**npm**:
+
+```bash
+npm install @mastra/acp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/acp
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/acp
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/acp
+```
+
+`@mastra/acp` exports two APIs:
+
+- `createACPTool`: Create a Mastra tool that sends a `task` string to an ACP agent and returns an `output` string.
+- `AcpAgent`: Wrap an ACP agent as a Mastra subagent with `generate()` and `stream()` support.
+
+The package requires `@mastra/core` version `1.34.0` or later.
+
+## Use ACP as a subagent
+
+Use `AcpAgent` when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent. Create the ACP agent, then register it in the parent agent's `agents` map.
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  description: 'An ACP-compatible coding agent that can inspect and edit files',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent subagent.',
+  model: 'openai/gpt-5.4',
+  agents: {
+    codeAgent,
+  },
+})
+```
+
+`AcpAgent.generate()` buffers the ACP response and returns it as text. `AcpAgent.stream()` emits Mastra `text-delta` chunks as ACP `agent_message_chunk` updates arrive.
+
+## Use ACP as a tool
+
+Use `createACPTool` when the parent Mastra agent should decide when to call the ACP agent as a tool. The following example creates a code editing tool and registers it on a parent agent:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to inspect and edit code',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
+  model: 'openai/gpt-5.4',
+  tools: {
+    codeAgentTool,
+  },
+})
+```
+
+Use the `command` and `args` required by the ACP-compatible agent you run. The tool input schema has a single `task` string, and the output schema returns the final ACP response as `output`.
+
+If the ACP agent requests permission, the tool can suspend and resume through Mastra's tool suspension flow. Use `onPermissionRequest` when you need custom permission behavior.
+
+## Options reference
+
+`createACPTool` and `AcpAgent` accept the same ACP connection options. `AcpAgent` also accepts `name` to set the display name used during agent delegation.
+
+| Option                | Type                             | Description                                                                             |
+| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
+| `id`                  | `string`                         | Unique tool or subagent identifier.                                                     |
+| `description`         | `string`                         | Description shown to the model when it can call the tool or delegate to the subagent.   |
+| `command`             | `string`                         | ACP agent executable to spawn.                                                          |
+| `args`                | `string[]`                       | Arguments passed to the ACP agent executable.                                           |
+| `env`                 | `Record<string, string>`         | Environment variables to merge with the current process environment.                    |
+| `cwd`                 | `string`                         | Working directory for the ACP process, ACP session, and default workspace.              |
+| `session`             | `Partial<NewSessionRequest>`     | ACP session creation options. Defaults to `cwd` or `process.cwd()` and no MCP servers.  |
+| `initialize`          | `Partial<InitializeRequest>`     | ACP initialization options. Defaults to Mastra client information and protocol version. |
+| `authMethodId`        | `string`                         | ACP authentication method ID to invoke after initialization.                            |
+| `persistSession`      | `boolean`                        | Keep the ACP process alive after execution. Defaults to `true`.                         |
+| `onPermissionRequest` | `(request) => Promise<Response>` | Callback for ACP permission requests. Defaults to selecting the first option.           |
+| `workspace`           | `Workspace`                      | Workspace used for ACP file reads and writes.                                           |
+
+## Session lifecycle
+
+`createACPTool` and `AcpAgent` start the configured command on first use and create an ACP session. By default, `persistSession` is `true`, so the child process stays alive across calls.
+
+Use the default persistent session when:
+
+- The ACP agent benefits from keeping conversation or repository context.
+- Startup is expensive and repeated calls should reuse the same process.
+- A parent agent may delegate several related tasks to the same coding agent.
+
+Set `persistSession: false` when each prompt should run in an isolated process:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP coding task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+})
+```
+
+With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent.
+
+Pass `onPermissionRequest` to inspect the request and return the selected option yourself:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+
+export const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Workspace integration
+
+ACP file operations go through Mastra's workspace abstraction. If you don't pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` as the filesystem root.
+
+Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    root: process.cwd(),
+  }),
+})
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run coding tasks in a controlled workspace',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  workspace,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Related
+
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/docs/agents/response-caching.md

@@ -1,5 +1,7 @@
 # Response Caching
 
+> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
 Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback; per-call overrides flow through `RequestContext`.

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

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** Agent signals are experimental. Breaking changes may occur without a major version bump until the API is stable.
+> **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.
 

package/.docs/docs/build-with-ai/skills.md

@@ -32,4 +32,32 @@ bun x skills add mastra-ai/skills
 
 Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
 
+## Update skill
+
+To update to the latest version of the Mastra skill, run:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
+
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
+
 They're also available on [GitHub](https://github.com/mastra-ai/skills).