@mastra/core 1.6.0 → 1.7.0-alpha.0

package/dist/docs/references/reference-tools-create-tool.md

@@ -1,237 +0,0 @@
-# createTool()
-
-The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
-
-## Usage example
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const tool = createTool({
-  id: "test-tool",
-  description: "Reverse the input string",
-  inputSchema: z.object({
-    input: z.string(),
-  }),
-  outputSchema: z.object({
-    output: z.string(),
-  }),
-  execute: async (inputData) => {
-    const reversed = inputData.input.split("").reverse().join("");
-
-    return {
-      output: reversed,
-    };
-  },
-});
-```
-
-## Example with MCP Annotations
-
-When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const weatherTool = createTool({
-  id: "get-weather",
-  description: "Get current weather for a location",
-  inputSchema: z.object({
-    location: z.string().describe("City name or coordinates"),
-  }),
-  // MCP-specific properties
-  mcp: {
-    // Annotations for client behavior hints
-    annotations: {
-      title: "Weather Lookup",           // Human-readable display name
-      readOnlyHint: true,                // Tool doesn't modify environment
-      destructiveHint: false,            // Tool doesn't perform destructive updates
-      idempotentHint: true,              // Same args = same result
-      openWorldHint: true,               // Interacts with external API
-    },
-    // Custom metadata for client-specific functionality
-    _meta: {
-      version: "1.0.0",
-      category: "weather",
-    },
-  },
-  execute: async (inputData) => {
-    const weather = await fetchWeather(inputData.location);
-    return { weather };
-  },
-});
-```
-
-## Parameters
-
-**id:** (`string`): A unique identifier for the tool.
-
-**description:** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
-
-**inputSchema?:** (`Zod schema`): A Zod schema defining the expected input parameters for the tool's \`execute\` function.
-
-**outputSchema?:** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
-
-**suspendSchema?:** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
-
-**resumeSchema?:** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
-
-**requireApproval?:** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
-
-**mcp?:** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
-
-**requestContextSchema?:** (`Zod schema`): A Zod schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
-
-**execute:** (`function`): input:z.infer\<TInput>The validated input data based on inputSchemacontext?:ToolExecutionContextOptional execution context containing metadataRequestContextTracingContextAbortSignalAgentToolExecutionContextWorkflowToolExecutionContextMCPToolExecutionContext
-
-**onInputStart?:** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onInputDelta?:** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onInputAvailable?:** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onOutput?:** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-## Returns
-
-The `createTool()` function returns a `Tool` object.
-
-**Tool:** (`object`): An object representing the defined tool, ready to be added to an agent.
-
-## Tool Lifecycle Hooks
-
-Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
-
-### Available Hooks
-
-#### onInputStart
-
-Called when tool call input streaming begins, before any input data is received.
-
-```typescript
-export const tool = createTool({
-  id: "example-tool",
-  description: "Example tool with hooks",
-  onInputStart: ({ toolCallId, messages, abortSignal }) => {
-    console.log(`Tool ${toolCallId} input streaming started`);
-  },
-});
-```
-
-#### onInputDelta
-
-Called for each incremental chunk of input text as it streams in. Useful for showing real-time progress or parsing partial JSON.
-
-```typescript
-export const tool = createTool({
-  id: "example-tool",
-  description: "Example tool with hooks",
-  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
-    console.log(`Received input chunk: ${inputTextDelta}`);
-  },
-});
-```
-
-#### onInputAvailable
-
-Called when the complete tool input is available and has been parsed and validated against the `inputSchema`.
-
-```typescript
-export const tool = createTool({
-  id: "example-tool",
-  description: "Example tool with hooks",
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
-    console.log(`Tool received complete input:`, input);
-    // input is fully typed based on inputSchema
-  },
-});
-```
-
-#### onOutput
-
-Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
-
-```typescript
-export const tool = createTool({
-  id: "example-tool",
-  description: "Example tool with hooks",
-  outputSchema: z.object({
-    result: z.string(),
-  }),
-  execute: async (input) => {
-    return { result: "Success" };
-  },
-  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
-    console.log(`${toolName} execution completed:`, output);
-    // output is fully typed based on outputSchema
-  },
-});
-```
-
-### Hook Execution Order
-
-For a typical streaming tool call, the hooks are invoked in this order:
-
-1. **onInputStart** - Input streaming begins
-2. **onInputDelta** - Called multiple times as chunks arrive
-3. **onInputAvailable** - Complete input is parsed and validated
-4. Tool's **execute** function runs
-5. **onOutput** - Tool has completed successfully
-
-### Hook Parameters
-
-All hooks receive a parameter object with these common properties:
-
-- `toolCallId` (string): Unique identifier for this specific tool call
-- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
-
-Additionally:
-
-- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
-- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
-- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
-- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
-
-### Error Handling
-
-Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
-
-## MCP Tool Annotations
-
-When exposing tools via the Model Context Protocol (MCP), you can provide annotations that describe tool behavior. These annotations help MCP clients like OpenAI Apps SDK understand how to present and handle your tools.
-
-MCP-specific properties are grouped under the `mcp` property, which includes `annotations` and `_meta`:
-
-```typescript
-mcp: {
-  annotations: { /* behavior hints */ },
-  _meta: { /* custom metadata */ },
-}
-```
-
-### ToolAnnotations Properties
-
-**title?:** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
-
-**readOnlyHint?:** (`boolean`): If true, the tool does not modify its environment. This hint indicates the tool only reads data and has no side effects. Defaults to false.
-
-**destructiveHint?:** (`boolean`): If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. This hint helps clients determine if confirmation should be required. Defaults to true.
-
-**idempotentHint?:** (`boolean`): If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment. This hint indicates idempotent behavior. Defaults to false.
-
-**openWorldHint?:** (`boolean`): If true, this tool may interact with an 'open world' of external entities (e.g., web search, external APIs). If false, the tool's domain is closed and fully defined. Defaults to true.
-
-These annotations follow the [MCP specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations) and are passed through when tools are listed via MCP.
-
-## Related
-
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
-- [Using Tools with Agents](https://mastra.ai/docs/agents/using-tools)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
-- [Tool Streaming](https://mastra.ai/docs/streaming/tool-streaming)
-- [Request Context](https://mastra.ai/docs/server/request-context)

package/dist/docs/references/reference-tools-graph-rag-tool.md

@@ -1,185 +0,0 @@
-# createGraphRAGTool()
-
-The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph of semantic relationships between documents. It uses the `GraphRAG` system under the hood to provide graph-based retrieval, finding relevant content through both direct similarity and connected relationships.
-
-## Usage Example
-
-```typescript
-import { createGraphRAGTool } from "@mastra/rag";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-
-const graphTool = createGraphRAGTool({
-  vectorStoreName: "pinecone",
-  indexName: "docs",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  graphOptions: {
-    dimension: 1536,
-    threshold: 0.7,
-    randomWalkSteps: 100,
-    restartProb: 0.15,
-  },
-});
-```
-
-## Parameters
-
-> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
-
-**id?:** (`string`): Custom ID for the tool. By default: 'GraphRAG {vectorStoreName} {indexName} Tool'. (Set at creation only.)
-
-**description?:** (`string`): Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.' (Set at creation only.)
-
-**vectorStoreName:** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
-
-**indexName:** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
-
-**model:** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
-
-**enableFilter?:** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
-
-**includeSources?:** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
-
-**graphOptions?:** (`GraphOptions`): Configuration for the graph-based retrieval (Default: `Default graph options`)
-
-**providerOptions?:** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
-
-**vectorStore?:** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
-
-### GraphOptions
-
-**dimension?:** (`number`): Dimension of the embedding vectors (Default: `1536`)
-
-**threshold?:** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
-
-**randomWalkSteps?:** (`number`): Number of steps in random walk for graph traversal. (Can be set at creation or overridden at runtime.) (Default: `100`)
-
-**restartProb?:** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.) (Default: `0.15`)
-
-## Returns
-
-The tool returns an object with:
-
-**relevantContext:** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
-
-**sources:** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
-
-### QueryResult object structure
-
-```typescript
-{
-  id: string;         // Unique chunk/document identifier
-  metadata: any;      // All metadata fields (document ID, etc.)
-  vector: number[];   // Embedding vector (if available)
-  score: number;      // Similarity score for this retrieval
-  document: string;   // Full chunk/document text (if available)
-}
-```
-
-## Default Tool Description
-
-The default description focuses on:
-
-- Analyzing relationships between documents
-- Finding patterns and connections
-- Answering complex queries
-
-## Advanced Example
-
-```typescript
-const graphTool = createGraphRAGTool({
-  vectorStoreName: "pinecone",
-  indexName: "docs",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  graphOptions: {
-    dimension: 1536,
-    threshold: 0.8, // Higher similarity threshold
-    randomWalkSteps: 200, // More exploration steps
-    restartProb: 0.2, // Higher restart probability
-  },
-});
-```
-
-## Example with Custom Description
-
-```typescript
-const graphTool = createGraphRAGTool({
-  vectorStoreName: "pinecone",
-  indexName: "docs",
-  model: "openai/text-embedding-3-small	",
-  description:
-    "Analyze document relationships to find complex patterns and connections in our company's historical data",
-});
-```
-
-This example shows how to customize the tool description for a specific use case while maintaining its core purpose of relationship analysis.
-
-## Example: Using Request Context
-
-```typescript
-const graphTool = createGraphRAGTool({
-  vectorStoreName: "pinecone",
-  indexName: "docs",
-  model: "openai/text-embedding-3-small	",
-});
-```
-
-When using request context, provide required parameters at execution time via the request context:
-
-```typescript
-const requestContext = new RequestContext<{
-  vectorStoreName: string;
-  indexName: string;
-  topK: number;
-  filter: any;
-}>();
-requestContext.set("vectorStoreName", "my-store");
-requestContext.set("indexName", "my-index");
-requestContext.set("topK", 5);
-requestContext.set("filter", { category: "docs" });
-requestContext.set("randomWalkSteps", 100);
-requestContext.set("restartProb", 0.15);
-
-const response = await agent.generate(
-  "Find documentation from the knowledge base.",
-  {
-    requestContext,
-  },
-);
-```
-
-For more information on request context, please see:
-
-- [Agent Request Context](https://mastra.ai/docs/server/request-context)
-- [Request Context](https://mastra.ai/docs/server/request-context)
-
-## Dynamic Vector Store for Multi-Tenant Applications
-
-For multi-tenant applications where each tenant has isolated data, you can pass a resolver function instead of a static vector store:
-
-```typescript
-import { createGraphRAGTool, VectorStoreResolver } from "@mastra/rag";
-import { PgVector } from "@mastra/pg";
-
-const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
-  const tenantId = requestContext?.get("tenantId");
-
-  return new PgVector({
-    id: `pg-vector-${tenantId}`,
-    connectionString: process.env.POSTGRES_CONNECTION_STRING!,
-    schemaName: `tenant_${tenantId}`,
-  });
-};
-
-const graphTool = createGraphRAGTool({
-  indexName: "embeddings",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  vectorStore: vectorStoreResolver,
-});
-```
-
-See [createVectorQueryTool - Dynamic Vector Store](https://mastra.ai/reference/tools/vector-query-tool) for more details.
-
-## Related
-
-- [createVectorQueryTool](https://mastra.ai/reference/tools/vector-query-tool)
-- [GraphRAG](https://mastra.ai/reference/rag/graph-rag)