企业官网建设流程全解析

在 Mastra 中注册记忆 Agent：更新src/mastra/index.ts的 mastra 导出

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本篇技术指南聚焦 Mastra 框架应用组装中的关键一步——将带有 Memory 能力的 Agent 注册进mastra实例导出。文章以官方课程"Agent Memory"第五步（05-updating-mastra-export.md）为核心，结合@mastra/core的源码实现，讲解src/mastra/index.ts的配置写法、Mastra 构造器的 Agent 注册机制，以及如何在 Playground 中验证注册结果。读完你将掌握 Mastra 应用入口文件的规范写法，并能独立排查"Agent 没有出现在 Playground 里"这类问题。

为什么需要更新 mastra 导出

在上一课（04-creating-basic-memory-agent.md）中，我们在src/mastra/agents/index.ts里创建了一个带记忆能力的memoryAgent——它通过Memory实例（默认配置即可记忆对话历史）与memory属性将记忆能力挂载到 Agent 上：

import { Agent } from '@mastra/core/agent' import { Memory } from '@mastra/memory' import { LibSQLStore } from '@mastra/libsql' const memory = new Memory({ storage: new LibSQLStore({ id: 'learning-memory-storage', url: 'file:../../memory.db', }), }) export const memoryAgent = new Agent({ name: 'MemoryAgent', instructions: `...`, model: 'openai/gpt-5.4', memory: memory, })

但仅仅创建 Agent 还不够。Mastra 应用需要一个"总装配点"——src/mastra/index.ts中的mastra导出。它是整个 Mastra 应用的主入口，只有被注册到这里的 Agent 才会被 Mastra 系统认识，才能在 Playground 等界面中使用。

更新src/mastra/index.ts注册记忆 Agent

编辑应用的入口文件src/mastra/index.ts，将memoryAgent加入Mastra实例的agents对象：

import { Mastra } from '@mastra/core' import { memoryAgent } from './agents' export const mastra: Mastra = new Mastra({ agents: { memoryAgent, }, })

这段代码做了三件事：

1. 从@mastra/core导入Mastra类——它是 Mastra 应用的中央编排器；
2. 从./agents导入上一步创建的memoryAgent；
3. 在agents对象中以memoryAgent为键注册该 Agent，并将其作为默认导出mastra暴露给应用。

这一步对于让 Agent 出现在 Mastra Playground 中至关重要。mastra导出是 Mastra 应用的主入口，需要包含所有你想使用的 Agent。通过把memoryAgent加入agents对象，你就把它注册进了 Mastra 系统，使它可以在 Playground 和应用的其余部分中使用。

源码视角：Mastra 构造器如何注册 Agent

从源码看，Mastra类的职责定义非常明确——它是 "The central orchestrator for Mastra applications, managing agents, workflows, storage, logging, observability, and more"（见 packages/core/src/mastra/index.ts）。它的构造器接收一个Config，其中agents是可选配置项：

agents?: { [K in keyof TAgents]: TAgents[K] | ToolLoopAgentLike | DurableAgentLike };

当构造器执行到config?.agents时，会遍历agents对象中的每一个键值对，并调用内部的addAgent方法完成注册（见 packages/core/src/mastra/index.ts#L1816-L1822）：

if (config?.agents) { Object.entries(config.agents).forEach(([key, agent]) => { if (agent != null) { this.addAgent(agent, key); } }); }

因此，agents对象中的属性名（key）就是该 Agent 在 Mastra 系统中的注册名，而addAgent是支持按任意键名注册的统一入口（packages/core/src/mastra/index.ts#L2570）。注册完成后，可以通过以下方式取回 Agent：

• mastra.getAgent('memoryAgent')——按注册名精确获取（packages/core/src/mastra/index.ts#L2255）；
• mastra.getAgents()——获取全部已注册 Agent 的字典（packages/core/src/mastra/index.ts#L2451）。

这也解释了为什么 key 的命名很重要：它既是 Playground 里展示的 Agent 标识，也是运行时getAgent的查询键。使用memoryAgent作为键，与导出变量同名，是最直白、最不易出错的约定。

在 Playground 中验证注册结果

注册完成后，按照下一课（06-testing-memory-agent.md）的流程验证：

1. 确保开发服务器已启动：运行npm run dev；
2. 打开 Playground：http://localhost:4111/；
3. 从 Agent 列表中选择MemoryAgent；
4. 尝试一轮测试记忆能力的对话：
   • "My name is Alex"
   • "What's my name?"
   • "I live in Seattle"
   • "Where do I live?"
   • "I prefer dark mode in my apps"
   • "What are my UI preferences?"

如果 Agent 能在这些交互中记住信息，说明注册成功，且 Playground 已自动为记忆功能处理了所需的 resource 与 thread ID。反之，如果列表中看不到 MemoryAgent，请优先检查src/mastra/index.ts是否已正确导出mastra实例、memoryAgent是否已放入agents对象。

常见问题与最佳实践

• 忘记注册：创建了 Agent 却忘了更新src/mastra/index.ts，Playground 中不会出现该 Agent。注册动作是"进入应用"的必要条件，而不是可选项。
• 注册名不一致：agents对象的 key 是运行时的查找键，getAgent时传入的必须是同一个名字。建议保持 key 与变量名一致（如memoryAgent）。
• 多 Agent 场景：后续课程中（如 26-updating-mastra-export-comprehensive.md）会展示更完整的导出，但核心机制相同——把所有要使用的 Agent 都放进agents对象即可。源码中Object.entries的遍历方式保证了多个 Agent 会按顺序逐个注册，互不影响。

小结

src/mastra/index.ts的mastra导出是 Mastra 应用的主入口，把带记忆的memoryAgent加入agents对象即完成注册。从源码看，这一步本质上是触发Mastra构造器对agents配置的遍历与addAgent注册，注册后即可通过getAgent在运行时取用，并立即可在 Playground（http://localhost:4111/）中体验对话记忆能力。它是衔接"创建 Agent"与"测试 Agent"两步之间不可或缺的装配环节。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra