作者：来自 Elastic JD Armada

了解如何在 JavaScript 生态系统中构建 AI 代理。

Elasticsearch 与业界领先的生成式 AI 工具和服务商有原生集成。查看我们的网络研讨会，了解如何超越 RAG 基础，或使用 Elastic 向量数据库构建可投入生产的应用。

为了为你的使用场景构建最佳搜索解决方案，现在就开始免费云端试用，或者在本地机器上试用 Elastic。

这个想法是在一场激烈且充满赌注的幻想篮球联赛中冒出来的。我在想：我能否构建一个 AI 代理，帮助我主宰每周的对决？当然可以！

在这篇文章中，我们将探索如何使用 Mastra 和一个轻量级的 JavaScript Web 应用来构建一个具备代理能力的 RAG 助手，并与它进行交互。通过将这个代理连接到 Elasticsearch，我们为它提供了访问结构化球员数据的能力，并能执行实时统计聚合，从而为你提供基于球员数据的推荐。前往 GitHub 仓库查看详情；README 文件提供了如何克隆并在本地运行该应用的说明。

当所有部分组装完成后，它应该是这样的：

注意：这篇博文是在《使用 AI SDK 和 Elastic 构建 AI 代理》的基础上扩展的。如果你对 AI 代理还不熟悉，或者想了解它们可以用于什么场景，建议先阅读那篇文章。

架构概览

系统的核心是一种大型语言模型（LLM），它充当代理的推理引擎（大脑）。它负责解释用户输入，决定调用哪些工具，并协调生成相关响应所需的步骤。

代理本身是由 Mastra 搭建的，它是 JavaScript 生态中的一个代理框架。Mastra 将 LLM 封装进后端基础架构，作为一个 API 端点暴露出来，并提供一个界面，用于定义工具、系统提示词和代理行为。

在前端，我们使用 Vite 快速搭建一个 React Web 应用，为用户提供一个聊天界面，用于发送查询给代理并接收其响应。

最后，我们有 Elasticsearch，用于存储球员统计和对阵数据，供代理查询和聚合使用。

背景

让我们先了解一些基本概念：

什么是 agentic RAG？

AI 代理可以与其他系统交互，独立运行，并根据其定义的参数执行操作。Agentic RAG 将 AI 代理的自主性与检索增强生成（retrieval augmented generation - RAG）的原理相结合，使 LLM 能够选择调用哪些工具、使用哪些数据作为上下文来生成响应。你可以在这里关于 RAG 的内容。

选择框架，为什么要超越 AI-SDK？

目前市面上有许多 AI 代理框架，你可能听说过比较流行的，比如 CrewAI、AutoGen 和 LangGraph。这些框架大多具有一套通用功能，包括对不同模型的支持、工具使用和记忆管理等。

以下是 LangChain CEO Harrison Chase 提供的一份框架对比表。

我之所以对 Mastra 感兴趣，是因为它是一个面向 JavaScript 的框架，为全栈开发者设计，可以轻松将代理集成进他们的开发生态。Vercel 的 AI-SDK 也能完成大部分工作，但 Mastra 的优势在于处理更复杂的代理工作流时更胜一筹。Mastra 在 AI-SDK 提供的基础模式上进行了增强，在这个项目中，我们将二者结合使用。

关于框架和模型选择的考量

虽然这些框架可以帮助你快速构建 AI 代理，但也存在一些缺点。例如，当你使用这些抽象层而不是自己动手实现时，会失去一些控制权。如果 LLM 没有正确调用工具或做出不符合预期的行为，由于抽象层的存在，调试会更加困难。尽管如此，我认为这种权衡是值得的，因为这些框架开发速度快，生态正在快速发展。

此外，这些框架都是模型无关的，也就是说你可以自由切换不同的模型，但要记住，各个模型训练的数据集不同，因此响应表现也会不同。有些模型甚至不支持调用工具。所以你可以尝试多个模型，看看哪个效果最好，不过你很可能需要为每个模型重新编写系统提示词。例如，如果你想用 Llama3.3 替代 GPT-4o，就需要提供更多提示词和具体指令才能获得理想结果。

NBA 幻想篮球

