MastraMastra
  • 文档
  • 大模型
⌘ K
介绍
入门
开始
Studio
项目结构
MCP 文档服务
Agents
概述
使用工具
Memory
结构化输出
智能体网络
处理器
MCP
概述
Memory
存储
Server
请求上下文
最后更新时间:
帮助改进此文档
Made with ❤️ by 紫升
本页访问量 | 本站总访问量 | 本站总访人数

TABLE OF CONTENTS

智能体概述

智能体使用大语言模型和工具来解决开放式任务。它们推理目标,决定使用哪些工具,保留对话记忆,并进行内部迭代,直到模型发出最终答案或满足可选的停止条件。

什么是智能体

AI 智能体(AI Agent) 是一种能够感知环境、自主决策、执行任务并持续学习的智能软件系统。它不只是被动地响应指令,而是像一个“数字员工”一样,主动思考、规划、调用工具、与外界交互,最终完成复杂目标。

✅ 简单说:AI 智能体 = LLM(大脑) + 工具(手脚) + 记忆(经验) + 目标(驱动力)

随着 LLM、工具调用(Function Calling)、记忆机制的发展,AI 智能体正从概念走向现实,成为下一代人机交互的核心范式。

参考:构建高效 AI 智能体 - Anthropic

设置 Agents

安装

1、将 Mastra 核心包添加到你的项目中:

sh
npm install @mastra/core@beta

2、Mastra 的模型路由器会自动检测您选择的提供商的环境变量。对于硅基流动,设置 SILICONFLOW_API_KEY:

env
SILICONFLOW_API_KEY=<your-api-key>

3、通过使用 系统 instructions 和 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: "siliconflow-cn/Qwen/Qwen3-Coder-30B-A3B-Instruct",
});

指令格式

指令定义了智能体的行为、个性和能力。它们是系统级提示,可建立智能体的核心身份和专业知识。

可以以多种格式提供说明,以提高灵活性。下面的示例说明了支持的格式:

ts
// 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
// 这里和 LLM 的格式是一致的s
instructions: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "system", content: "You have expertise in TypeScript." },
];

特定模型提供商选项

每个模型提供商会提供一些不同的选项,包括提示缓存和配置推理。我们提供 providerOptions 属性来管理。你可以在指令级别设置每个系统指令/提示设置不同的缓存策略。

ts
// 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

访问 Agent reference 获取更多信息。

注册智能体

在 Mastra 实例中注册你的智能体,使其在你的整个应用程序中可用。注册后,它可以从工作流、工具或其他智能体重调用,并且可以访问共享资源,例如内存、日志记录和可观察性功能:

ts
import { Mastra } from "@mastra/core";
import { testAgent } from "./agents/test-agent";
export const mastra = new Mastra({
agents: { testAgent },
});

引用智能体

你可以从工作流步骤、工具、Mastra 客户端或命令行调用智能体。根据你的设置,调用 mastra 或 mastraClient 的 getAgent():

ts
const testAgent = mastra.getAgent("testAgent");

INFO

mastra.getAgent() 优于直接导入,引入它提供对 Mastra 实例配置(logger、telemetry、storage、注册智能体和向量存储)的访问。

生成响应

智能体可以通过两种方式返回结果:在返回之前生成完整的输出或实时流式传输 token。选择适合你的方法:生成简短的内部响应或调试,并流式传输以尽快交付页面给用户。

对于简单提示,传递单个字符串;在提供多个上下文时传递字符串数组;或者使用带有 role 和 content 的对象数组传递消息。role 定义每条消息的发言者。典型的角色是 user(人工输入)、assistant(智能体响应) 和 system(指令)。

Generate
Stream
ts
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);

访问 .generate() 或 .stream() 了解更多信息。

结构化输出

智能体使用 Zod 或者 JSON Schema 能够返回结构化,类型安全的数据。解析后的结构可以通过 response.object 获取。

INFO

访问 结构化输出 查看更多信息。

分析图片

智能体可以通过处理视觉内容和其中的任何文本来分析和描述图像。要启用图像分析,请在 content 数组中传递一个 type 是 "image" 并包含图像 url 的对象。你可以将图像内容与文本提示相结合来指导智能体的分析。

图片分析
Test Agent
ts
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);

输出结果:

txt
The image is a black-and-white photograph depicting a bear standing in water. The bear is shown in profile, facing to the right, with its head slightly raised and its gaze directed forward. Its fur appears thick and textured, with varying shades of gray that suggest a natural, rugged coat. The bear’s body is partially submerged, with water reaching up to its midsection, and ripples are visible around it, indicating gentle movement in the water. The background consists of a calm, rippling water surface that extends to the horizon, with no visible land or other objects. The lighting is soft and even, enhancing the textures of the bear’s fur and the water’s surface. The overall mood of the image is serene and naturalistic.

使用 maxSteps

maxSteps 参数控制智能体可以进行的连续 LLM 调用的最大数量。每个步骤包括生成响应、执行任何工具调用以及处理结果、限制步骤有助于防止无限循环、减少延迟并控制使用工具使用工具的智能体 Token 的使用情况。默认为 1,但可以增加:

ts
const response = await testAgent.generate("Help me organize my day", {
maxSteps: 10,
});
console.log(response.text);

使用 onStepFinish

你可以使用回调监听多步骤操作的进度。这对于调试或向用户提供进度更新很有用。onStepFinish 仅在流式传输或生成没有结构化输出的文本时可用。

ts
const response = await testAgent.generate("Help me organize my day", {
onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
console.log({ text, toolCalls, toolResults, finishReason, usage });
},
});

使用工具

智能体可以使用工具,从而实现与外部 API 和服务的结构化交互。工具允许智能体以可靠、可重复的方式访问数据并执行明确定义的操作。

ts
export const testAgent = new Agent({
id: "test-agent",
instructions: "You are a helpful assistant.",
name: "Test Agent",
tools: { testTool },
});

"""info
请访问 使用工具 了解更多信息。
"""

使用 RequestContext

RequestContext 用于访问特定请求的值。这使你可以根据请求的上下文有条件地调整行为:

ts
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";
},
});
ts
import { RequestContext } from "@mastra/core/request-context";
export type UserTier = {
"user-tier": "enterprise" | "pro";
};
const requestContext = new RequestContext<UserTier>();
requestContext.set("user-tier", "enterprise");
const agent = mastra.getAgent("weatherAgent");
await agent.generate("What's the weather in London?", {
requestContext,
});

INFO

有关详细信息,请参阅 请求上下文 RequestContext。

使用 Studio 进行测试

在 Studio 用不同的消息测试智能体、检查工具和响应以调试智能体的行为。