npm - @mastra/core - Versions diffs - 1.6.0 → 1.7.0-alpha.0 - Mend

@mastra/core 1.6.0 → 1.7.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (452) hide show

package/dist/docs/references/docs-agents-networks.md DELETED Viewed

@@ -1,290 +0,0 @@
-# Agent Networks
-Agent networks in Mastra coordinate multiple agents, workflows, and tools to handle tasks that aren't clearly defined upfront but can be inferred from the user's message or context. A top-level **routing agent** (a Mastra agent with other agents, workflows, and tools configured) uses an LLM to interpret the request and decide which primitives (subagents, workflows, or tools) to call, in what order, and with what data.
-## When to use networks
-Use networks for complex tasks that require coordination across multiple primitives. Unlike workflows, which follow a predefined sequence, networks rely on LLM reasoning to interpret the request and decide what to run.
-## Core principles
-Mastra agent networks operate using these principles:
-- Memory is required when using `.network()` and is used to store task history and determine when a task is complete.
-- Primitives are selected based on their descriptions. Clear, specific descriptions improve routing. For workflows and tools, the input schema helps determine the right inputs at runtime.
-- If multiple primitives have overlapping functionality, the agent favors the more specific one, using a combination of schema and descriptions to decide which to run.
-## Creating an agent network
-An agent network is built around a top-level routing agent that delegates tasks to subagents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-import { researchAgent } from "./research-agent";
-import { writingAgent } from "./writing-agent";
-import { cityWorkflow } from "../workflows/city-workflow";
-import { weatherTool } from "../tools/weather-tool";
-export const routingAgent = new Agent({
-  id: "routing-agent",
-  name: "Routing Agent",
-  instructions: `
-      You are a network of writers and researchers.
-      The user will ask you to research a topic.
-      Always respond with a complete report—no bullet points.
-      Write in full paragraphs, like a blog post.
-      Do not answer with incomplete or uncertain information.`,
-  model: "openai/gpt-5.1",
-  agents: {
-    researchAgent,
-    writingAgent,
-  },
-  workflows: {
-    cityWorkflow,
-  },
-  tools: {
-    weatherTool,
-  },
-  memory: new Memory({
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      url: "file:../mastra.db",
-    }),
-  }),
-});
-```
-### Writing descriptions for network primitives
-When configuring a Mastra agent network, each primitive (agent, workflow, or tool) needs a clear description to help the routing agent decide which to use. The routing agent uses each primitive's description and schema to determine what it does and how to use it. Clear descriptions and well-defined input and output schemas improve routing accuracy.
-#### Agent descriptions
-Each subagent in a network should include a clear `description` that explains what the agent does.
-```typescript
-export const researchAgent = new Agent({
-  id: "research-agent",
-  name: "Research Agent",
-  description: `This agent gathers concise research insights in bullet-point form.
-    It's designed to extract key facts without generating full
-    responses or narrative content.`,
-});
-```
-```typescript
-export const writingAgent = new Agent({
-  id: "writing-agent",
-  name: "Writing Agent",
-  description: `This agent turns researched material into well-structured
-    written content. It produces full-paragraph reports with no bullet points,
-    suitable for use in articles, summaries, or blog posts.`,
-});
-```
-#### Workflow descriptions
-Workflows in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
-```typescript
-export const cityWorkflow = createWorkflow({
-  id: "city-workflow",
-  description: `This workflow handles city-specific research tasks.
-    It first gathers factual information about the city, then synthesizes
-    that research into a full written report. Use it when the user input
-    includes a city to be researched.`,
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  outputSchema: z.object({
-    text: z.string(),
-  }),
-});
-```
-#### Tool descriptions
-Tools in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
-```typescript
-export const weatherTool = createTool({
-  id: "weather-tool",
-  description: ` Retrieves current weather information using the wttr.in API.
-    Accepts a city or location name as input and returns a short weather summary.
-    Use this tool whenever up-to-date weather data is requested.
-  `,
-  inputSchema: z.object({
-    location: z.string(),
-  }),
-  outputSchema: z.object({
-    weather: z.string(),
-  }),
-});
-```
-## Calling agent networks
-Call a Mastra agent network using `.network()` with a user message. The method returns a stream of events that you can iterate over to track execution progress and retrieve the final result.
-### Agent example
-In this example, the network interprets the message and would route the request to both the `researchAgent` and `writingAgent` to generate a complete response.
-```typescript
-const result = await routingAgent.network(
-  "Tell me three cool ways to use Mastra",
-);
-for await (const chunk of result) {
-  console.log(chunk.type);
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-#### Agent output
-The following `chunk.type` events are emitted during this request:
-```text
-routing-agent-start
-routing-agent-end
-agent-execution-start
-agent-execution-event-start
-agent-execution-event-step-start
-agent-execution-event-text-start
-agent-execution-event-text-delta
-agent-execution-event-text-end
-agent-execution-event-step-finish
-agent-execution-event-finish
-agent-execution-end
-network-execution-event-step-finish
-```
-## Workflow example
-In this example, the routing agent recognizes the city name in the message and runs the `cityWorkflow`. The workflow defines steps that call the `researchAgent` to gather facts, then the `writingAgent` to generate the final text.
-```typescript
-const result = await routingAgent.network(
-  "Tell me some historical facts about London",
-);
-for await (const chunk of result) {
-  console.log(chunk.type);
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-#### Workflow output
-The following `chunk.type` events are emitted during this request:
-```text
-routing-agent-end
-workflow-execution-start
-workflow-execution-event-workflow-start
-workflow-execution-event-workflow-step-start
-workflow-execution-event-workflow-step-result
-workflow-execution-event-workflow-finish
-workflow-execution-end
-routing-agent-start
-network-execution-event-step-finish
-```
-### Tool example
-In this example, the routing agent skips the `researchAgent`, `writingAgent`, and `cityWorkflow`, and calls the `weatherTool` directly to complete the task.
-```typescript
-const result = await routingAgent.network("What's the weather in London?");
-for await (const chunk of result) {
-  console.log(chunk.type);
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-#### Tool output
-The following `chunk.type` events are emitted during this request:
-```text
-routing-agent-start
-routing-agent-end
-tool-execution-start
-tool-execution-end
-network-execution-event-step-finish
-```
-## Structured output
-When you need typed, validated results from a network, use the `structuredOutput` option. After the network completes its task, it generates a structured response matching your schema.
-```typescript
-import { z } from "zod";
-const resultSchema = z.object({
-  summary: z.string().describe("A brief summary of the findings"),
-  recommendations: z.array(z.string()).describe("List of recommendations"),
-  confidence: z.number().min(0).max(1).describe("Confidence score"),
-});
-const stream = await routingAgent.network("Research AI trends", {
-  structuredOutput: {
-    schema: resultSchema,
-  },
-});
-// Consume the stream
-for await (const chunk of stream) {
-  if (chunk.type === "network-object") {
-    // Partial object during generation
-    console.log("Partial:", chunk.payload.object);
-  }
-  if (chunk.type === "network-object-result") {
-    // Final structured object
-    console.log("Final:", chunk.payload.object);
-  }
-}
-// Get the typed result
-const result = await stream.object;
-console.log(result?.summary);
-console.log(result?.recommendations);
-console.log(result?.confidence);
-```
-### Streaming partial objects
-For real-time updates during structured output generation, use `objectStream`:
-```typescript
-const stream = await routingAgent.network("Analyze market data", {
-  structuredOutput: { schema: resultSchema },
-});
-// Stream partial objects as they're generated
-for await (const partial of stream.objectStream) {
-  console.log("Building result:", partial);
-}
-// Get the final typed result
-const final = await stream.object;
-```
-## Related
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
-- [Workflows Overview](https://mastra.ai/docs/workflows/overview)
-- [Request Context](https://mastra.ai/docs/server/request-context)
-- [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)

package/dist/docs/references/docs-agents-overview.md DELETED Viewed

@@ -1,309 +0,0 @@
-# Using Agents
-Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or agent networks.
-![Agents overview](/assets/images/agents-overview-1e3bb3b8cf0d13be675394ad41418ea7.jpg)
-> **Watch an introduction:** An introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
-## Setting up agents
-### Installation
-1. Add the Mastra core package to your project:
-   **npm**:
-   ```bash
-   npm install @mastra/core@latest
-   ```
-   **pnpm**:
-   ```bash
-   pnpm add @mastra/core@latest
-   ```
-   **Yarn**:
-   ```bash
-   yarn add @mastra/core@latest
-   ```
-   **Bun**:
-   ```bash
-   bun add @mastra/core@latest
-   ```
-2. Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
-   ```bash
-   OPENAI_API_KEY=<your-api-key>
-   ```
-   > **Note:** Mastra supports more than 600 models. Choose from the [full list](https://mastra.ai/models).
-3. Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
-   ```typescript
-   import { Agent } from "@mastra/core/agent";
-   export const testAgent = new Agent({
-     id: "test-agent",
-     name: "Test Agent",
-     instructions: "You are a helpful assistant.",
-     model: "openai/gpt-5.1",
-   });
-   ```
-### Instruction formats
-Instructions define the agent's behavior, personality, and capabilities. They are system-level prompts that establish the agent's core identity and expertise.
-Instructions can be provided in multiple formats for greater flexibility. The examples below illustrate the supported shapes:
-```typescript
-// String (most common)
-instructions: "You are a helpful assistant.";
-// Array of strings
-instructions: [
-  "You are a helpful assistant.",
-  "Always be polite.",
-  "Provide detailed answers.",
-];
-// Array of system messages
-instructions: [
-  { role: "system", content: "You are a helpful assistant." },
-  { role: "system", content: "You have expertise in TypeScript." },
-];
-```
-### Provider-specific options
-Each model provider also enables a few different options, including prompt caching and configuring reasoning. We provide a `providerOptions` flag to manage these. You can set `providerOptions` on the instruction level to set different caching strategy per system instruction/prompt.
-```typescript
-// With provider-specific options (e.g., caching, reasoning)
-instructions: {
-  role: "system",
-  content:
-    "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
-  providerOptions: {
-    openai: { reasoningEffort: "high" },        // OpenAI's reasoning models
-    anthropic: { cacheControl: { type: "ephemeral" } }  // Anthropic's prompt caching
-  }
-}
-```
-> **Info:** Visit [Agent reference](https://mastra.ai/reference/agents/agent) for more information.
-### Dynamic instructions
-Instructions can be provided as an async function, allowing you to resolve prompts at runtime. This enables patterns like personalizing instructions based on user context, fetching prompts from external registry services, and running A/B tests with different variants.
-> **Info:** See [Dynamic instructions](https://mastra.ai/docs/server/request-context) for examples.
-### Registering an agent
-Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
-```typescript
-import { Mastra } from "@mastra/core";
-import { testAgent } from "./agents/test-agent";
-export const mastra = new Mastra({
-  agents: { testAgent },
-});
-```
-### Registering subagents
-You can register subagents within an agent. They'll be executed as tools from the parent agent. Read the [using agents as tools](https://mastra.ai/docs/agents/using-tools) documentation to learn more.
-### Registering subworkflows
-You can register subworkflows within an agent. They'll be executed as tools from the parent agent. Read the [using workflows as tools](https://mastra.ai/docs/agents/using-tools) documentation to learn more.
-## Referencing an agent
-You can call agents from workflow steps, tools, the Mastra Client, or the command line. Get a reference by calling `.getAgent()` on your `mastra` or `mastraClient` instance, depending on your setup:
-```typescript
-const testAgent = mastra.getAgent("testAgent");
-```
-> **Info:** `mastra.getAgent()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
-## Generating responses
-Agents can return results in two ways: generating the full output before returning it or streaming tokens in real time. Choose the approach that fits your use case: generate for short, internal responses or debugging, and stream to deliver pixels to end users as quickly as possible.
-**Generate**:
-Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
-(The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
-```typescript
-const response = await testAgent.generate([
-  { role: "user", content: "Help me organize my day" },
-  { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
-  { role: "user", content: "I take lunch between 12:30 and 13:30" },
-  {
-    role: "user",
-    content: "I have meetings Monday to Friday between 10:30 and 11:30",
-  },
-]);
-console.log(response.text);
-```
-**Stream**:
-Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
-(The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
-```typescript
-const stream = await testAgent.stream([
-  { role: "user", content: "Help me organize my day" },
-  { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
-  { role: "user", content: "I take lunch between 12:30 and 13:30" },
-  {
-    role: "user",
-    content: "I have meetings Monday to Friday between 10:30 and 11:30",
-  },
-]);
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
-```
-### Completion using `onFinish()`
-When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete. It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
-```typescript
-const stream = await testAgent.stream("Help me organize my day", {
-  onFinish: ({ steps, text, finishReason, usage }) => {
-    console.log({ steps, text, finishReason, usage });
-  },
-});
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
-```
-> **Info:** Visit [.generate()](https://mastra.ai/reference/agents/generate) or [.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
-## Structured output
-Agents can return structured, type-safe data using Zod or JSON Schema. The parsed result is available on `response.object`.
-> **Info:** Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more information.
-## Analyzing images
-Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the `content` array. You can combine image content with text prompts to guide the agent's analysis.
-```typescript
-const response = await testAgent.generate([
-  {
-    role: "user",
-    content: [
-      {
-        type: "image",
-        image: "https://placebear.com/cache/395-205.jpg",
-        mimeType: "image/jpeg",
-      },
-      {
-        type: "text",
-        text: "Describe the image in detail, and extract all the text in the image.",
-      },
-    ],
-  },
-]);
-console.log(response.text);
-```
-## Using `maxSteps`
-The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 1, but can be increased:
-```typescript
-const response = await testAgent.generate("Help me organize my day", {
-  maxSteps: 10,
-});
-console.log(response.text);
-```
-## Using `onStepFinish`
-You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
-`onStepFinish` is only available when streaming or generating text without structured output.
-```typescript
-const response = await testAgent.generate("Help me organize my day", {
-  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
-    console.log({ text, toolCalls, toolResults, finishReason, usage });
-  },
-});
-```
-## Using tools
-Agents can use tools to go beyond language generation, enabling structured interactions with external APIs and services. Tools allow agents to access data and perform clearly defined operations in a reliable, repeatable way.
-```typescript
-export const testAgent = new Agent({
-  id: "test-agent",
-  name: "Test Agent",
-  tools: { testTool },
-});
-```
-> **Info:** Visit [Using Tools](https://mastra.ai/docs/agents/using-tools) for more information.
-## Using `RequestContext`
-Use `RequestContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
-```typescript
-export type UserTier = {
-  "user-tier": "enterprise" | "pro";
-};
-export const testAgent = new Agent({
-  id: "test-agent",
-  name: "Test Agent",
-  model: ({ requestContext }) => {
-    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
-    return userTier === "enterprise"
-      ? "openai/gpt-5"
-      : "openai/gpt-4.1-nano";
-  },
-});
-```
-> **Info:** See [Request Context](https://mastra.ai/docs/server/request-context) for more information.
-> **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
-## Testing with Studio
-Use [Studio](https://mastra.ai/docs/getting-started/studio) to test agents with different messages, inspect tool calls and responses, and debug agent behavior.
-## Related
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
-- [Request Context](https://mastra.ai/docs/server/request-context)