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 multi-agent systems.

When to use agents

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 instead.

tip

Watch an introduction to agents, and how they compare to workflows on YouTube (7 minutes).

Quickstart

Create an agent by instantiating the Agent class from @mastra/core and provide the required properties:

src/mastra/agents/test-agent.ts

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',
})

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.

To make the agent available throughout your application, register it in your Mastra instance (typically located in src/mastra/index.ts):

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { testAgent } from './agents/test-agent'

export const mastra = new Mastra({
  agents: { testAgent },
})

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.

tip

Use Studio to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.

note

Visit the agent reference for more information on available properties and configurations.

Use your agent

After registration, retrieve your agent with mastra.getAgentById(). Call .generate() for a complete response or .stream() to deliver tokens in real time. You can call agents from workflow steps, tools, the Mastra Client, route handlers, server adapters, or the command line. Visit the guides section to learn how to use agents in your framework of choice.

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

Returns the full response after all tool calls and steps complete. The result includes text, toolCalls, toolResults, steps, and token usage statistics.

const agent = mastra.getAgentById('test-agent')
const response = await agent.generate('Help me organize my day')
console.log(response.text)

Stream

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.

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)
}

Expand your agent

Once your agent is running, use this table to find the right page for what you want to do next:

Goal	Start here
Give your agent tools to call external APIs or services	Tools
Keep context and preferences across conversations	Memory
Get typed objects back instead of plain text	Structured output
Human-in-the-loop: Pause execution and wait for human approval	Approval
Build a multi-agent network	Supervisor agents
Register subagents	Tools
Intercept or transform messages before and after generation	Processors
Keep your agent safe	Guardrails
Swap instructions or models based on request context	Dynamic configuration
Add speech-to-text or text-to-speech	Voice

Multi-agent systems

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.

Read the conceptual overview of multi-agent systems to learn how you can apply different patterns with Mastra.