用 Mastra 与 Oracle Database 构建持久化天气 Agent完整示例实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南围绕仓库中的examples/oracledb示例展开讲解如何将一个精简版天气 Agent源自 templates/weather-agent 模板接入mastra/oracledb让会话线程、消息、工作流快照与追踪traces全部持久化到 Oracle Database并注册 Oracle 向量搜索能力。读完本文你将掌握从零启动本地 Oracle、链接 monorepo 内预发布包、运行 Mastra Studio 并验证数据落库的完整实操链路。示例概览天气 Agent 与 Oracle 存储的接线方式examples/oracledb是 Mastra 官方仓库中的一个自包含示例。它在功能上是 templates/weather-agent 模板的精简版区别在于数据层——所有持久化能力都交给了mastra/oracledb包括Storage线程threads、消息messages、工作流快照与追踪都通过OracleStore写入 OracleVector通过OracleVector注册向量相似度检索能力供任何 Agent 或 Tool 按需调用。从 examples/oracledb/src/mastra/index.ts 可以看到整个接线核心import { Mastra } from mastra/core/mastra; import { PinoLogger } from mastra/loggers; import { OraclePoolManager, OracleStore, OracleVector } from mastra/oracledb; import { weatherAgent } from ./agents/weather-agent; import { weatherWorkflow } from ./workflows/weather-workflow; // One Oracle connection pool shared by storage and vectors. See // stores/oracledb/README.md (Shared Pool) for the underlying API. const poolManager new OraclePoolManager({ user: process.env.ORACLE_DATABASE_USER, password: process.env.ORACLE_DATABASE_PASSWORD, connectString: process.env.ORACLE_DATABASE_CONNECT_STRING, }); export const mastra new Mastra({ agents: { weatherAgent }, workflows: { weatherWorkflow }, // Threads, messages, workflow snapshots, and traces persist in Oracle. storage: new OracleStore({ id: oracle-storage, poolManager }), // Registered so vector search is available to any agent/tool that needs it // (e.g. mastra.getVector(oracleVector)). See ../../README.md for the // exact search vs. IVF/HNSW indexing notes. vectors: { oracleVector: new OracleVector({ id: oracle-vector, poolManager }), }, logger: new PinoLogger({ name: Mastra, level: info, }), });注意OracleStore与OracleVector共享同一个OraclePoolManager实例这是为了让存储与向量检索复用同一 Oracle 连接池详见后文源码解析。示例目录结构examples/oracledb/ ├── .env.example # 环境变量模板 ├── docker-compose.yaml # 本地 Oracle 数据库编排 ├── package.json # 依赖与 pnpm overrides ├── pnpm-workspace.yaml # 自包含 workspace 包链接 ├── tsconfig.json └── src/mastra/ ├── index.ts # Mastra 实例storage/vectors 接线 ├── agents/weather-agent.ts # 天气 Agent含 Memory ├── tools/weather-tool.ts # 实时天气工具Open-Meteo └── workflows/weather-workflow.ts # 天气→活动建议工作流关于预发布包的重要说明mastra/oracledb目前是预发布状态尚未发布到 npm。因此 examples/oracledb/package.json 没有用mastra/oracledb: latest而是直接链接到 monorepo 内的包dependencies: { mastra/core: latest, mastra/loggers: latest, mastra/memory: latest, mastra/oracledb: link:../../stores/oracledb, zod: ^4.4.3 }同时mastra/core、mastra/loggers、mastra/memory、mastra也通过 examples/oracledb/pnpm-workspace.yaml 的overrides链接到 monorepo 构建产物以保证编译出的类型与mastra/oracledb构建所依赖的类型完全一致。等包正式发布后再把link:换回正常版本号即可。前置条件在开始之前你需要准备两样东西Docker—— 用于在本地运行 Oracle Database示例通过 Docker Compose 拉起gvenzl/oracle-free:23-slim-faststart镜像OpenAI API Key—— Agent 的模型weather-agent.ts 中使用的是openai/gpt-5.2。另外注意 package.json 声明的运行环境要求Node.js22.13.0包管理器为 pnpmpackageManager: pnpm11.8.0。一步步启动示例1. 启动 Oraclecd examples/oracledb docker compose up -d --wait这条命令使用与stores/oracledb自身 Docker Compose 文件相同的gvenzl/oracle-free:23-slim-faststart镜像。看 examples/oracledb/docker-compose.yaml 的具体配置services: db: image: gvenzl/oracle-free:23-slim-faststart container_name: oracledb-example-db ports: - ${ORACLE_DATABASE_PORT:-1521}:1521 environment: ORACLE_RANDOM_PASSWORD: true APP_USER: ${ORACLE_DATABASE_USER:?Set ORACLE_DATABASE_USER before starting Oracle} APP_USER_PASSWORD: ${ORACLE_DATABASE_PASSWORD:?Set ORACLE_DATABASE_PASSWORD before starting Oracle} volumes: - oracledbdata:/opt/oracle/oradata healthcheck: test: [CMD, healthcheck.sh] interval: 10s timeout: 5s retries: 30 start_period: 60s volumes: oracledbdata:几点值得说明ORACLE_RANDOM_PASSWORD: true表示系统管理员SYS密码由镜像随机生成我们只关心通过APP_USER/APP_USER_PASSWORD创建的mastra应用用户端口默认映射为宿主机的1521可通过ORACLE_DATABASE_PORT覆盖healthcheck.sh配合--wait会等待数据库真正就绪后再返回避免后续步骤在实例未初始化完成时执行数据卷oracledbdata挂载到/opt/oracle/oradata保证重启容器后数据不丢。2. 配置环境变量cp .env.example .env编辑.env填写OPENAI_API_KEY如果修改过数据库账号信息则同步更新ORACLE_DATABASE_*三项。参考 examples/oracledb/.env.exampleOPENAI_API_KEYyour-api-key # Oracle Database connection (see ./docker-compose.yaml for a local instance) ORACLE_DATABASE_USERmastra ORACLE_DATABASE_PASSWORDyour-oracle-password ORACLE_DATABASE_CONNECT_STRINGlocalhost:1521/FREEPDB1其中ORACLE_DATABASE_CONNECT_STRING的默认值localhost:1521/FREEPDB1与docker-compose.yaml的端口映射和 Oracle Free 镜像的默认可插拔数据库PDB名称一致未改动端口时无需修改。3. 构建被链接的包在 monorepo 根目录执行构建示例链接到的所有包mastra/oracledb、mastra/core、mastra/loggers、mastra/memory、mastra让link:依赖能解析到真实的构建产物cd /path/to/mastra pnpm turbo build --filtermastra/oracledb --filtermastra/loggers --filtermastra/memory --filtermastra--filter让 turbo 只构建相关包及其依赖mastra/core会作为依赖被自动带上避免全量构建耗时。4. 安装依赖这个示例是一个自包含的 pnpm workspace——它有自己的 pnpm-workspace.yaml里面只列出.一个包packages: - . # pnpm 11 reads overrides from here, not package.json. They are duplicated in # package.json pnpm.overrides because the example validator # (.github/scripts/validate-examples.js) checks for them there. overrides: mastra/core: link:../../packages/core mastra/loggers: link:../../packages/loggers mastra/memory: link:../../packages/memory mastra/oracledb: link:../../stores/oracledb mastra: link:../../packages/cli # esbuild ships a prebuilt binary via its platform optionalDependency; the # postinstall script is unnecessary (matches the monorepo roots setting). allowBuilds: esbuild: false直接安装即可cd examples/oracledb pnpm install千万不要加--ignore-workspace。如果加了pnpm 会丢弃本地pnpm-workspace.yaml中的overrides改而从 registry 安装已发布的 Mastra 包——但mastra/oracledb编译出的类型引用的是 monorepo 构建里的MastraCompositeStore/MastraVector类与单独发布的mastra/core类型对不上最终会导致类型检查失败。如果不小心装坏了修复方法是删除node_modules和pnpm-lock.yaml重新执行pnpm install然后检查安装输出中是否出现- ../../packages/core形式的链接记录确认 overrides 已生效。5. 运行pnpm devStudio 会在http://localhost:4111打开。dev脚本对应 package.json 中的mastra dev此外还提供了mastra build/mastra start与tsc --noEmit类型检查脚本。运行后值得验证的三件事Agent 对话在 Studio 中与天气 Agent 对话询问某个城市的天气然后继续追问适合做的活动——这会触发weatherWorkflow它内部会再次调用 Agent。对话逻辑本身由 weather-agent.ts 与 weather-tool.ts 驱动工具通过 Open-Meteo 的地理编码 API 与天气预报 API 获取实时数据Agent 根据weather_code映射出可读天气描述后回复。Threads 持久化Agent 聊天页的侧边栏会展示会话线程。由于 Agent 的Memory没有显式指定存储见 weather-agent.ts 中memory: new Memory()的注释说明它会从 Mastra 实例的storage注入因此线程与消息都经由mastra/oracledb的OracleStore持久化。你可以直接查 Oracle 表验证——例如MASTRA_THREADS、MASTRA_MESSAGES——应该能看到与 Studio 侧边栏一致的行数据。可观测性 / TracesAgent 运行过程与工具调用的 spans 同样持久化在 Oracle 中可在 Studio 的 Observability 页面查看完整的调用链。向量存储与 HNSW 索引OracleVector被注册到 Mastra 实例上vectors: { oracleVector }因此任何 Agent 或 Tool 都可以通过mastra.getVector(oracleVector)使用相似度检索。不过这个精简示例并没有把语义召回semantic recall接入天气 Agent 的Memory。OracleVector默认使用精确搜索exact search它不需要任何向量索引可以直接在上述启动的数据库上工作。这一点很关键——它保证了示例开箱即用不依赖任何额外的数据库配置。如果你希望实验HNSW 索引请参考 stores/oracledb/README.md 中Vector memory (HNSW only)一节的说明它解释了VECTOR_MEMORY_SIZE的要求以及启用它所需的一次性容器重启示例自带的 examples/oracledb/docker-compose.yaml没有设置VECTOR_MEMORY_SIZE如需 HNSW请改用包自身的 stores/oracledb/docker-compose.yaml或应用其中的 scripts/configure-vector-memory.sql注意 stores/oracledb/docker-compose.yaml 中的说明VECTOR_MEMORY_SIZE通过 SPFILE 持久化但只有重启数据库后才生效——即docker compose up -d --wait docker compose restart db。不重启时 Vector Pool 保持为 0此时精确搜索默认和 IVF 索引仍可工作只有 HNSW 索引构建需要这一步。源码级解析连接池、存储与向量的底层协作共享连接池 OraclePoolManager示例的关键设计是让OracleStore与OracleVector共用一个连接池。其底层实现在 stores/oracledb/src/shared/connection.tsexport class OraclePoolManager { // Pool creation is lazy and memoized so OracleStore and OracleVector can share one manager safely. private poolPromise?: PromisePool; private readonly poolOptions?: PoolAttributes; private readonly ownsPool: boolean; constructor(private readonly config: OracleConnectionConfig) { validateOracleConnectionConfig(config); this.ownsPool !config.pool; if (!config.pool) { this.poolOptions buildPoolOptions(config); } } async getPool(): PromisePool { if (this.config.pool) return this.config.pool; if (!this.poolOptions) { throw new Error(Oracle pool options were not initialized); } if (!this.poolPromise) { // Reset the promise on failure so a transient listener/network issue does not poison the manager forever. this.poolPromise oracledb.createPool(this.poolOptions).catch(error { this.poolPromise undefined; throw error; }); } return this.poolPromise; } async withConnectionT(callback: (connection: Connection) PromiseT): PromiseT { const pool await this.getPool(); const connection await pool.getConnection(); try { // Transaction ownership stays with the caller; this helper only owns acquire/release. return await callback(connection); } finally { await connection.close(); } } async close(): Promisevoid { if (this.ownsPool this.poolPromise) { const poolPromise this.poolPromise; this.poolPromise undefined; const pool await poolPromise; await pool.close(0); } } }从源码结构可以提炼出几个实现要点懒加载与记忆化poolPromise保证OracleStore和OracleVector共享同一个 manager 时只创建一次池创建失败会重置poolPromise避免瞬时故障如监听器/网络问题永久毒化 manager连接生命周期withConnection只负责 acquire/release事务所有权仍归调用方配置校验validateOracleConnectionConfig要求必须提供connectString且非外部认证时必须提供user与password外部认证OS / Kerberos / wallet TLS场景下凭据可省略可注入连接池也支持直接传入一个已存在的Poolpool选项此时 manager 不拥有该池close()不会关闭它。Memory 的存储注入在 weather-agent.ts 中Memory没有显式绑定 storage/vector这正是 Mastra 的设计当 Agent 通过new Mastra({...})挂载时实例级storage会自动注入到 Agent 的 Memory 中。因此示例只需在index.ts配置一次OracleStore线程、消息甚至工作流快照的持久化便全部生效这也是“精简”二字的体现。工作流内部再调 Agentweather-workflow.ts 展示了一个两层调用模式weatherWorkflow先由fetchWeather步骤抓取预报同样走 Open-Meteo计算最高/最低温与最大降水概率再由planActivities步骤通过mastra?.getAgent(weatherAgent)拿到 Agent 实例并stream生成结构化活动建议。工作流同样被注册到 Mastra 实例workflows: { weatherWorkflow }其快照也会持久化到 Oracle。清理验证完毕后停止并移除容器与数据卷docker compose down -v-v会同时删除命名卷oracledbdata确保下次docker compose up时是从全新数据库开始。常见问题速查现象原因与对策安装后类型检查报MastraCompositeStore/MastraVector类型不匹配安装时误用了--ignore-workspace导致安装了 registry 版而非链接的 monorepo 构建。删除node_modules与pnpm-lock.yaml后重新pnpm install确认输出中出现- ../../packages/core链接端口被占用通过ORACLE_DATABASE_PORT环境变量修改宿主机端口映射并同步更新.env中的ORACLE_DATABASE_CONNECT_STRING构建 HNSW 索引失败VECTOR_MEMORY_SIZE未生效需使用 stores/oracledb/docker-compose.yaml 并在初始化完成后重启一次数据库容器docker compose up -d --wait超时Oracle Free 首次初始化较慢healthcheck 的start_period: 60sretries: 30是上限耐心等待或检查日志确认初始化进度至此你已经完整走通了本地 Oracle Mastra 天气 Agent的全链路从拉起数据库、配置环境、链接并构建预发布包、安装运行到验证线程/消息/追踪落库与向量检索注册。以这个示例为起点你可以进一步把OracleStore与OracleVector集成进自己的 Agent 应用为会话与工作流构建真正由 Oracle 支撑的持久化底座。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考