236 lines
5.4 KiB
Markdown
236 lines
5.4 KiB
Markdown
# 多功能 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. 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 配置 API 密钥
|
||
|
||
复制 `.env.example` 为 `.env`，并填入你的 OpenAI API 密钥：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
```
|
||
OPENAI_API_KEY=sk-your-openai-api-key-here
|
||
```
|
||
|
||
### 3. 启动开发服务器
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
服务器将在 http://localhost:4111 启动。
|
||
|
||
### 4. 使用 Agent
|
||
|
||
#### 通过 Studio UI 交互
|
||
|
||
打开浏览器访问 http://localhost:4111，在 Studio 界面中与你的 agent 对话。
|
||
|
||
#### 通过 HTTP API 调用
|
||
|
||
```bash
|
||
# 获取当前时间
|
||
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 代码调用
|
||
|
||
```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 包并配置：
|
||
|
||
```bash
|
||
pnpm add @mastra/memory @mastra/libsql
|
||
```
|
||
|
||
然后在 agent 配置中添加：
|
||
|
||
```typescript
|
||
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",
|
||
}),
|
||
}),
|
||
});
|
||
```
|
||
|
||
### 添加语音功能
|
||
|
||
安装语音包并配置：
|
||
|
||
```bash
|
||
pnpm add @mastra/voice-openai
|
||
```
|
||
|
||
```typescript
|
||
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 官方文档](https://mastra.ai/docs)
|
||
- [Mastra Discord 社区](https://discord.gg/BTYqqHKUrf)
|
||
|
||
## 许可证
|
||
|
||
MIT |