幻想篮球是和一群朋友组成联盟（提醒：如果你的朋友们非常好胜，可能会影响你们的友情），通常还会涉及一些金钱下注。你们每人选出 10 名球员组成自己的队伍，每周与别人的队伍进行对战。你每周的得分取决于你的球员在现实比赛中的表现。

如果你队伍中的某个球员受伤、被禁赛等，可以从自由球员列表中添加新球员。这也是幻想体育中思考最多的环节，因为你的增援次数有限，而其他人也都在寻找最有潜力的球员。

这正是我们的 NBA AI 助手大放异彩的时刻，尤其是在你需要快速决定该选哪位球员时。你无需再手动查找某个球员对某个对手的历史表现，助手可以快速获取数据并对比平均值，为你提供有根据的推荐。

现在你已经了解了 agentic RAG 和 NBA 幻想篮球的一些基础知识，让我们看看它是如何实际运作的。

构建项目

如果你在构建过程中遇到问题，或者不想从零开始搭建，请参考项目仓库。

我们将涵盖以下内容：

搭建项目结构

后端（Mastra）：使用 npx create mastra@latest 搭建后端并定义代理逻辑。
前端（Vite + React）：使用 npm create vite@latest 创建前端聊天界面，用于与代理交互。

设置环境变量

安装 dotenv 来管理环境变量。
创建 .env 文件并提供所需变量。

设置 Elasticsearch

启动一个 Elasticsearch 集群（本地或云端均可）。
安装官方 Elasticsearch 客户端。
确保环境变量可被访问。
建立与客户端的连接。

将 NBA 数据批量导入 Elasticsearch

创建索引并定义适当的 mapping，以支持聚合操作。
从 CSV 文件中批量导入球员比赛统计数据到 Elasticsearch 索引中。

定义 Elasticsearch 聚合

查询某球员对特定对手的历史平均值。
查询某球员对特定对手的赛季平均值。

玩家比较工具文件

整合辅助函数和 Elasticsearch 聚合逻辑。

构建代理

添加代理定义和系统提示词。
安装 zod 并定义工具。
添加中间件以处理 CORS。

集成前端

使用 AI-SDK 的 useChat 与代理交互。
创建 UI 界面以支持格式化的对话显示。

运行应用

启动后端（Mastra 服务器）和前端（React 应用）。
尝试示例查询，体验应用使用方式。

下一步：让代理更智能

添加语义搜索（semantic search）功能，以实现更有洞察力的推荐。
通过将搜索逻辑转移到 Elasticsearch MCP（模型上下文协议）服务器，实现动态查询。

前置条件

Node.js 和 npm：后端和前端均基于 Node 运行。请确保你安装了 Node 18+ 和 npm v9+（Node 18+ 已自带 npm）。
Elasticsearch 集群：本地或云端运行的 Elasticsearch 集群。
OpenAI API 密钥：在 OpenAI 开发者门户的 API 密钥页面生成。

项目结构

npx create-mastra@latest

第 1 步：搭建项目框架

首先，创建目录 nba-ai-assistant-js 并使用以下命令进入该目录：

mkdir nba-ai-assistant-js && cd nba-ai-assistant-js

后端：

1）使用 Mastra 创建工具，命令如下：

npx create-mastra@latest

2）你会在终端看到一些提示，第一个提示中，我们将项目命名为 backend：

3）接下来，我们保持默认的 Mastra 文件存储结构，所以输入 src/。

4）然后，我们选择 OpenAI 作为默认的 LLM 提供商。

5）最后，它会询问你的 OpenAI API 密钥。现在，我们选择跳过，稍后在 .env 文件中提供。

前端：

1）返回到根目录，运行 Vite 创建工具，命令如下：

npm create vite@latest frontend -- --template react

这会创建一个名为 frontend 的轻量级 React 应用，使用专门的 React 模板。

如果一切顺利，你的项目目录下应该有一个存放 Mastra 代码的 backend 目录和一个包含 React 应用的 frontend 目录。

第 2 步：设置环境变量

1）为了管理敏感密钥，我们将使用 dotenv 包从 .env 文件加载环境变量。进入 backend 目录并安装 dotenv：

cd backend
npm install dotenv --save

