多功能 Mastra Agent

这是一个使用 Mastra 框架构建的多功能 AI Agent，具备以下基础功能：

• 天气查询：获取任意城市的当前天气信息
• 时间查询：返回当前时间和时区
• 计算器：执行基本算术运算（加、减、乘、除）
• 文件列表：列出指定目录的文件
• 笑话生成：随机讲述笑话

项目结构

src/mastra/
├── agents/
│   ├── multi-function-agent.ts    # 多功能 agent
│   └── index.ts                   # agent 导出
├── tools/
│   ├── weather-tool.ts            # 天气工具
│   ├── time-tool.ts               # 时间工具
│   ├── calculator-tool.ts         # 计算器工具
│   ├── filelist-tool.ts           # 文件列表工具
│   ├── joke-tool.ts               # 笑话工具
│   └── index.ts                   # 工具导出
├── workflows/                     # （可选）工作流目录
└── index.ts                       # Mastra 入口点

快速开始

1. 安装依赖

pnpm install

2. 配置 API 密钥

复制 .env.example 为 .env，并填入你的 OpenAI API 密钥：

cp .env.example .env

编辑 .env 文件：

OPENAI_API_KEY=sk-your-openai-api-key-here

3. 启动开发服务器

pnpm dev

服务器将在 http://localhost:4111 启动。

4. 使用 Agent

通过 Studio UI 交互

打开浏览器访问 http://localhost:4111，在 Studio 界面中与你的 agent 对话。

通过 HTTP API 调用

# 获取当前时间
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What time is it?"
      }
    ]
  }'

# 计算 15 + 27
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is 15 + 27?"
      }
    ]
  }'

# 查询东京天气
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What'\''s the weather in Tokyo?"
      }
    ]
  }'

通过 TypeScript 代码调用

import { mastra } from "./src/mastra/index.js";

async function callAgent() {
  const agent = mastra.getAgent("multiFunctionAgent");

  // 查询时间
  const timeResponse = await agent.generate("What time is it?");
  console.log(timeResponse.text);

  // 计算
  const calcResponse = await agent.generate("What is 15 + 27?");
  console.log(calcResponse.text);

  // 查询天气
  const weatherResponse = await agent.generate("What's the weather in Tokyo?");
  console.log(weatherResponse.text);

  // 列出文件
  const fileResponse = await agent.generate("List files in current directory");
  console.log(fileResponse.text);

  // 讲笑话
  const jokeResponse = await agent.generate("Tell me a joke");
  console.log(jokeResponse.text);
}

callAgent();

工具详情

1. 天气工具 (weatherTool)

• 功能：通过 Open-Meteo API 获取实时天气数据
• 输入：城市名称
• 输出：温度、体感温度、湿度、风速、天气状况

2. 时间工具 (timeTool)

• 功能：返回当前 ISO 时间和时区
• 输入：无
• 输出：当前时间、时区

3. 计算器工具 (calculatorTool)

• 功能：执行基本算术运算
• 输入：操作类型（add/subtract/multiply/divide）、两个数字
• 输出：计算结果、操作描述

4. 文件列表工具 (filelistTool)

• 功能：列出指定目录的文件
• 输入：（可选）目录路径
• 输出：文件数组、目录路径

5. 笑话工具 (jokeTool)

• 功能：随机返回一个预设笑话
• 输入：无
• 输出：笑话文本

扩展功能

添加新工具

1. 在 src/mastra/tools/ 目录下创建新的工具文件
2. 实现工具逻辑，使用 createTool 函数
3. 在 tools/index.ts 中导出新工具
4. 在 agent 配置中添加该工具

添加记忆功能

安装 memory 包并配置：

pnpm add @mastra/memory @mastra/libsql

然后在 agent 配置中添加：

import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";

export const agent = new Agent({
  // ... 其他配置
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:./mastra.db",
    }),
  }),
});

添加语音功能

安装语音包并配置：

pnpm add @mastra/voice-openai

import { OpenAIVoice } from "@mastra/voice-openai";

export const agent = new Agent({
  // ... 其他配置
  voice: new OpenAIVoice(),
});

故障排除

常见问题

1. API 密钥错误

   • 检查 .env 文件中的 OPENAI_API_KEY 是否正确
   • 确保密钥有足够的额度

2. 服务器启动失败

   • 检查端口 4111 是否被占用
   • 尝试 pnpm build 检查构建错误

3. 工具调用失败

   • 检查网络连接（天气工具需要网络）
   • 确认工具输入格式正确

获取帮助

• Mastra 官方文档
• Mastra Discord 社区

许可证

MIT