@mastra/core 1.15.0-alpha.0 → 1.15.0-alpha.2

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

@@ -1,110 +1,31 @@
-# Using agents
+# Agents overview
 
-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 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 multi-agent systems.
 
-![Agents overview](/assets/images/agents-overview-1e3bb3b8cf0d13be675394ad41418ea7.jpg)
+## When to use agents
 
-> **Watch an introduction:** An introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+Use agents when the task is open-ended and the steps aren't known in advance. An agent decides which tools to call, how many times to loop, and when to stop. You provide the goal and constraints instead of defining each step. For predetermined, multi-step processes with explicit control flow, use [workflows](https://mastra.ai/docs/workflows/overview) instead.
 
-## Setting up agents
+> **Tip:** Watch an introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw).
 
-### Installation
+## Quickstart
 
-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.4',
-   })
-   ```
-
-### Instruction formats
-
-Instructions define the agent's behavior, personality, and capabilities. They're 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:
+Create an agent by instantiating the `Agent` class from `@mastra/core` and provide the required properties:
 
 ```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.' },
-]
-```
+import { Agent } from '@mastra/core/agent'
 
-### 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
-  }
-}
+export const testAgent = new Agent({
+  id: 'test-agent',
+  name: 'Test Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.4',
+})
 ```
 
-> **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.
+The `instructions` define the agent's behavior, personality, and capabilities. They're system-level prompts that establish the agent's core identity and expertise. The `model` is specified as `'provider/model-name'` using Mastra's [model router](https://mastra.ai/models).
 
-> **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:
+To make the agent available throughout your application, register it in your Mastra instance (typically located in `src/mastra/index.ts`):
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -115,190 +36,60 @@ export const mastra = new Mastra({
 })
 ```
 
-### Registering subagents
+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.
 
-You can register subagents within an agent using the `agents` property. Adding subagents makes the parent agent a supervisor. A supervisor can delegate tasks to subagents, control delegations with hooks, filter context, and monitor progress using the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents). Read the [using agents as tools](https://mastra.ai/docs/agents/using-tools) documentation for setup details.
+> **Tip:** Use [Studio](https://mastra.ai/docs/getting-started/studio) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
 
-### Registering subworkflows
+> **Note:** Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
-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.
+## Use your agent
 
-## Referencing an agent
+After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. Visit the [guides section](https://mastra.ai/guides) to learn how to use agents in your framework of choice.
 
-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.
+When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
 **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',
-  },
-])
+Returns the full response after all tool calls and steps complete. The result includes `text`, `toolCalls`, `toolResults`, `steps`, and token `usage` statistics.
 
+```ts
+const agent = mastra.getAgentById('test-agent')
+const response = await agent.generate('Help me organize my day')
 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.)
+Returns a stream you can consume as tokens arrive. The result exposes `textStream` for incremental output and promises for `toolCalls`, `toolResults`, `steps`, and token `usage` that resolve when the stream finishes.
 
-```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',
-  },
-])
+```ts
+const agent = mastra.getAgentById('test-agent')
+const stream = await agent.stream('Help me organize my day')
 
 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 5, 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.4' : 'openai/gpt-5-mini'
-  },
-})
-```
-
-> **Info:** See [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+## Expand your agent
 
-> **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
+Once your agent is running, use this table to find the right page for what you want to do next:
 
-## Testing with Studio
+| Goal                                                           | Start here                                                             |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Keep context and preferences across conversations              | [Memory](https://mastra.ai/docs/memory/overview)                       |
+| Get typed objects back instead of plain text                   | [Structured output](https://mastra.ai/docs/agents/structured-output)   |
+| Human-in-the-loop: Pause execution and wait for human approval | [Approval](https://mastra.ai/docs/agents/agent-approval)               |
+| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)   |
+| Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
+| Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
+| Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
+| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/docs/agents/adding-voice)                    |
 
-Use [Studio](https://mastra.ai/docs/getting-started/studio) to test agents with different messages, inspect tool calls and responses, and debug agent behavior.
+## Multi-agent systems
 
-## Related
+A multi-agent system uses multiple agents to solve a task that is too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
 
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
-- [Supervisor Agents](https://mastra.ai/docs/agents/supervisor-agents)
-- [Request Context](https://mastra.ai/docs/server/request-context)
+Read the [conceptual overview of multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems) to learn how you can apply different patterns with Mastra.