2）在 backend 目录中，有一个 example.env 文件，里面包含需要填写的变量。如果你自己创建 .env 文件，请确保包含以下变量：

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here# Elasticsearch Configuration
ELASTIC_ENDPOINT=your_elasticsearch_endpoint_here
ELASTIC_API_KEY=your_elasticsearch_api_key_here

注意：确保将该文件从版本控制中排除，在 .gitignore 中添加 .env。

第 3 步：设置 Elasticsearch

首先，你需要一个活动的 Elasticsearch 集群，有两个选项：

选项 A：使用 Elasticsearch Cloud
- 注册 Elastic Cloud
- 创建一个新部署
- 获取你的端点 URL 和 API 密钥（已编码）
选项 B：本地运行 Elasticsearch
- 安装并本地运行 Elasticsearch
- 使用 http://localhost:9200 作为端点
- 生成 API 密钥

在后端安装 Elasticsearch 客户端：

1）首先，在 backend 目录安装官方 Elasticsearch 客户端：

npm install @elastic/elasticsearch

2）然后创建一个名为 lib 的目录来存放可复用函数，并进入该目录：

mkdir lib && cd lib

3）在里面创建一个名为 elasticClient.js 的新文件。这个文件将初始化 Elasticsearch 客户端，并供项目中各处使用。

4）由于我们使用的是 ECMAScript 模块（ESM），所以 __dirname 和 __filename 不可用。为了确保环境变量能正确从 backend 文件夹的 .env 文件加载，请在文件顶部添加以下配置：

import { config } from 'dotenv';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { Client } from '@elastic/elasticsearch';// Grab current directory and load .env from backend folder
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const envPath = join(__dirname, '../.env');// Load environment variables from the correct path
config({ path: envPath });

5）现在，使用你的环境变量初始化 Elasticsearch 客户端，并检查连接：

//Elastic client Initialization, make sure environment variables are being loaded in correctly
const config= {node: `${process.env.ELASTIC_ENDPOINT}`,auth: {apiKey: `${process.env.ELASTIC_API_KEY}`,},
};export const elasticClient = new Client(config);//Check if the client is connected
async function checkConnection() { try {const info = await elasticClient.info();console.log('Elasticsearch is connected:', info);} catch (error) {console.error('Elasticsearch connection error:', error);}
}checkConnection();

现在，我们可以在任何需要与 Elasticsearch 集群交互的文件中导入这个客户端实例。

第 4 步：将 NBA 数据批量导入 Elasticsearch

数据集：

本项目将使用仓库中 backend/data 目录下的数据集。我们的 NBA 助手将利用这些数据作为知识库，进行统计比较和生成推荐。

sample_player_game_stats.csv — 示例球员比赛统计数据（例如每场比赛的得分、篮板、抢断等，涵盖球员整个 NBA 职业生涯）。我们将使用该数据集进行聚合。（注意：这是模拟数据，预先生成用于演示，不来源于官方 NBA 数据。）
playerAndTeamInfo.js — 用作球员和球队元数据的替代，通常这些数据会通过 API 调用获得，代理需要它来匹配球员和球队名称与 ID。因为我们用的是示例数据，所以避免从外部 API 获取的开销，代理可以参考这里硬编码的值。

实现步骤：

1）在 backend/lib 目录下创建名为 playerDataIngestion.js 的文件。

2）设置导入内容，解析 CSV 文件路径并配置解析。由于使用 ESM，我们需要重构 __dirname 来解析示例 CSV 文件路径。同时，我们将导入 Node.js 内置模块 fs 和 readline，逐行解析 CSV 文件。

import fs from 'fs';
import readline from 'readline';
import path from 'path';
import { fileURLToPath } from 'url';
import { elasticClient } from './elasticClient.js';const indexName = 'sample-nba-player-data'; //Replace with your preferred index name//Since we are using ES modules __dirname and __filename don't exist, so this is a workaround that allows us to use the absolute file path for our sample data.
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const filePath = path.resolve(__dirname, '../data/sample_nba_data.csv');

这为我们后续进行批量导入时高效读取和解析 CSV 文件做好了准备。

3）创建一个带有合适 mapping 的索引。虽然 Elasticsearch 支持动态映射自动推断字段类型，但这里我们希望明确指定，以确保每个统计字段都被视为数值型字段。这很重要，因为我们后续会用这些字段进行聚合计算。对于得分、篮板等统计数据，我们使用 float 类型，以确保包含小数值。最后，我们添加 mapping 属性 dynamic: 'strict'，防止 Elasticsearch 对未识别字段进行动态映射。

// Function to create an index with mappings
async function createIndex() {try {// Check if the index already existsconst exists = await elasticClient.indices.exists({ index: indexName });if (exists) {console.log(`Index "${indexName}" already exists, deleting it now.`);await elasticClient.indices.delete({ index: indexName });console.log(`Deleted index "${indexName}".`);}// Create the index with mappingsconst response = await elasticClient.indices.create({index: indexName,body: {mappings: {dynamic: 'strict', // Prevent dynamic mappingproperties: {game_id: { type: 'integer' },game_date: { type: 'date' },player_id: { type: 'integer' },player_full_name: { type: 'text' },player_team_id: { type: 'integer' },player_team_name: { type: 'text' },home_team: { type: 'boolean' },opponent_team_id: { type: 'integer' },opponent_team_name: { type: 'text' },points: { type: 'float' },rebounds: { type: 'float' },assists: { type: 'float' },steals: { type: 'float' },blocks: { type: 'float' },fg_percentage: { type: 'float' },minutes_played: { type: 'float' },},},},});console.log('Index created:', response);return true;} catch (error) {console.error('Error creating index:', error);return false;}
}

4）添加一个函数，将 CSV 数据批量导入到 Elasticsearch 索引中。在代码中，我们跳过表头行，然后用逗号分割每行数据，并将其放入文档对象中。此步骤还会清理数据，确保它们的类型正确。接着，我们将这些文档和索引信息一起推入 bulkBody 数组，作为批量导入 Elasticsearch 的请求载荷。

async function bulkIngestCsv(filePath) {const readStream = fs.createReadStream(filePath);const rl = readline.createInterface({input: readStream,crlfDelay: Infinity,});const bulkBody = [];let lineNum = 0;//Skip the header linelet headerLine = true;for await (const line of rl) {if (headerLine) {headerLine = false;continue;}lineNum++;// Split the line by comma and remove whitespaceconst [game_id,game_date,player_id,player_full_name,player_team_id,player_team_name,home_team,opponent_team_id,opponent_team_name,points,rebounds,assists,steals,blocks,fg_percentage,minutes_played,] = line.split(',');// Create a document objectconst document = {game_id: parseInt(game_id),game_date: game_date.trim(),player_id: parseInt(player_id),player_full_name: player_full_name.trim(),player_team_id: parseInt(player_team_id),player_team_name: player_team_name.trim(),home_team: home_team.trim() === 'True', // Converts True/False into a booleanopponent_team_id: parseInt(opponent_team_id),opponent_team_name: opponent_team_name.trim(),points: parseFloat(points),rebounds: parseFloat(rebounds),assists: parseFloat(assists),steals: parseFloat(steals),blocks: parseFloat(blocks),fg_percentage: parseFloat(fg_percentage),minutes_played: parseFloat(minutes_played),};// Prepare the bulk operation formatbulkBody.push({ index: { _index: indexName } });bulkBody.push(document);}console.log(`Parsed ${lineNum} lines from CSV`);

5）然后，我们可以使用 Elasticsearch 的 Bulk API，通过 elasticClient.bulk() 在一次请求中导入多条文档。下面的错误处理逻辑会统计有多少文档导入失败，以及有多少成功。

try {// Perform the bulk requestconst response = await elasticClient.bulk({ body: bulkBody });if (response.errors) {console.log('Bulk Ingestion had some hiccups:');// Count successful vs failed operationslet successCount = 0;let errorCount = 0;const errorDetails = [];response.items.forEach((item, index) => {const operation = item.index || item.create || item.update || item.delete;if (operation.error) {errorCount++;errorDetails.push({document: index + 1,error: operation.error,});} else {successCount++;}});console.log(`Successfully indexed: ${successCount} documents`);console.log(`Failed to index: ${errorCount} documents, here are the details`, errorDetails);} else {console.log(`Bulk Ingestion fully successful!`);}} catch (error) {console.error('Error performing bulk ingestion:', error);}
}

6）运行下面的 main() 函数，依次执行 createIndex() 和 bulkIngestCsv() 两个函数。

// Run this function
async function main() {const result = await createIndex();if (!result) {console.error('Index setup failed. Aborting.');return;}await bulkIngestCsv(filePath);console.log('Bulk ingestion completed!');
}main();

如果你看到控制台日志显示批量导入成功，可以快速检查一下 Elasticsearch 索引，确认文档是否真的成功导入。

第 5 步：定义 Elasticsearch 聚合并整合函数

这些将是我们为 AI 代理定义工具时使用的主要函数，用于比较球员之间的统计数据。

1）进入 backend/lib 目录，创建一个名为 elasticAggs.js 的文件。

2）添加下面的查询，用于计算某球员对特定对手的历史平均数据。该查询使用一个包含两个条件的 bool 过滤器：一个匹配 player_id，另一个匹配 opponent_team_id，确保只检索相关比赛。我们不需要返回具体文档，只关心聚合结果，所以设置 size: 0。在 aggs 块中，同时对 points、rebounds、assists、steals、blocks 和 fg_percentage 等字段进行多个指标聚合，计算它们的平均值。LLM 在计算方面可能不准确，这样做将计算任务交给 Elasticsearch，确保我们的 NBA AI 助手能获得准确的数据。

export async function getHistoricalAveragesAgainstOpponent(player_id, opponent_team_id) {try {//Query for Historical Averagesconst historicalQuery = await elasticClient.search({index: 'sample-nba-player-data', size: 0,query: {bool: {must: [{term: {player_id: {value: player_id,},},},{term: {opponent_team_id: {value: opponent_team_id,},},},],},},aggs: {avg_points: { avg: { field: 'points' } },avg_rebounds: { avg: { field: 'rebounds' } },avg_assists: { avg: { field: 'assists' } },avg_steals: { avg: { field: 'steals' } },avg_blocks: { avg: { field: 'blocks' } },avg_fg_percentage: { avg: { field: 'fg_percentage' } },},});return {points: historicalQuery.aggregations.avg_points.value || 0,rebounds: historicalQuery.aggregations.avg_rebounds.value || 0,assists: historicalQuery.aggregations.avg_assists.value || 0,steals: historicalQuery.aggregations.avg_steals.value || 0,blocks: historicalQuery.aggregations.avg_blocks.value || 0,fgPercentage: historicalQuery.aggregations.avg_fg_percentage.value || 0,};} catch (error) {console.error('Query error from getHistoricalAveragesAgainstOpponent function:', error);return { error: 'Queries failed in getting historical averages against opponent.' };}
}

3）要计算某球员对特定对手的赛季平均数据，我们使用与历史平均几乎相同的查询。唯一的区别是 bool 过滤器中增加了对 game_date 的条件，game_date 必须在当前 NBA 赛季范围内，这里是 2024-10-01 到 2025-06-30。这个额外条件确保后续的聚合只统计本赛季的比赛数据。

        {range: {//Range for this season, change to match current seasongame_date: {gte: '2024-10-01',lte: '2025-06-30',},},

第 6 步：球员比较工具

为了保持代码的模块化和易维护性，我们将创建一个工具文件，整合元数据辅助函数和 Elasticsearch 聚合逻辑。这将支持代理使用的主要工具。稍后会详细介绍：

1）在 backend/lib 目录下新建一个文件 comparePlayers.js。

2）添加以下函数，将元数据辅助和 Elasticsearch 聚合逻辑整合到一个函数中，支持代理使用的主要工具。

import { playersByName } from '../data/playerAndTeamInfo.js';
import { teamsByName } from '../data/playerAndTeamInfo.js';
import { upcomingMatchups } from '../data/playerAndTeamInfo.js';
import { getHistoricalAveragesAgainstOpponent } from './elasticAggs.js';
import { getSeasonAveragesAgainstOpponent } from './elasticAggs.js';//Simple helper functions to simulate API calls for player and team metadata. These reference the hardcoded values from playerAndTeamInfo.js in the data directory
export function getPlayerInfo(playerFullName) {return playersByName[playerFullName];
}export function getTeamID(teamFullName) {return teamsByName[teamFullName];
}export function getUpcomingMatchups(teamId) {return upcomingMatchups[teamId];
}//Main function used by the 'playerComparisonTool' agent tool
export async function comparePlayersForNextMatchup(player1Name, player2Name) {//Get Player Infoconst player1Info = getPlayerInfo(player1Name);const player2Info = getPlayerInfo(player2Name);//Get upcoming matchupsconst player1NextGame = getUpcomingMatchups(player1Info.team_id)[0];const player2NextGame = getUpcomingMatchups(player2Info.team_id)[0];//Get season and historical averages against next opponent for player 1const player1SeasonAverages = await getSeasonAveragesAgainstOpponent(player1Info.player_id,player1NextGame.opponent_team_id);const player1HistoricalAverages = await getHistoricalAveragesAgainstOpponent(player1Info.player_id,player1NextGame.opponent_team_id);//Get season and historical averages against next opponent for player 2const player2SeasonAverages = await getSeasonAveragesAgainstOpponent(player2Info.player_id,player2NextGame.opponent_team_id);const player2HistoricalAverages = await getHistoricalAveragesAgainstOpponent(player2Info.player_id,player2NextGame.opponent_team_id);const player1 = {name: player1Name,playerId: player1Info.player_id,teamId: player1Info.team_id,nextOpponent: {teamId: player1NextGame.opponent_team_id,teamName: player1NextGame.opponent_team_name,home: player1NextGame.home,},stats: {seasonAverages: player1SeasonAverages,historicalAverages: player1HistoricalAverages,},};const player2 = {name: player2Name,playerId: player2Info.player_id,teamId: player2Info.team_id,nextOpponent: {teamId: player2NextGame.opponent_team_id,teamName: player2NextGame.opponent_team_name,home: player2NextGame.home,},stats: {seasonAverages: player2SeasonAverages,historicalAverages: player2HistoricalAverages,},};return [player1, player2];
}

第 7 步：构建代理

现在你已经搭建了前后端框架，导入了 NBA 比赛数据，并建立了与 Elasticsearch 的连接，我们可以开始把各部分组合起来，构建代理。

定义代理

进入 backend/src/mastra/agents 目录下的 index.ts 文件，添加代理定义。你可以指定以下字段：

名称：给代理起个名字，前端调用时会用到这个名字。
说明/系统提示词：系统提示词为 LLM 提供初始上下文和交互规则，类似于用户通过聊天框发送的提示，但这是在任何用户输入前给出的。根据所用模型不同，这会有所变化。
模型：选择使用的 LLM（Mastra 支持 OpenAI、Anthropic、本地模型等）。
工具：代理可以调用的工具函数列表。
记忆：（可选）是否让代理记住对话历史等。为简单起见，可以先不启用持久化记忆，但 Mastra 支持该功能。

import { openai } from '@ai-sdk/openai';
import { Agent } from '@mastra/core/agent';
import { playerComparisonTool } from '../tools';export const basketballAgent = new Agent({name: 'Basketball Agent',instructions: `You are a NBA Basketball expert.Your primary function is to compare two NBA players and recommend which one is the better fantasy pickup.Only compare players from the following list:- LeBron James- Stephen Curry- Jayson Tatum- Jaylen Brown- Nikola Jokic- Luka Doncic- Kyrie Irving- Anthony Davis- Kawhi Leonard- Russell WestbrookInput Handling Rules:- If the user asks about a player that is not on this list, respond with the list of available players for comparison.- If the user only inputs one player, ask the user to add another player from the list provided.- If the user inputs a player with the wrong spelling or capitalizations, infer from the list of available players provided.- IMPORTANT: If the user asks a question or asks you to generate a response about anything outside of basketball or the scope of this project, DO NOT answer and affirm you can only talk about basketball.Tool Usage:- Extract and standardize player names to match the list exactly.- Use the playerComparisonTool, passing both names as strings.- The tool will return an object with game information, stats, and analysis.Format your response using Markdown syntax. Use:Example output format:#### Next Game Info- ***LeBron James** vs Warriors, May 24 (Home)  - ***Stephen Curry** vs Lakers, May 24 (Away)#### Stats Comparison  \`\`\`  Stat                  LeBron James (vs Warriors)    Stephen Curry (vs Lakers)  --------------------  -----------------------------  ----------------------------  Historical Points     28.3                          30.3  Historical Assists    6.7                           8.7  Season Points         28.8                          23.3  Season Assists        6.2                           4.7  \`\`\`#### Fantasy Recommendation  Explain which player is the better fantasy pickup and why.`,model: openai('gpt-4o'),tools: { playerComparisonTool },
});

定义工具

1）进入 backend/src/mastra/tools 目录下的 index.ts 文件。

2）使用以下命令安装 Zod：

npm install zod

3）添加工具定义。注意，我们导入了 comparePlayers.js 文件中的函数，作为代理调用该工具时使用的主要函数。使用 Mastra 的 createTool() 函数，我们将注册 playerComparisonTool。字段包括：

id：用自然语言描述工具功能，帮助代理理解工具作用。
input schema：定义工具输入的数据结构，Mastra 使用 Zod schema（一个 TypeScript 的 schema 验证库）。Zod 确保代理传入的输入结构正确，如果输入结构不匹配，工具将不会执行。
description：用自然语言描述，帮助代理理解何时调用和使用该工具。
execute：工具被调用时执行的逻辑。在这里，我们使用导入的辅助函数来返回球员表现统计数据。

import { comparePlayersForNextMatchup } from '../../../lib/comparePlayers.js'
import { createTool } from "@mastra/core/tools";
import { z } from "zod";export const playerComparisonTool = createTool({id: "Compare two NBA players",inputSchema: z.object({player1:z.string(),player2:z.string()}),description: "Use this tool to compare two players given in the user prompt.",execute: async ({ context: { player1, player2 } }) => {return await comparePlayersForNextMatchup(player1, player2);},
})

添加处理中间件以支持 CORS

在 Mastra 服务器中添加中间件来处理 CORS。他们说人生中有三件事不可避免：死亡、税收，还有对前端开发来说的 CORS。简单来说，跨域资源共享（CORS）是浏览器的一种安全机制，阻止前端向运行在不同域名或端口的后端发请求。即使我们前后端都运行在 localhost，但它们端口不同，会触发 CORS 策略。我们需要按照 Mastra 文档添加中间件，使后端允许来自前端的请求。

进入 backend/src/mastra 目录下的index.ts 文件，添加 CORS 配置：

origin: ['http://localhost:5173']
只允许来自这个地址的请求（Vite 默认地址）
allowMethods: ["GET", "POST"]
允许的 HTTP 方法，大多数情况下使用 POST
allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type", "x-highlight-request", "traceparent"]
允许请求中使用的自定义头部字段

import { Mastra } from '@mastra/core/mastra';
import { basketballAgent } from './agents';console.log('Starting Mastra server...');export const mastra = new Mastra({agents: { basketballAgent },server:{timeout: 10 * 60 * 1000, // 10 minutescors: {origin: ['http://localhost:5173'],allowMethods: ["GET", "POST"],allowHeaders: ["Content-Type","Authorization","x-mastra-client-type","x-highlight-request","traceparent",],exposeHeaders: ["Content-Length", "X-Requested-With"],credentials: false,},},});console.log('Mastra server configured.'); // Log after server configuration

第 8 步：集成前端

这个 React 组件提供了一个简单的聊天界面，使用 @ai-sdk/react 中的 useChat() hook 连接到 Mastra AI 代理。我们还会用这个 hook 显示 token 使用情况、工具调用，并渲染对话内容。在系统提示词中，我们要求代理以 markdown 格式输出响应，所以会使用 react-markdown 来正确格式化响应。

1) 在 frontend 目录下，安装 @ai-sdk/react 包以使用 useChat() hook。

npm install @ai-sdk/react

2）在同一目录下，安装 React Markdown，以便我们能够正确格式化代理生成的响应内容。

npm install react-markdown

3）实现 useChat()。这个 hook 将管理前端与 AI 代理后端之间的交互。它负责处理消息状态、用户输入、交互状态，并提供生命周期钩子用于可观测性。我们传入的选项包括：

api：定义 Mastra AI 代理的接口地址。默认使用 4111 端口，并添加支持流式响应的路由。
onToolCall：每当代理调用某个工具时执行；我们用它来追踪代理调用了哪些工具。
onFinish：代理完整响应完成后执行。尽管启用了流式响应，onFinish 仍会在完整消息接收后执行，而不是每个 chunk 后执行。我们在这里用它来统计 token 使用量，这对监控 LLM 成本和优化非常有帮助。

4）最后，进入 frontend/components 目录下的 ChatUI.jsx 组件，创建用于显示对话的界面。然后使用 ReactMarkdown 组件包裹响应内容，以便正确格式化代理的 markdown 响应。

import React, { useState } from 'react';
import { useChat } from '@ai-sdk/react';
import ReactMarkdown from 'react-markdown';export default function ChatUI() {const [totalTokenUsage, setTotalTokenUsage] = useState(0);const [promptTokenUsage, setPromptTokenUsage] = useState(0);const [completionTokenUsage, setCompletionTokenUsage] = useState(0);const [toolsCalled, setToolsCalled] = useState([]);const { messages, input, handleInputChange, handleSubmit, status } = useChat({api: 'http://localhost:4111/api/agents/basketballAgent/stream', //Replace with your own endpoint for your agentid: 'my-chat-session',//Optional parameter to check agent tool callsonToolCall: ({ toolCall }) => {setToolsCalled((prev) => [...prev, toolCall.toolName]);},//Optional parameter to check token usagesonFinish: (message, { usage }) => {setTotalTokenUsage((prev) => prev + usage.totalTokens);setPromptTokenUsage((prev) => prev + usage.promptTokens);setCompletionTokenUsage((prev) => prev + usage.completionTokens);},//Optional parameter for error handlingonError: (error) => {console.error('Agent error:', error);},});return (<div><div className="agent-info"><h4 className="stats-title">What's My Agent Doing?</h4><div className="stats-box"><strong className="stats-sub-title">Tools Called:</strong><ul className="tool-list">{toolsCalled.map((tool, idx) => (<li key={idx}>{tool}</li>))}{toolsCalled.length === 0 && <li>No tools called yet.</li>}</ul><div className="usage-stats"><p>Prompt Token Usage: {promptTokenUsage}</p><p>Completion Token Usage: {completionTokenUsage}</p><p>Total Token Usage: {totalTokenUsage}</p></div></div></div><strong>Conversation:</strong><div className="convo-box">{messages.map((msg) => (<div key={msg.id} className="message-item"><strong className="message-role">{msg.role === 'assistant' ? 'Basketbot' : 'You'}:</strong><ReactMarkdown>{msg.content}</ReactMarkdown></div>))}</div><form onSubmit={handleSubmit}><inputtype="text"value={input}onChange={handleInputChange}placeholder="Input two players you want to compare."className="input-box"/><button type="submit" disabled={status === 'streaming'}>{status === 'streaming' ? 'Thinking...' : 'Send'}</button></form></div>);
}

第 9 步：运行应用程序

恭喜！现在你已经可以运行整个应用程序了。按照以下步骤同时启动后端和前端：

1）在终端窗口中，从项目根目录开始，进入 backend 目录并启动 Mastra 服务器：

cd backendnpm run dev

2）在另一个终端窗口中，从项目根目录开始，进入 frontend 目录并启动 React 应用：

cd frontendnpm run dev

3）打开浏览器，访问：

http://localhost:5173

你应该能看到聊天界面。试试以下示例提示：

"Compare LeBron James and Stephen Curry"
"Who should I pick between Jayson Tatum and Luka Doncic?"

下一步：让代理更智能

为了让助手更加智能化、推荐更具洞察力，我将在下一个迭代中添加几个关键升级。

对 NBA 新闻进行语义搜索

影响球员表现的因素有很多，其中很多并不会体现在原始统计数据中。例如伤病报告、首发阵容变动、甚至赛后分析，这些只能通过新闻报道获取。为了捕捉这些额外的上下文信息，我将添加语义搜索功能，让代理能够检索相关的 NBA 文章，并将这些叙事信息纳入推荐逻辑中。

使用 Elasticsearch MCP 服务器进行动态搜索

MCP（Model Context Protocol）正快速成为代理连接数据源的标准方式。我会将搜索逻辑迁移到 Elasticsearch MCP 服务器中，这样代理就能动态构建查询，而不再依赖我们手动定义的搜索函数。这使得我们可以使用更自然的语言工作流，也减少了手动编写每一个查询语句的需求。
在这里了解更多关于 Elasticsearch MCP 服务器和当前生态的内容。

这些改进正在进行中，敬请期待！