尧图网页设计 
Mastra 官方示例库运行指南从 examples 目录到可运行的 AI 应用【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读Mastra 是面向 AI 应用与 Agent 的现代 TypeScript 框架其 examples 目录汇集了覆盖 Agent、工作流、语音、可观测性、存储、沙箱部署等场景的可运行示例。本文以 examples/README.md 为骨架系统讲解如何正确进入示例目录、安装依赖、启动开发服务器并结合仓库中每个示例的 README、package.json与源码逐类说明每个示例演示的核心能力与运行细节。读完本文你将掌握 Mastra 示例库的完整运行方法论以及各示例背后的技术要点。一、examples 目录概览一个主题一个示例Mastra 仓库采用 pnpm workspace 管理examples/目录位于仓库根目录下与packages/、stores/、integrations/等源码目录平级。每个示例都是独立的包自带package.json、pnpm-workspace.yaml并有自己的 README 说明用途与运行方式示例目录演示主题关联文档examples/agent多类型 Agent、计算机使用 Agent、Request Context Presets、动态工作流READMEexamples/agent-builderAgent Builder 可视化编排package.jsonexamples/durable-agents基于 Redis 的可恢复流与持久化执行READMEexamples/evals-with-memory带记忆 Agent 的三种评估方式READMEexamples/inngestInngest 工作流编排 可观测性READMEexamples/oracledbOracle 数据库存储与向量搜索READMEexamples/sandbox-deployer沙箱 microVM 部署READMEexamples/voice-agentLiveKit 语音客服 AgentREADME注意环境信息中展示的examples/ai-sdk-v5并不存在于当前仓库README 仅将其作为命令示例占位符请以仓库中实际存在的目录为准。二、三步启动进入目录、安装依赖、运行命令examples/README.md 给出了最通用的运行流程共三步。1. 进入目标示例目录cd examples/agent2. 安装依赖npm installREADME 特别强调了几条依赖安装规则示例拥有独立的package.json不属于 Mastra 主 workspace因此大多数示例可以直接使用npm install如果某个示例通过link:关联了本地 workspace 包则必须在该示例目录下改用pnpm install --ignore-workspace--ignore-workspace的含义是忽略 pnpm 全局 workspace 配置把该示例当作独立工程安装。以 examples/agent/package.json 为例它的pnpm.overrides字段把mastra/core、mastra/memory、mastra/evals、mastra等一大批包以link:../../packages/...的形式指向仓库内的本地源码这正是关联本地 workspace 包的典型形态此时必须使用pnpm install --ignore-workspace才能让链接解析到本地构建产物。3. 运行对应的 CLI 命令npm run dev不同示例的启动命令可能不同dev、start、build、worker等请以各示例 README 为准。三、让示例真正跑起来环境变量与 MASTRA 开发命令仅仅npm run dev往往不够多数示例还需要先准备密钥与构建本地包。准备环境变量需要调用模型或第三方服务的示例都要求先复制.env.example并填入密钥例如 examples/agent/README.mdcp .env.example .env # Edit .env with your API keysexamples/oracledb/README.md同样要求填入OPENAI_API_KEY以及如需修改默认值ORACLE_DATABASE_*系列变量其默认值与docker-compose.yaml中的localhost:1521/FREEPDB1保持一致。关联本地 workspace 包的示例先构建、再运行当示例通过link:关联 monorepo 包时link:目标必须是真实存在的构建产物。examples/oracledb/README.md明确给出构建命令在仓库根目录执行pnpm turbo build --filtermastra/oracledb --filtermastra/loggers --filtermastra/memory --filtermastra它还特别警告不要对这类示例传--ignore-workspace与通用规则相反因为mastra/oracledb属于尚未发布到 npm 的预发布包其编译后的类型引用的是 monorepo 构建中的MastraCompositeStore/MastraVector类若从 registry 拉取发布版mastra/core会导致类型不匹配。判断依据是安装输出中是否出现- ../../packages/core样式的本地链接。用pnpm mastra dev而非mastra devexamples/AGENTS.md 提醒本地运行示例时应使用pnpm mastra dev或pnpm mastra:dev而不是全局安装的mastra dev这样才能确保使用被link:的 workspace 版本而非全局 CLI。这也是为什么 examples/agent/package.json 的 scripts 中同时存在mastra:dev、mastra:studio、mastra:build、mastra:start等脚本。四、示例运行方式的分流三种典型安装形态综合各示例 README可以把 examples 下的安装方式归纳为三种形态形态适用示例安装命令说明通用形态大多数示例npm install或pnpm install独立package.json不依赖本地构建workspace 关联形态examples/agent等pnpm install --ignore-workspacelink:指向仓库本地包自带 workspace 根examples/oracledb、examples/voice-agent等普通pnpm install禁加--ignore-workspace示例自带pnpm-workspace.yaml仅列出.依赖本地 override 链接examples/voice-agent/README.md 与 oracledb 同样强调Do not pass--ignore-workspace否则会丢弃本地pnpm-workspace.yaml的overrides装回发布版包后类型校验失败若发生这种情况删除node_modules与pnpm-lock.yaml后重新pnpm install即可。五、逐示例速览每个示例演示什么、怎么跑1.examples/agent最全能的 Agent 示例集这是覆盖面最广的示例包含十几个 Agent 与工作流演示见 src/mastra/agents其 package.json 通过link:关联了 auth、daytona、e2b、voice、memory、evals、observability 等大量仓库包。可用脚本包括pnpm start— 运行 Agent 示例pnpm mastra:dev— 启动 Mastra 开发服务器pnpm mastra:studio— 打开 Mastra Studio UIpnpm mastra:build/pnpm mastra:start— 生产构建与启动其 README 中还包含两个特色功能Computer-use Agent通过 workspace 截图、鼠标、键盘和 shell 工具控制远程 Linux 桌面默认使用 Daytona需DAYTONA_API_KEY也可设置COMPUTER_USE_PROVIDERe2b-desktop与E2B_API_KEY切换为 E2B Desktop。注意它会产生云沙箱费用使用完应停止或销毁沙箱且不要分享已认证的桌面流 URL。Request Context Presets通过--request-context-presets ./request-context-presets.json在mastra dev或mastra studio时加载预置的 JSON 配置然后在 Studio Playground 的 Request Context 下拉框中一键切换环境development/production/staging或角色admin-user/guest-user预设文件必须是对象形式见 request-context-presets.json。2.examples/durable-agentsRedis 可恢复流与三种持久化模式该示例演示三种可恢复执行模式READMEAgentFactory可恢复流持久化执行durableResearchAgentcreateDurableAgentRedis—eventedResearchAgentcreateEventedAgentRedisWorkflow 引擎inngestResearchAgentcreateInngestAgentRedisInngest运行前先启动 Redisdocker run -d -p 6379:6379 redis再pnpm install、pnpm devInngest 模式还需npx inngest-clilatest dev。核心机制是通过RedisServerCache缓存事件并附顺序索引pubsub使用EventEmitterPubSub当连接断开后客户端可携带runId调用observe接口重放缺失事件再续接实时事件curl -X POST http://localhost:4111/api/agents/durable-research-agent/observe \ -H Content-Type: application/json \ -d {runId: your-run-id, offset: 5}3.examples/evals-with-memory带记忆 Agent 的三种评估姿势该示例提供三种在开启记忆含 thread 作用域的可观测记忆的 Agent 上运行 Mastra evals 的具体做法README全局targetOptions.memoryrunEvals({ target: agent, scorers, targetOptions: { memory: { thread, resource } }, data })所有数据项共享同一 thread逐项调用runEvals由于runEvals目前不支持 per-item 的 agent 选项需要在循环中为每项传入独立thread再自行聚合评分dataset.startExperiment 内联taskexperiment 运行器不会向agent.generate()传递 memory因此把{ threadId, resourceId }放进数据项的metadata在task函数内手动调用agent.generate(input, { memory: { thread, resource } })。所有脚本使用确定性 mock 模型无需 API Key 即可在 CI 中复现。运行方式pnpm install --ignore-workspace pnpm ex:all4.examples/inngestInngest 工作流编排 可观测性该示例演示用mastra/inngest构建三步活动规划工作流获取天气 → 按降水概率分支 → 室内/混合活动建议并开启可观测性采集workflow_run、workflow_step、agent_run、model_generation等 spanREADME。依赖与本地 Inngest Dev Servernpm install mastra/inngest inngest mastra/core mastra/deployer hono/node-server docker run --rm -p 8288:8288 \ inngest/inngest:v1.18.0 \ inngest dev -u http://host.docker.internal:3000/inngest/api需要inngest^4与 Dev Serverv1.18.0。工作流通过createWorkflow(...).then(fetchWeather).branch([...])组装并以mastra.getWorkflow(...)获取后createRun()run.start({ inputData: { city: New York } })执行。README 还完整给出了 Inngest 流控配置示例concurrency、rateLimit、throttle、debounce、priority以及组合用法所有流控项均为可选。可观测性默认使用ConsoleExporterMastraStorageExporter采样{ type: always }生产环境可替换为LangfuseExporter、DatadogExporter或OtelExporter。此外还演示了createInngestAgent包装 Agent 以获得跨崩溃检查点的持久化执行。5.examples/oracledbOracle 存储 向量搜索简化版天气 Agent用mastra/oracledb做线程/消息/追踪存储与向量搜索README。运行链路为docker compose up -d --wait启动gvenzl/oracle-free:23-slim-faststart→cp .env.example .env→ 在仓库根执行pnpm turbo build --filtermastra/oracledb ...→pnpm install→pnpm dev。Studio 默认在http://localhost:4111对话后可查看持久化的 ThreadsMASTRA_THREADS、MASTRA_MESSAGES表与 traces。OracleVector默认精确搜索无需向量索引若需 HNSW 实验可参考 stores/oracledb/README.md 的VECTOR_MEMORY_SIZE说明。6.examples/sandbox-deployer一行构建部署到沙箱 microVM用mastra/deployer-sandbox把一个最小 Mastra 服务器一个 Agent、一个工具、Studio部署进沙箱 microVM 并输出公开 URLREADME。支持 Vercel Sandbox默认、E2B、Daytona 三种 provider用SANDBOX_PROVIDER环境变量选择。安装与认证corepack pnpm10.29.3 --dir examples/sandbox-deployer install --ignore-workspace cd examples/sandbox-deployer vercel link # 关联/创建 Vercel 项目 vercel env pull # 写入 VERCEL_OIDC_TOKEN 到 .env.local或复制.env.example手动设置VERCEL_TOKEN/VERCEL_TEAM_ID/VERCEL_PROJECT_ID。随后执行pnpm build即完成构建 部署一步到位并写出.mastra/output/sandbox-deployment.json。生命周期管理通过getDeployment()的stop()/destroy()/logs()实现对应pnpm stop/pnpm destroy脚本见 scripts/stop.ts 与 scripts/destroy.ts。7.examples/voice-agentLiveKit 驱动的电话客服 Agent完整的呼叫中心语音 Agent 示例虚构公司 Meridian Trades由mastra/livekit负责音频回路WebRTC、STT、语义换气检测、barge-in、TTSMastra 生成每轮回复README。提供四个可互换的入口pnpm worker— Agent 循环应答每轮对话pnpm worker:workflow— Workflow 每轮完整执行一次先classifyIntent分类意图再generateResponse生成回复pnpm worker:plugin— 客户自持voice.AgentSessionMastraLLM插件经 HTTP/SSE 访问 Mastra 服务器pnpm worker:regulated— 开启全部合规控制的超监管 Agent运行需 LiveKit Cloud 凭据与OPENAI_API_KEY首次使用先执行pnpm worker:download-files下载换气检测与 VAD 模型。全部进程共享同一个voice-agent.dbLibSQL支持在 Studio 中以:4111地址打开语音通话并体验语义换气、barge-in、跨电话记忆识别等能力。README 还给出了大量排查建议例如模型缓存与依赖树绑定、pnpm clean与运行中进程冲突导致Thread not found等。六、排错速查examples 常见问题对照症状原因与处理安装后类型不匹配误用了--ignore-workspace对自带 workspace 根的示例或未先turbo build本地包删除node_modules、pnpm-lock.yaml重装确认输出含- ../../packages/core示例启动后报缺密钥未复制.env.example为.env或未填模型/服务密钥本地mastra dev与全局 CLI 行为不一致改用pnpm mastra dev/pnpm mastra:dev以使用 workspace 链接版本见 examples/AGENTS.md语音示例Thread not found数据库文件在进程运行期间被pnpm clean删除导致进程间数据库分叉先停止所有进程再清理、再同时启动语音示例模型文件缺失依赖重装使换气检测模型缓存失效重跑pnpm worker:download-files七、把示例跑通的通用检查清单阅读目标示例的 README每个示例都自带如 examples/agent/README.md、examples/durable-agents/README.md确认它的安装形态属于哪种复制.env.example为.env并填好 API Key若 README 要求本地link:先在仓库根用pnpm turbo build --filter包名构建对应包按形态选择npm install、pnpm install --ignore-workspace或普通pnpm install用pnpm mastra dev或 README 指定的pnpm start/pnpm dev/pnpm worker等启动有外部依赖的示例Redis、Oracle、Inngest、LiveKit、沙箱 provider先启动对应服务详见各示例 README 的 Prerequisites 小节。掌握这套方法论后examples 下从基础 Agent 到语音呼叫中心、从 Oracle 存储到沙箱部署的每个示例都可以在数分钟内启动并复现其演示效果各示例目录内的 README 与源码如 examples/agent/src/mastra、examples/voice-agent/src/mastra也是深入学习 Mastra 框架各模块的最佳范本。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 官方示例库运行指南：从 examples 目录到可运行的 AI 应用
Mastra 官方示例库运行指南从 examples 目录到可运行的 AI 应用【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读Mastra 是面向 AI 应用与 Agent 的现代 TypeScript 框架其 examples 目录汇集了覆盖 Agent、工作流、语音、可观测性、存储、沙箱部署等场景的可运行示例。本文以 examples/README.md 为骨架系统讲解如何正确进入示例目录、安装依赖、启动开发服务器并结合仓库中每个示例的 README、package.json与源码逐类说明每个示例演示的核心能力与运行细节。读完本文你将掌握 Mastra 示例库的完整运行方法论以及各示例背后的技术要点。一、examples 目录概览一个主题一个示例Mastra 仓库采用 pnpm workspace 管理examples/目录位于仓库根目录下与packages/、stores/、integrations/等源码目录平级。每个示例都是独立的包自带package.json、pnpm-workspace.yaml并有自己的 README 说明用途与运行方式示例目录演示主题关联文档examples/agent多类型 Agent、计算机使用 Agent、Request Context Presets、动态工作流READMEexamples/agent-builderAgent Builder 可视化编排package.jsonexamples/durable-agents基于 Redis 的可恢复流与持久化执行READMEexamples/evals-with-memory带记忆 Agent 的三种评估方式READMEexamples/inngestInngest 工作流编排 可观测性READMEexamples/oracledbOracle 数据库存储与向量搜索READMEexamples/sandbox-deployer沙箱 microVM 部署READMEexamples/voice-agentLiveKit 语音客服 AgentREADME注意环境信息中展示的examples/ai-sdk-v5并不存在于当前仓库README 仅将其作为命令示例占位符请以仓库中实际存在的目录为准。二、三步启动进入目录、安装依赖、运行命令examples/README.md 给出了最通用的运行流程共三步。1. 进入目标示例目录cd examples/agent2. 安装依赖npm installREADME 特别强调了几条依赖安装规则示例拥有独立的package.json不属于 Mastra 主 workspace因此大多数示例可以直接使用npm install如果某个示例通过link:关联了本地 workspace 包则必须在该示例目录下改用pnpm install --ignore-workspace--ignore-workspace的含义是忽略 pnpm 全局 workspace 配置把该示例当作独立工程安装。以 examples/agent/package.json 为例它的pnpm.overrides字段把mastra/core、mastra/memory、mastra/evals、mastra等一大批包以link:../../packages/...的形式指向仓库内的本地源码这正是关联本地 workspace 包的典型形态此时必须使用pnpm install --ignore-workspace才能让链接解析到本地构建产物。3. 运行对应的 CLI 命令npm run dev不同示例的启动命令可能不同dev、start、build、worker等请以各示例 README 为准。三、让示例真正跑起来环境变量与 MASTRA 开发命令仅仅npm run dev往往不够多数示例还需要先准备密钥与构建本地包。准备环境变量需要调用模型或第三方服务的示例都要求先复制.env.example并填入密钥例如 examples/agent/README.mdcp .env.example .env # Edit .env with your API keysexamples/oracledb/README.md同样要求填入OPENAI_API_KEY以及如需修改默认值ORACLE_DATABASE_*系列变量其默认值与docker-compose.yaml中的localhost:1521/FREEPDB1保持一致。关联本地 workspace 包的示例先构建、再运行当示例通过link:关联 monorepo 包时link:目标必须是真实存在的构建产物。examples/oracledb/README.md明确给出构建命令在仓库根目录执行pnpm turbo build --filtermastra/oracledb --filtermastra/loggers --filtermastra/memory --filtermastra它还特别警告不要对这类示例传--ignore-workspace与通用规则相反因为mastra/oracledb属于尚未发布到 npm 的预发布包其编译后的类型引用的是 monorepo 构建中的MastraCompositeStore/MastraVector类若从 registry 拉取发布版mastra/core会导致类型不匹配。判断依据是安装输出中是否出现- ../../packages/core样式的本地链接。用pnpm mastra dev而非mastra devexamples/AGENTS.md 提醒本地运行示例时应使用pnpm mastra dev或pnpm mastra:dev而不是全局安装的mastra dev这样才能确保使用被link:的 workspace 版本而非全局 CLI。这也是为什么 examples/agent/package.json 的 scripts 中同时存在mastra:dev、mastra:studio、mastra:build、mastra:start等脚本。四、示例运行方式的分流三种典型安装形态综合各示例 README可以把 examples 下的安装方式归纳为三种形态形态适用示例安装命令说明通用形态大多数示例npm install或pnpm install独立package.json不依赖本地构建workspace 关联形态examples/agent等pnpm install --ignore-workspacelink:指向仓库本地包自带 workspace 根examples/oracledb、examples/voice-agent等普通pnpm install禁加--ignore-workspace示例自带pnpm-workspace.yaml仅列出.依赖本地 override 链接examples/voice-agent/README.md 与 oracledb 同样强调Do not pass--ignore-workspace否则会丢弃本地pnpm-workspace.yaml的overrides装回发布版包后类型校验失败若发生这种情况删除node_modules与pnpm-lock.yaml后重新pnpm install即可。五、逐示例速览每个示例演示什么、怎么跑1.examples/agent最全能的 Agent 示例集这是覆盖面最广的示例包含十几个 Agent 与工作流演示见 src/mastra/agents其 package.json 通过link:关联了 auth、daytona、e2b、voice、memory、evals、observability 等大量仓库包。可用脚本包括pnpm start— 运行 Agent 示例pnpm mastra:dev— 启动 Mastra 开发服务器pnpm mastra:studio— 打开 Mastra Studio UIpnpm mastra:build/pnpm mastra:start— 生产构建与启动其 README 中还包含两个特色功能Computer-use Agent通过 workspace 截图、鼠标、键盘和 shell 工具控制远程 Linux 桌面默认使用 Daytona需DAYTONA_API_KEY也可设置COMPUTER_USE_PROVIDERe2b-desktop与E2B_API_KEY切换为 E2B Desktop。注意它会产生云沙箱费用使用完应停止或销毁沙箱且不要分享已认证的桌面流 URL。Request Context Presets通过--request-context-presets ./request-context-presets.json在mastra dev或mastra studio时加载预置的 JSON 配置然后在 Studio Playground 的 Request Context 下拉框中一键切换环境development/production/staging或角色admin-user/guest-user预设文件必须是对象形式见 request-context-presets.json。2.examples/durable-agentsRedis 可恢复流与三种持久化模式该示例演示三种可恢复执行模式READMEAgentFactory可恢复流持久化执行durableResearchAgentcreateDurableAgentRedis—eventedResearchAgentcreateEventedAgentRedisWorkflow 引擎inngestResearchAgentcreateInngestAgentRedisInngest运行前先启动 Redisdocker run -d -p 6379:6379 redis再pnpm install、pnpm devInngest 模式还需npx inngest-clilatest dev。核心机制是通过RedisServerCache缓存事件并附顺序索引pubsub使用EventEmitterPubSub当连接断开后客户端可携带runId调用observe接口重放缺失事件再续接实时事件curl -X POST http://localhost:4111/api/agents/durable-research-agent/observe \ -H Content-Type: application/json \ -d {runId: your-run-id, offset: 5}3.examples/evals-with-memory带记忆 Agent 的三种评估姿势该示例提供三种在开启记忆含 thread 作用域的可观测记忆的 Agent 上运行 Mastra evals 的具体做法README全局targetOptions.memoryrunEvals({ target: agent, scorers, targetOptions: { memory: { thread, resource } }, data })所有数据项共享同一 thread逐项调用runEvals由于runEvals目前不支持 per-item 的 agent 选项需要在循环中为每项传入独立thread再自行聚合评分dataset.startExperiment 内联taskexperiment 运行器不会向agent.generate()传递 memory因此把{ threadId, resourceId }放进数据项的metadata在task函数内手动调用agent.generate(input, { memory: { thread, resource } })。所有脚本使用确定性 mock 模型无需 API Key 即可在 CI 中复现。运行方式pnpm install --ignore-workspace pnpm ex:all4.examples/inngestInngest 工作流编排 可观测性该示例演示用mastra/inngest构建三步活动规划工作流获取天气 → 按降水概率分支 → 室内/混合活动建议并开启可观测性采集workflow_run、workflow_step、agent_run、model_generation等 spanREADME。依赖与本地 Inngest Dev Servernpm install mastra/inngest inngest mastra/core mastra/deployer hono/node-server docker run --rm -p 8288:8288 \ inngest/inngest:v1.18.0 \ inngest dev -u http://host.docker.internal:3000/inngest/api需要inngest^4与 Dev Serverv1.18.0。工作流通过createWorkflow(...).then(fetchWeather).branch([...])组装并以mastra.getWorkflow(...)获取后createRun()run.start({ inputData: { city: New York } })执行。README 还完整给出了 Inngest 流控配置示例concurrency、rateLimit、throttle、debounce、priority以及组合用法所有流控项均为可选。可观测性默认使用ConsoleExporterMastraStorageExporter采样{ type: always }生产环境可替换为LangfuseExporter、DatadogExporter或OtelExporter。此外还演示了createInngestAgent包装 Agent 以获得跨崩溃检查点的持久化执行。5.examples/oracledbOracle 存储 向量搜索简化版天气 Agent用mastra/oracledb做线程/消息/追踪存储与向量搜索README。运行链路为docker compose up -d --wait启动gvenzl/oracle-free:23-slim-faststart→cp .env.example .env→ 在仓库根执行pnpm turbo build --filtermastra/oracledb ...→pnpm install→pnpm dev。Studio 默认在http://localhost:4111对话后可查看持久化的 ThreadsMASTRA_THREADS、MASTRA_MESSAGES表与 traces。OracleVector默认精确搜索无需向量索引若需 HNSW 实验可参考 stores/oracledb/README.md 的VECTOR_MEMORY_SIZE说明。6.examples/sandbox-deployer一行构建部署到沙箱 microVM用mastra/deployer-sandbox把一个最小 Mastra 服务器一个 Agent、一个工具、Studio部署进沙箱 microVM 并输出公开 URLREADME。支持 Vercel Sandbox默认、E2B、Daytona 三种 provider用SANDBOX_PROVIDER环境变量选择。安装与认证corepack pnpm10.29.3 --dir examples/sandbox-deployer install --ignore-workspace cd examples/sandbox-deployer vercel link # 关联/创建 Vercel 项目 vercel env pull # 写入 VERCEL_OIDC_TOKEN 到 .env.local或复制.env.example手动设置VERCEL_TOKEN/VERCEL_TEAM_ID/VERCEL_PROJECT_ID。随后执行pnpm build即完成构建 部署一步到位并写出.mastra/output/sandbox-deployment.json。生命周期管理通过getDeployment()的stop()/destroy()/logs()实现对应pnpm stop/pnpm destroy脚本见 scripts/stop.ts 与 scripts/destroy.ts。7.examples/voice-agentLiveKit 驱动的电话客服 Agent完整的呼叫中心语音 Agent 示例虚构公司 Meridian Trades由mastra/livekit负责音频回路WebRTC、STT、语义换气检测、barge-in、TTSMastra 生成每轮回复README。提供四个可互换的入口pnpm worker— Agent 循环应答每轮对话pnpm worker:workflow— Workflow 每轮完整执行一次先classifyIntent分类意图再generateResponse生成回复pnpm worker:plugin— 客户自持voice.AgentSessionMastraLLM插件经 HTTP/SSE 访问 Mastra 服务器pnpm worker:regulated— 开启全部合规控制的超监管 Agent运行需 LiveKit Cloud 凭据与OPENAI_API_KEY首次使用先执行pnpm worker:download-files下载换气检测与 VAD 模型。全部进程共享同一个voice-agent.dbLibSQL支持在 Studio 中以:4111地址打开语音通话并体验语义换气、barge-in、跨电话记忆识别等能力。README 还给出了大量排查建议例如模型缓存与依赖树绑定、pnpm clean与运行中进程冲突导致Thread not found等。六、排错速查examples 常见问题对照症状原因与处理安装后类型不匹配误用了--ignore-workspace对自带 workspace 根的示例或未先turbo build本地包删除node_modules、pnpm-lock.yaml重装确认输出含- ../../packages/core示例启动后报缺密钥未复制.env.example为.env或未填模型/服务密钥本地mastra dev与全局 CLI 行为不一致改用pnpm mastra dev/pnpm mastra:dev以使用 workspace 链接版本见 examples/AGENTS.md语音示例Thread not found数据库文件在进程运行期间被pnpm clean删除导致进程间数据库分叉先停止所有进程再清理、再同时启动语音示例模型文件缺失依赖重装使换气检测模型缓存失效重跑pnpm worker:download-files七、把示例跑通的通用检查清单阅读目标示例的 README每个示例都自带如 examples/agent/README.md、examples/durable-agents/README.md确认它的安装形态属于哪种复制.env.example为.env并填好 API Key若 README 要求本地link:先在仓库根用pnpm turbo build --filter包名构建对应包按形态选择npm install、pnpm install --ignore-workspace或普通pnpm install用pnpm mastra dev或 README 指定的pnpm start/pnpm dev/pnpm worker等启动有外部依赖的示例Redis、Oracle、Inngest、LiveKit、沙箱 provider先启动对应服务详见各示例 README 的 Prerequisites 小节。掌握这套方法论后examples 下从基础 Agent 到语音呼叫中心、从 Oracle 存储到沙箱部署的每个示例都可以在数分钟内启动并复现其演示效果各示例目录内的 README 与源码如 examples/agent/src/mastra、examples/voice-agent/src/mastra也是深入学习 Mastra 框架各模块的最佳范本。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考