@mastra/mcp-docs-server 1.2.14-alpha.3 → 1.2.14

package/.docs/reference/processors/processor-interface.md

@@ -58,6 +58,11 @@ Processor methods run at different points in the agent execution lifecycle:
 │  │              ▼                                               │  │
 │  │        Tool Execution (if needed)                            │  │
 │  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processToolResult     │  ← Runs per tool, after each     │  │
+│  │  └───────────┬────────────┘    tool.execute() returns        │  │
+│  │              │                                               │  │
 │  │              └──────── Loop back if tools called ────────────│  │
 │  │                                                              │  │
 │  └──────────────────────────────────────────────────────────────┘  │
@@ -73,16 +78,17 @@ Processor methods run at different points in the agent execution lifecycle:
 └────────────────────────────────────────────────────────────────────┘
 ```
 
-| Method                | When it runs                                                 | Use case                                                                                       |
-| --------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `processInput`        | Once at the start, before the agentic loop                   | Validate/transform initial user input, add context                                             |
-| `processInputStep`    | At each step of the agentic loop, before each LLM call       | Transform messages between steps, handle tool results                                          |
-| `processLLMRequest`   | After LLM request conversion, before the provider call       | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
-| `processAPIError`     | When an LLM API call fails                                   | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
-| `processOutputStream` | On each streaming chunk during LLM response                  | Filter/modify streaming content, detect patterns in real-time                                  |
-| `processLLMResponse`  | After the LLM step completes and stream chunks are collected | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
-| `processOutputStep`   | After each LLM response, before tool execution               | Validate output quality, implement guardrails with retry                                       |
-| `processOutputResult` | Once after generation completes                              | Post-process final response, log results                                                       |
+| Method                | When it runs                                                                                | Use case                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `processInput`        | Once at the start, before the agentic loop                                                  | Validate/transform initial user input, add context                                             |
+| `processInputStep`    | At each step of the agentic loop, before each LLM call                                      | Transform messages between steps, handle tool results                                          |
+| `processLLMRequest`   | After LLM request conversion, before the provider call                                      | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
+| `processAPIError`     | When an LLM API call fails                                                                  | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
+| `processOutputStream` | On each streaming chunk during LLM response                                                 | Filter/modify streaming content, detect patterns in real-time                                  |
+| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
+| `processOutputStep`   | After each LLM response, before tool execution                                              | Validate output quality, implement guardrails with retry                                       |
+| `processToolResult`   | Per tool, after `tool.execute()` returns and before the result is added to the message list | Scan tool output for prompt injection, redact sensitive fields, abort on policy violations     |
+| `processOutputResult` | Once after generation completes                                                             | Post-process final response, log results                                                       |
 
 ## Interface definition
 
@@ -131,6 +137,8 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
 
   processOutputStep?(args: ProcessOutputStepArgs<TTripwireMetadata>): ProcessorMessageResult
 
+  processToolResult?(args: ProcessToolResultArgs<TTripwireMetadata>): ProcessorMessageResult
+
   processOutputResult?(args: ProcessOutputResultArgs<TTripwireMetadata>): ProcessorMessageResult
 }
 ```
@@ -698,6 +706,109 @@ export class QualityGuardrail implements Processor {
 }
 ```
 
+### `processToolResult`
+
+Processes a tool's result after `tool.execute()` returns and before the result is added to the message list or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to scan tool output for prompt injection, redact sensitive fields, or abort the run with `abort('reason', { retry: true })`.
+
+To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it is enqueued, so streaming clients see the processed value.
+
+This method does not fire when `tool.execute()` throws; it is called only for successful tool executions where a result is available.
+
+```typescript
+processToolResult?(args: ProcessToolResultArgs): ProcessorMessageResult;
+```
+
+#### `ProcessToolResultArgs`
+
+**messages** (`MastraDBMessage[]`): All messages including the current assistant message with the tool call.
+
+**messageList** (`MessageList`): MessageList instance for managing messages. Call updateToolInvocation to replace the tool result with a redacted or transformed value.
+
+**stepNumber** (`number`): Current step number (0-indexed).
+
+**toolName** (`string`): Name of the tool that was executed.
+
+**toolCallId** (`string`): Unique identifier for this specific tool call.
+
+**args** (`unknown`): Arguments the LLM passed to the tool.
+
+**result** (`unknown`): Value returned by the tool. For client-executed tools this is the output of tool.execute() after it has passed through ensureSerializable. For provider-executed tools (e.g. Anthropic web\_search) it is the raw result from the provider stream, which is not run through ensureSerializable.
+
+**providerExecuted** (`boolean`): Whether this result came from a provider-executed tool such as Anthropic web\_search. Defaults to undefined for client-executed tools.
+
+**systemMessages** (`CoreMessage[]`): All system messages for read access.
+
+**steps** (`StepResult[]`): All completed steps so far.
+
+**state** (`Record<string, unknown>`): Per-processor state that persists across all method calls within this request. Shared with other processor methods on the same processor.
+
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort the run. Pass retry: true to request the LLM retry the step with the abort reason as feedback.
+
+**retryCount** (`number`): Number of times processors have triggered retry. Starts at 0.
+
+**tracingContext** (`TracingContext`): Tracing context for observability.
+
+**requestContext** (`RequestContext`): Request-scoped context with execution metadata.
+
+#### Use cases
+
+- Scanning tool output for prompt injection before the LLM sees it.
+- Redacting sensitive fields from tool returns (PII, secrets, credentials).
+- Aborting the run when a tool returns content that violates policy.
+- Logging or instrumenting tool returns for compliance or audit.
+
+#### Example: Redact sensitive fields
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class RedactToolResult implements Processor {
+  id = 'redact-tool-result'
+
+  async processToolResult({ toolName, toolCallId, args, result, messageList }) {
+    if (toolName !== 'lookup-customer') return
+
+    const redacted = {
+      ...(result as Record<string, unknown>),
+      ssn: '[REDACTED]',
+      email: '[REDACTED]',
+    }
+
+    messageList.updateToolInvocation({
+      type: 'tool-invocation',
+      toolInvocation: {
+        state: 'result',
+        toolCallId,
+        toolName,
+        args,
+        result: redacted,
+      },
+    })
+  }
+}
+```
+
+#### Example: Block prompt injection in tool output
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class ScanToolResult implements Processor {
+  id = 'scan-tool-result'
+
+  async processToolResult({ result, abort }) {
+    const text = typeof result === 'string' ? result : JSON.stringify(result)
+    if (containsPromptInjection(text)) {
+      abort('blocked by scan-tool-result: suspected prompt injection')
+    }
+  }
+}
+
+function containsPromptInjection(text: string): boolean {
+  return /ignore (all )?(previous|prior) instructions/i.test(text)
+}
+```
+
 ## Processor types
 
 Mastra provides type aliases to ensure processors implement the required methods:

package/.docs/reference/server/routes.md

@@ -183,6 +183,19 @@ The route returns:
 | `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
 | `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
 
+### Stored workflows
+
+Stored workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows).
+
+| Method   | Path                                      | Description                                                                    |
+| -------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/stored/workflows`                   | List stored workflow definitions, filterable by `status` and `authorId`        |
+| `GET`    | `/api/stored/workflows/:storedWorkflowId` | Get a stored workflow definition by ID                                         |
+| `POST`   | `/api/stored/workflows`                   | Upsert a definition (plus optional helper `dependencies`) and live-register it |
+| `DELETE` | `/api/stored/workflows/:storedWorkflowId` | Delete a stored definition and unregister the live workflow                    |
+
+On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered stored workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
+
 ### Create run request body
 
 ```typescript

package/.docs/reference/storage/overview.md

@@ -10,14 +10,15 @@ Mastra storage is organized into domains. Each domain owns a set of tables or co
 
 Not every storage adapter implements every domain. Composite storage lets you mix adapters per domain when the adapter packages export the corresponding domain classes.
 
-| Domain          | Description                                                                            |
-| --------------- | -------------------------------------------------------------------------------------- |
-| `memory`        | Conversation persistence: messages, threads, and resources (including working memory). |
-| `workflows`     | Workflow run snapshots used for suspend and resume.                                    |
-| `scores`        | Evaluation score records from eval runs.                                               |
-| `observability` | Traces and spans used by observability exporters and Studio.                           |
-| `datasets`      | Dataset records, versioned items, and dataset versions used by experiments.            |
-| `experiments`   | Experiment runs and per-item experiment results.                                       |
+| Domain                | Description                                                                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                 |
+| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                    |
+| `workflowDefinitions` | Persisted [stored workflow](https://mastra.ai/docs/workflows/stored-workflows) definitions (beta). Loaded and live-registered on boot. |
+| `scores`              | Evaluation score records from eval runs.                                                                                               |
+| `observability`       | Traces and spans used by observability exporters and Studio.                                                                           |
+| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                            |
+| `experiments`         | Experiment runs and per-item experiment results.                                                                                       |
 
 The schema definitions below cover the built-in database-backed tables documented for `memory`, `workflows`, `scores`, and `observability`. Other domains, and non-database adapters, use implementation-specific storage structures.
 

package/.docs/reference/streaming/workflows/observeStream.md

@@ -34,7 +34,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-start`**: A step begins execution
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result
 
 ## Related
 

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -66,7 +66,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-start`**: A step begins execution
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result
 
 ## Related
 

package/.docs/reference/streaming/workflows/stream.md

@@ -93,7 +93,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-progress`**: A foreach step reports per-iteration progress (includes `completedCount`, `totalCount`, `currentIndex`, `iterationStatus`, and optional `iterationOutput`)
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result so stream consumers don't need a follow-up fetch
 
 ## Related
 

package/.docs/reference/workflows/stored-workflow-definition.md

@@ -0,0 +1,292 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Stored workflow definition
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+A stored workflow definition is a JSON-compatible `StoredWorkflowGraph` accepted by [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow), the stored-workflow server routes, and the Client SDK workflows API.
+
+See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup and usage example.
+
+## Definition fields
+
+| Field                  | Type                        | Required | Description                                                                    |
+| ---------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------ |
+| `id`                   | `string`                    | Yes      | Unique workflow ID. This is also the ID used to retrieve and run the workflow. |
+| `description`          | `string`                    | No       | Human-readable description                                                     |
+| `inputSchema`          | `JsonSchema`                | Yes      | JSON Schema for the workflow input                                             |
+| `outputSchema`         | `JsonSchema`                | Yes      | JSON Schema for the workflow output                                            |
+| `stateSchema`          | `JsonSchema`                | No       | JSON Schema for shared workflow state                                          |
+| `requestContextSchema` | `JsonSchema`                | No       | JSON Schema for values read from the request context                           |
+| `metadata`             | `Record<string, unknown>`   | No       | Arbitrary JSON metadata preserved through storage                              |
+| `graph`                | `SerializedStepFlowEntry[]` | Yes      | Step entries that make up the workflow                                         |
+
+Schemas use JSON Schema rather than Zod so the definition can round-trip through JSON. Mastra converts each schema to Zod when it registers the workflow.
+
+```json
+{
+  "id": "greeting-workflow",
+  "description": "Returns a greeting for the supplied name",
+  "inputSchema": {
+    "type": "object",
+    "properties": { "name": { "type": "string" } },
+    "required": ["name"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": { "message": { "type": "string" } },
+    "required": ["message"]
+  },
+  "graph": [
+    {
+      "type": "mapping",
+      "id": "create-greeting",
+      "mapConfig": "{\"message\":{\"template\":\"Hello, ${initData.name}!\"}}"
+    }
+  ]
+}
+```
+
+## Graph entries
+
+Entries in the `graph` run in order. Each entry receives the previous entry's output, and the first entry receives the workflow input.
+
+| Entry type    | Description                                            |
+| ------------- | ------------------------------------------------------ |
+| `agent`       | Invoke a registered agent                              |
+| `tool`        | Invoke a registered tool                               |
+| `mapping`     | Reshape data between steps                             |
+| `workflow`    | Invoke a registered workflow as a nested step          |
+| `parallel`    | Run several steps concurrently and merge their outputs |
+| `conditional` | Run every branch whose predicate is true, concurrently |
+| `foreach`     | Run one step per item of an array input                |
+| `loop`        | Repeat a step while or until a predicate holds         |
+| `sleep`       | Pause for a fixed duration                             |
+| `sleepUntil`  | Pause until a fixed date                               |
+
+Code-defined workflows that use [`.agent()`](https://mastra.ai/reference/workflows/workflow-methods/agent) and [`.tool()`](https://mastra.ai/reference/workflows/workflow-methods/tool) produce the same declarative entries when serialized.
+
+### Agent steps
+
+An `agent` entry invokes a registered agent by ID. Agent steps accept `{ prompt: string }` as input and return `{ text: string }` by default.
+
+```json
+{
+  "type": "agent",
+  "id": "summarize",
+  "agentId": "support-agent"
+}
+```
+
+The `id` identifies this call site within the workflow. Later steps address the result as `stepResults.summarize`, regardless of the agent's own ID.
+
+Add an `outputSchema` to request structured output from the agent:
+
+```json
+{
+  "type": "agent",
+  "id": "extract-subtopics",
+  "agentId": "support-agent",
+  "outputSchema": {
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": { "title": { "type": "string" } },
+      "required": ["title"]
+    }
+  }
+}
+```
+
+Use a `mapping` entry before an agent to build its `{ prompt }` input from workflow data.
+
+Agent entries accept an optional `description` and an `options` object:
+
+```json
+{
+  "type": "agent",
+  "id": "summarize",
+  "agentId": "support-agent",
+  "description": "Summarize the incoming request",
+  "options": { "retries": 2, "metadata": { "team": "support" } }
+}
+```
+
+Only `retries` and `metadata` persist. Function-valued options such as `onFinish` and function-valued `toolChoice` are rejected when a code-defined workflow is stored. Other agent call options don't persist.
+
+### Tool steps
+
+A `tool` entry invokes a tool by its registration key from the `Mastra` `tools` object. Mastra resolves the tool's input and output schemas from the registry when it registers the workflow.
+
+```json
+{
+  "type": "tool",
+  "id": "lookup",
+  "toolId": "lookup-customer"
+}
+```
+
+Tool entries accept the same optional `description` and `options` fields as agent entries. Only `retries` and `metadata` persist.
+
+### Mapping steps
+
+A `mapping` entry reshapes data. Its `mapConfig` is a JSON string that encodes an object. Each key becomes a key in the step output, and each descriptor defines one source.
+
+| Descriptor                             | Description                               |
+| -------------------------------------- | ----------------------------------------- |
+| `{ "value": ... }`                     | A constant JSON value                     |
+| `{ "template": "..." }`                | A string built from `${...}` placeholders |
+| `{ "initData": true, "path": "a.b" }`  | A value from the workflow input           |
+| `{ "step": "step-id", "path": "a.b" }` | A value from a preceding step's output    |
+| `{ "requestContextPath": "a.b" }`      | A value from the request context          |
+
+The `step` source also accepts an array of step IDs:
+
+```json
+{ "step": ["escalate", "auto-reply"], "path": "text" }
+```
+
+The first listed step with a non-empty result supplies the value. This can select the branch that ran after a `conditional` entry.
+
+Templates resolve placeholders against `initData`, `inputData`, `state`, `requestContext`, and `stepResults.<step-id>`:
+
+```json
+{
+  "type": "mapping",
+  "id": "build-prompt",
+  "mapConfig": "{\"prompt\":{\"template\":\"Summarize this request: ${initData.request}\"}}"
+}
+```
+
+Objects and arrays resolved by a template are stringified as JSON. A `null` value inside a present result renders as an empty string. A template that references a step without a successful output fails the run.
+
+Mapping entries must be top-level graph entries. They can't be placed inside `parallel`, `conditional`, `foreach`, or `loop` containers.
+
+### Nested workflow steps
+
+A `workflow` entry invokes another registered workflow. The target can be code-defined or stored.
+
+```json
+{
+  "type": "workflow",
+  "id": "lookup-first",
+  "workflowId": "lookup-customer-workflow"
+}
+```
+
+The `id` identifies the call site. The same nested workflow can appear several times under different call-site IDs, and later steps address each result as `stepResults.<id>`. A `workflow` entry also accepts an optional `description`.
+
+### Parallel entries
+
+A `parallel` entry runs several single steps concurrently and merges their outputs into an object keyed by step ID.
+
+```json
+{
+  "type": "parallel",
+  "steps": [
+    { "type": "tool", "id": "first", "toolId": "lookup-customer" },
+    { "type": "tool", "id": "second", "toolId": "lookup-customer" }
+  ]
+}
+```
+
+Each child must be an `agent`, `tool`, or `workflow` entry. All children receive the parallel entry's input directly.
+
+### Conditional entries
+
+A `conditional` entry pairs each step with a declarative predicate and runs every branch whose predicate is true.
+
+```json
+{
+  "type": "conditional",
+  "steps": [
+    { "type": "agent", "id": "escalate", "agentId": "support-agent" },
+    { "type": "agent", "id": "auto-reply", "agentId": "support-agent" }
+  ],
+  "predicates": [
+    { "op": "eq", "left": { "path": "inputData.priority" }, "right": { "literal": "urgent" } },
+    { "op": "ne", "left": { "path": "inputData.priority" }, "right": { "literal": "urgent" } }
+  ]
+}
+```
+
+Each child must be an `agent`, `tool`, or `workflow` entry, and each child needs a predicate. All children receive the conditional entry's input directly.
+
+### Predicates
+
+Conditional entries and loops use a JSON predicate DSL. Operands are `{ "path": "..." }` references or `{ "literal": ... }` values. Paths resolve against `initData`, `inputData`, `stepResults`, and `state`.
+
+| Operator                             | Shape                                        |
+| ------------------------------------ | -------------------------------------------- |
+| `eq`, `ne`, `lt`, `lte`, `gt`, `gte` | `{ "op": "eq", "left": ..., "right": ... }`  |
+| `in`, `notIn`                        | `{ "op": "in", "value": ..., "set": [...] }` |
+| `exists`, `notExists`                | `{ "op": "exists", "path": "..." }`          |
+| `truthy`, `falsy`                    | `{ "op": "truthy", "value": ... }`           |
+| `and`, `or`                          | `{ "op": "and", "args": [...] }`             |
+| `not`                                | `{ "op": "not", "arg": ... }`                |
+
+Missing paths don't throw. Path-based operators return `false` when the path can't be resolved. Use `exists` or `notExists` to distinguish a missing value from a falsy value.
+
+### Foreach entries
+
+A `foreach` entry runs its body once for each item in an array input. The preceding entry must produce a raw array. Results preserve input order, and concurrency defaults to `1`.
+
+```json
+{
+  "type": "foreach",
+  "step": { "type": "workflow", "id": "write-blurb", "workflowId": "blurb-workflow" },
+  "opts": { "concurrency": 3 }
+}
+```
+
+The body can be an `agent`, `tool`, or `workflow` entry, but not a `mapping` entry.
+
+### Loop entries
+
+A `loop` repeats one step while (`dowhile`) or until (`dountil`) a predicate holds.
+
+```json
+{
+  "type": "loop",
+  "loopType": "dountil",
+  "step": { "type": "tool", "id": "poll", "toolId": "check-status" },
+  "predicate": {
+    "op": "eq",
+    "left": { "path": "inputData.status" },
+    "right": { "literal": "done" }
+  }
+}
+```
+
+The loop body must be a single step, and stored loops require a declarative predicate.
+
+### Sleep entries
+
+A `sleep` entry pauses for a fixed number of milliseconds. A `sleepUntil` entry pauses until a fixed date represented by an ISO date string. Stored definitions require literal values.
+
+```json
+{ "type": "sleep", "id": "wait", "duration": 5000 }
+```
+
+```json
+{ "type": "sleepUntil", "id": "wait-for-launch", "date": "2027-01-01T00:00:00.000Z" }
+```
+
+Use a code-defined workflow when the duration or date must be calculated at runtime.
+
+## Validation
+
+Mastra validates definitions before it persists or registers them:
+
+- Structure: Entry shapes and required fields, including placement rules such as top-level-only mappings.
+- References: Each `agentId` and `workflowId` must resolve against the live registries or the same bundle. A `toolId` must match a tool registration key.
+- Schema flow: Each entry's input must be compatible with the preceding output, including inferred mapping outputs.
+
+Validation errors include a dotted path, such as `graph.2.steps.0`, that identifies the invalid entry.
+
+## Related
+
+- [Use stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow)
+- [`Mastra.addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows)
+- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows)

package/.docs/reference/workflows/workflow-methods/agent.md

@@ -0,0 +1,62 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workflow\.agent()
+
+The `.agent()` method adds an agent as a declarative step. The step accepts `{ prompt: string }` as input and returns `{ text: string }` by default. Use `.map()` before the agent to build the prompt from workflow data.
+
+Unlike wrapping an agent with `createStep()`, `.agent()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows).
+
+## Usage example
+
+```typescript
+workflow
+  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
+  .agent(testAgent)
+  .commit();
+```
+
+## Parameters
+
+**agentOrId** (`Agent | string`): An agent instance, or the ID of an agent registered on the Mastra instance. When passing an ID, the agent is resolved from the registry at execution time.
+
+**options** (`AgentStepOptions & { structuredOutput?: { schema }, retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): Agent call options such as maxSteps, modelSettings, memory, and providerOptions, plus step-level retries, scorers, and metadata. Per-request fields such as requestContext, resourceId, threadId, and onStepFinish are managed by the workflow engine and excluded.
+
+**stepOptions** (`{ id?: string }`): The step's call-site ID within the workflow. Defaults to the agent's ID. Set this when the same agent appears more than once in one workflow.
+
+## Returns
+
+**workflow** (`Workflow`): The workflow instance for method chaining
+
+## Structured output
+
+By default the step's output is `{ text: string }`. Pass `structuredOutput.schema` to make the step return that shape instead. The schema becomes the step's output schema, so later steps chain against it with full type safety:
+
+```typescript
+workflow
+  .agent(testAgent, {
+    structuredOutput: {
+      schema: z.object({
+        subtopics: z.array(z.string()),
+      }),
+    },
+  })
+  .commit();
+```
+
+## Referencing an agent by ID
+
+Pass a string to reference a registered agent without importing it. The agent must be registered on the Mastra instance when the workflow runs:
+
+```typescript
+workflow.agent("test-agent", { maxSteps: 3 }).commit();
+```
+
+## Persisting agent steps
+
+Workflows built with `.agent()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-workflows) use. Only `retries` and `metadata` round-trip through storage. Options that hold functions, such as `onFinish` or a function-valued `toolChoice`, throw an error when the workflow is stored.
+
+## Related
+
+- [Agents and Tools](https://mastra.ai/docs/workflows/agents-and-tools)
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [Workflow.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool)

package/.docs/reference/workflows/workflow-methods/tool.md

@@ -0,0 +1,43 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workflow\.tool()
+
+The `.tool()` method adds a tool as a declarative step. The tool's own input and output schemas apply, so the previous step's output must satisfy the tool's input schema. Use `.map()` to transform the data if they don't match.
+
+Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows).
+
+## Usage example
+
+```typescript
+workflow.tool(testTool).commit();
+```
+
+## Parameters
+
+**toolOrId** (`Tool | string`): A tool instance, or the ID of a tool registered on the Mastra instance. When passing an ID, the tool is resolved from the registry at execution time.
+
+**options** (`{ retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): Step-level retry count, scorers, and metadata for the tool step.
+
+**stepOptions** (`{ id?: string }`): The step's call-site ID within the workflow. Defaults to the tool's ID. Set this when the same tool appears more than once in one workflow.
+
+## Returns
+
+**workflow** (`Workflow`): The workflow instance for method chaining
+
+## Referencing a tool by ID
+
+Pass a string to reference a registered tool without importing it. The tool must be registered on the Mastra instance when the workflow runs:
+
+```typescript
+workflow.tool("lookup-customer", { retries: 2 }).commit();
+```
+
+## Persisting tool steps
+
+Workflows built with `.tool()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-workflows) use. Only `retries` and `metadata` round-trip through storage. A function-valued `scorers` option throws an error when the workflow is stored.
+
+## Related
+
+- [Agents and Tools](https://mastra.ai/docs/workflows/agents-and-tools)
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)