作者：来自 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`AI写代码
第 1 步：搭建项目框架
首先，创建目录 nba-ai-assistant-js 并使用以下命令进入该目录：
`mkdir nba-ai-assistant-js && cd nba-ai-assistant-js`AI写代码
后端：
1）使用 Mastra 创建工具，命令如下：
`npx create-mastra@latest`AI写代码
2）你会在终端看到一些提示，第一个提示中，我们将项目命名为 backend：
3）接下来，我们保持默认的 Mastra 文件存储结构，所以输入 src/。
4）然后，我们选择 OpenAI 作为默认的 LLM 提供商。
5）最后，它会询问你的 OpenAI API 密钥。现在，我们选择跳过，稍后在 .env 文件中提供。
前端：
1）返回到根目录，运行 Vite 创建工具，命令如下：
`npm create vite@latest frontend -- --template react`AI写代码
这会创建一个名为 frontend 的轻量级 React 应用，使用专门的 React 模板。
如果一切顺利，你的项目目录下应该有一个存放 Mastra 代码的 backend 目录和一个包含 React 应用的 frontend 目录。
第 2 步：设置环境变量
1）为了管理敏感密钥，我们将使用 dotenv 包从 .env 文件加载环境变量。进入 backend 目录并安装 dotenv：
`
1. cd backend
2. npm install dotenv --save
`AI写代码
2）在 backend 目录中，有一个 example.env 文件，里面包含需要填写的变量。如果你自己创建 .env 文件，请确保包含以下变量：
`
1. # OpenAI Configuration
2. OPENAI_API_KEY=your_openai_api_key_here
4. # Elasticsearch Configuration
5. ELASTIC_ENDPOINT=your_elasticsearch_endpoint_here
6. ELASTIC_API_KEY=your_elasticsearch_api_key_here
`AI写代码
注意：确保将该文件从版本控制中排除，在 .gitignore 中添加 .env。
第 3 步：设置 Elasticsearch
首先，你需要一个活动的 Elasticsearch 集群，有两个选项：
- 选项 A：使用 Elasticsearch Cloud
-
创建一个新部署
-
获取你的端点 URL 和 API 密钥（已编码）
- 选项 B：本地运行 Elasticsearch
-
安装并本地运行 Elasticsearch
-
使用 http://localhost:9200 作为端点
-
生成 API 密钥
-
在后端安装 Elasticsearch 客户端：
1）首先，在 backend 目录安装官方 Elasticsearch 客户端：
`npm install @elastic/elasticsearch`AI写代码
2）然后创建一个名为 lib 的目录来存放可复用函数，并进入该目录：
`mkdir lib && cd lib`AI写代码
3）在里面创建一个名为 elasticClient.js 的新文件。这个文件将初始化 Elasticsearch 客户端，并供项目中各处使用。
4）由于我们使用的是 ECMAScript 模块（ESM），所以 __dirname 和 __filename 不可用。为了确保环境变量能正确从 backend 文件夹的 .env 文件加载，请在文件顶部添加以下配置：
`
1. import { config } from 'dotenv';
2. import { fileURLToPath } from 'url';
3. import { dirname, join } from 'path';
4. import { Client } from '@elastic/elasticsearch';
6. // Grab current directory and load .env from backend folder
7. const __filename = fileURLToPath(import.meta.url);
8. const __dirname = dirname(__filename);
9. const envPath = join(__dirname, '../.env');
11. // Load environment variables from the correct path
12. config({ path: envPath });
`AI写代码
5）现在，使用你的环境变量初始化 Elasticsearch 客户端，并检查连接：
``
1. //Elastic client Initialization, make sure environment variables are being loaded in correctly
2. const config= {
3. node: `${process.env.ELASTIC_ENDPOINT}`,
4. auth: {
5. apiKey: `${process.env.ELASTIC_API_KEY}`,
6. },
7. };
9. export const elasticClient = new Client(config);
11. //Check if the client is connected
12. async function checkConnection() {
13. try {
14. const info = await elasticClient.info();
15. console.log('Elasticsearch is connected:', info);
16. } catch (error) {
17. console.error('Elasticsearch connection error:', error);
18. }
19. }
21. checkConnection();
``AI写代码
现在，我们可以在任何需要与 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 文件。
`
1. import fs from 'fs';
2. import readline from 'readline';
3. import path from 'path';
4. import { fileURLToPath } from 'url';
5. import { elasticClient } from './elasticClient.js';
7. const indexName = 'sample-nba-player-data'; //Replace with your preferred index name
9. //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.
10. const __filename = fileURLToPath(import.meta.url);
11. const __dirname = path.dirname(__filename);
12. const filePath = path.resolve(__dirname, '../data/sample_nba_data.csv');
`AI写代码
这为我们后续进行批量导入时高效读取和解析 CSV 文件做好了准备。
3）创建一个带有合适 mapping 的索引。虽然 Elasticsearch 支持动态映射自动推断字段类型，但这里我们希望明确指定，以确保每个统计字段都被视为数值型字段。这很重要，因为我们后续会用这些字段进行聚合计算。对于得分、篮板等统计数据，我们使用 float 类型，以确保包含小数值。最后，我们添加 mapping 属性 dynamic: 'strict'，防止 Elasticsearch 对未识别字段进行动态映射。
``
1. // Function to create an index with mappings
2. async function createIndex() {
3. try {
4. // Check if the index already exists
5. const exists = await elasticClient.indices.exists({ index: indexName });
7. if (exists) {
8. console.log(`Index "${indexName}" already exists, deleting it now.`);
9. await elasticClient.indices.delete({ index: indexName });
10. console.log(`Deleted index "${indexName}".`);
11. }
12. // Create the index with mappings
13. const response = await elasticClient.indices.create({
14. index: indexName,
15. body: {
16. mappings: {
17. dynamic: 'strict', // Prevent dynamic mapping
18. properties: {
19. game_id: { type: 'integer' },
20. game_date: { type: 'date' },
21. player_id: { type: 'integer' },
22. player_full_name: { type: 'text' },
23. player_team_id: { type: 'integer' },
24. player_team_name: { type: 'text' },
25. home_team: { type: 'boolean' },
26. opponent_team_id: { type: 'integer' },
27. opponent_team_name: { type: 'text' },
28. points: { type: 'float' },
29. rebounds: { type: 'float' },
30. assists: { type: 'float' },
31. steals: { type: 'float' },
32. blocks: { type: 'float' },
33. fg_percentage: { type: 'float' },
34. minutes_played: { type: 'float' },
35. },
36. },
37. },
38. });
40. console.log('Index created:', response);
41. return true;
42. } catch (error) {
43. console.error('Error creating index:', error);
44. return false;
45. }
46. }
``AI写代码
4）添加一个函数，将 CSV 数据批量导入到 Elasticsearch 索引中。在代码中，我们跳过表头行，然后用逗号分割每行数据，并将其放入文档对象中。此步骤还会清理数据，确保它们的类型正确。接着，我们将这些文档和索引信息一起推入 bulkBody 数组，作为批量导入 Elasticsearch 的请求载荷。
``
1. async function bulkIngestCsv(filePath) {
2. const readStream = fs.createReadStream(filePath);
3. const rl = readline.createInterface({
4. input: readStream,
5. crlfDelay: Infinity,
6. });
8. const bulkBody = [];
9. let lineNum = 0;
11. //Skip the header line
12. let headerLine = true;
13. for await (const line of rl) {
14. if (headerLine) {
15. headerLine = false;
16. continue;
17. }
18. lineNum++;
20. // Split the line by comma and remove whitespace
21. const [
22. game_id,
23. game_date,
24. player_id,
25. player_full_name,
26. player_team_id,
27. player_team_name,
28. home_team,
29. opponent_team_id,
30. opponent_team_name,
31. points,
32. rebounds,
33. assists,
34. steals,
35. blocks,
36. fg_percentage,
37. minutes_played,
38. ] = line.split(',');
40. // Create a document object
41. const document = {
42. game_id: parseInt(game_id),
43. game_date: game_date.trim(),
44. player_id: parseInt(player_id),
45. player_full_name: player_full_name.trim(),
46. player_team_id: parseInt(player_team_id),
47. player_team_name: player_team_name.trim(),
48. home_team: home_team.trim() === 'True', // Converts True/False into a boolean
49. opponent_team_id: parseInt(opponent_team_id),
50. opponent_team_name: opponent_team_name.trim(),
51. points: parseFloat(points),
52. rebounds: parseFloat(rebounds),
53. assists: parseFloat(assists),
54. steals: parseFloat(steals),
55. blocks: parseFloat(blocks),
56. fg_percentage: parseFloat(fg_percentage),
57. minutes_played: parseFloat(minutes_played),
58. };
60. // Prepare the bulk operation format
61. bulkBody.push({ index: { _index: indexName } });
62. bulkBody.push(document);
63. }
65. console.log(`Parsed ${lineNum} lines from CSV`);
``AI写代码
5）然后，我们可以使用 Elasticsearch 的 Bulk API，通过 elasticClient.bulk() 在一次请求中导入多条文档。下面的错误处理逻辑会统计有多少文档导入失败，以及有多少成功。
``
1. try {
2. // Perform the bulk request
3. const response = await elasticClient.bulk({ body: bulkBody });
5. if (response.errors) {
6. console.log('Bulk Ingestion had some hiccups:');
8. // Count successful vs failed operations
9. let successCount = 0;
10. let errorCount = 0;
11. const errorDetails = [];
13. response.items.forEach((item, index) => {
14. const operation = item.index || item.create || item.update || item.delete;
15. if (operation.error) {
16. errorCount++;
17. errorDetails.push({
18. document: index + 1,
19. error: operation.error,
20. });
21. } else {
22. successCount++;
23. }
24. });
26. console.log(`Successfully indexed: ${successCount} documents`);
27. console.log(`Failed to index: ${errorCount} documents, here are the details`, errorDetails);
29. } else {
30. console.log(`Bulk Ingestion fully successful!`);
31. }
33. } catch (error) {
34. console.error('Error performing bulk ingestion:', error);
35. }
36. }
``AI写代码
6）运行下面的 main() 函数，依次执行 createIndex() 和 bulkIngestCsv() 两个函数。
`
1. // Run this function
2. async function main() {
3. const result = await createIndex();
4. if (!result) {
5. console.error('Index setup failed. Aborting.');
6. return;
7. }
9. await bulkIngestCsv(filePath);
10. console.log('Bulk ingestion completed!');
11. }
13. main();
`AI写代码
如果你看到控制台日志显示批量导入成功，可以快速检查一下 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 助手能获得准确的数据。
`
1. export async function getHistoricalAveragesAgainstOpponent(player_id, opponent_team_id) {
2. try {
3. //Query for Historical Averages
4. const historicalQuery = await elasticClient.search({
5. index: 'sample-nba-player-data',
6. size: 0,
7. query: {
8. bool: {
9. must: [
10. {
11. term: {
12. player_id: {
13. value: player_id,
14. },
15. },
16. },
17. {
18. term: {
19. opponent_team_id: {
20. value: opponent_team_id,
21. },
22. },
23. },
24. ],
25. },
26. },
27. aggs: {
28. avg_points: { avg: { field: 'points' } },
29. avg_rebounds: { avg: { field: 'rebounds' } },
30. avg_assists: { avg: { field: 'assists' } },
31. avg_steals: { avg: { field: 'steals' } },
32. avg_blocks: { avg: { field: 'blocks' } },
33. avg_fg_percentage: { avg: { field: 'fg_percentage' } },
34. },
35. });
37. return {
38. points: historicalQuery.aggregations.avg_points.value || 0,
39. rebounds: historicalQuery.aggregations.avg_rebounds.value || 0,
40. assists: historicalQuery.aggregations.avg_assists.value || 0,
41. steals: historicalQuery.aggregations.avg_steals.value || 0,
42. blocks: historicalQuery.aggregations.avg_blocks.value || 0,
43. fgPercentage: historicalQuery.aggregations.avg_fg_percentage.value || 0,
44. };
45. } catch (error) {
46. console.error('Query error from getHistoricalAveragesAgainstOpponent function:', error);
47. return { error: 'Queries failed in getting historical averages against opponent.' };
48. }
49. }
`AI写代码
3）要计算某球员对特定对手的赛季平均数据，我们使用与历史平均几乎相同的查询。唯一的区别是 bool 过滤器中增加了对 game_date 的条件，game_date 必须在当前 NBA 赛季范围内，这里是 2024-10-01 到 2025-06-30。这个额外条件确保后续的聚合只统计本赛季的比赛数据。
`1. {
2. range: {
3. //Range for this season, change to match current season
4. game_date: {
5. gte: '2024-10-01',
6. lte: '2025-06-30',
7. },
8. },`AI写代码
第 6 步：球员比较工具
为了保持代码的模块化和易维护性，我们将创建一个工具文件，整合元数据辅助函数和 Elasticsearch 聚合逻辑。这将支持代理使用的主要工具。稍后会详细介绍：
1）在 backend/lib 目录下新建一个文件 comparePlayers.js。
2）添加以下函数，将元数据辅助和 Elasticsearch 聚合逻辑整合到一个函数中，支持代理使用的主要工具。
`
1. import { playersByName } from '../data/playerAndTeamInfo.js';
2. import { teamsByName } from '../data/playerAndTeamInfo.js';
3. import { upcomingMatchups } from '../data/playerAndTeamInfo.js';
4. import { getHistoricalAveragesAgainstOpponent } from './elasticAggs.js';
5. import { getSeasonAveragesAgainstOpponent } from './elasticAggs.js';
7. //Simple helper functions to simulate API calls for player and team metadata. These reference the hardcoded values from playerAndTeamInfo.js in the data directory
8. export function getPlayerInfo(playerFullName) {
9. return playersByName[playerFullName];
10. }
12. export function getTeamID(teamFullName) {
13. return teamsByName[teamFullName];
14. }
16. export function getUpcomingMatchups(teamId) {
17. return upcomingMatchups[teamId];
18. }
20. //Main function used by the 'playerComparisonTool' agent tool
21. export async function comparePlayersForNextMatchup(player1Name, player2Name) {
22. //Get Player Info
23. const player1Info = getPlayerInfo(player1Name);
24. const player2Info = getPlayerInfo(player2Name);
26. //Get upcoming matchups
27. const player1NextGame = getUpcomingMatchups(player1Info.team_id)[0];
28. const player2NextGame = getUpcomingMatchups(player2Info.team_id)[0];
30. //Get season and historical averages against next opponent for player 1
31. const player1SeasonAverages = await getSeasonAveragesAgainstOpponent(
32. player1Info.player_id,
33. player1NextGame.opponent_team_id
34. );
35. const player1HistoricalAverages = await getHistoricalAveragesAgainstOpponent(
36. player1Info.player_id,
37. player1NextGame.opponent_team_id
38. );
40. //Get season and historical averages against next opponent for player 2
41. const player2SeasonAverages = await getSeasonAveragesAgainstOpponent(
42. player2Info.player_id,
43. player2NextGame.opponent_team_id
44. );
45. const player2HistoricalAverages = await getHistoricalAveragesAgainstOpponent(
46. player2Info.player_id,
47. player2NextGame.opponent_team_id
48. );
50. const player1 = {
51. name: player1Name,
52. playerId: player1Info.player_id,
53. teamId: player1Info.team_id,
54. nextOpponent: {
55. teamId: player1NextGame.opponent_team_id,
56. teamName: player1NextGame.opponent_team_name,
57. home: player1NextGame.home,
58. },
59. stats: {
60. seasonAverages: player1SeasonAverages,
61. historicalAverages: player1HistoricalAverages,
62. },
63. };
65. const player2 = {
66. name: player2Name,
67. playerId: player2Info.player_id,
68. teamId: player2Info.team_id,
69. nextOpponent: {
70. teamId: player2NextGame.opponent_team_id,
71. teamName: player2NextGame.opponent_team_name,
72. home: player2NextGame.home,
73. },
74. stats: {
75. seasonAverages: player2SeasonAverages,
76. historicalAverages: player2HistoricalAverages,
77. },
78. };
80. return [player1, player2];
81. }
`AI写代码
第 7 步：构建代理
现在你已经搭建了前后端框架，导入了 NBA 比赛数据，并建立了与 Elasticsearch 的连接，我们可以开始把各部分组合起来，构建代理。
定义代理
进入 backend/src/mastra/agents 目录下的 index.ts 文件，添加代理定义。你可以指定以下字段：
-
名称：给代理起个名字，前端调用时会用到这个名字。
-
说明/系统提示词：系统提示词为 LLM 提供初始上下文和交互规则，类似于用户通过聊天框发送的提示，但这是在任何用户输入前给出的。根据所用模型不同，这会有所变化。
-
模型：选择使用的 LLM（Mastra 支持 OpenAI、Anthropic、本地模型等）。
-
工具：代理可以调用的工具函数列表。
-
记忆：（可选）是否让代理记住对话历史等。为简单起见，可以先不启用持久化记忆，但 Mastra 支持该功能。
``
1. import { openai } from '@ai-sdk/openai';
2. import { Agent } from '@mastra/core/agent';
3. import { playerComparisonTool } from '../tools';
5. export const basketballAgent = new Agent({
6. name: 'Basketball Agent',
7. instructions: `
8. You are a NBA Basketball expert.
9. Your primary function is to compare two NBA players and recommend which one is the better fantasy pickup.
11. Only compare players from the following list:
12. - LeBron James
13. - Stephen Curry
14. - Jayson Tatum
15. - Jaylen Brown
16. - Nikola Jokic
17. - Luka Doncic
18. - Kyrie Irving
19. - Anthony Davis
20. - Kawhi Leonard
21. - Russell Westbrook
23. Input Handling Rules:
24. - If the user asks about a player that is not on this list, respond with the list of available players for comparison.
25. - If the user only inputs one player, ask the user to add another player from the list provided.
26. - If the user inputs a player with the wrong spelling or capitalizations, infer from the list of available players provided.
27. - 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.
29. Tool Usage:
30. - Extract and standardize player names to match the list exactly.
31. - Use the playerComparisonTool, passing both names as strings.
32. - The tool will return an object with game information, stats, and analysis.
34. Format your response using Markdown syntax. Use:
36. Example output format:
39. #### Next Game Info
40. - ***LeBron James** vs Warriors, May 24 (Home)
41. - ***Stephen Curry** vs Lakers, May 24 (Away)
44. #### Stats Comparison
45. \`\`\`
46. Stat LeBron James (vs Warriors) Stephen Curry (vs Lakers)
47. -------------------- ----------------------------- ----------------------------
48. Historical Points 28.3 30.3
49. Historical Assists 6.7 8.7
50. Season Points 28.8 23.3
51. Season Assists 6.2 4.7
52. \`\`\`
54. #### Fantasy Recommendation
55. Explain which player is the better fantasy pickup and why.
57. `,
58. model: openai('gpt-4o'),
59. tools: { playerComparisonTool },
60. });
``AI写代码
定义工具
1）进入 backend/src/mastra/tools 目录下的 index.ts 文件。
2）使用以下命令安装 Zod：
`npm install zod`AI写代码
3）添加工具定义。注意，我们导入了 comparePlayers.js 文件中的函数，作为代理调用该工具时使用的主要函数。使用 Mastra 的 createTool() 函数，我们将注册 playerComparisonTool。字段包括：
-
id：用自然语言描述工具功能，帮助代理理解工具作用。
-
input schema：定义工具输入的数据结构，Mastra 使用 Zod schema（一个 TypeScript 的 schema 验证库）。Zod 确保代理传入的输入结构正确，如果输入结构不匹配，工具将不会执行。
-
description：用自然语言描述，帮助代理理解何时调用和使用该工具。
-
execute：工具被调用时执行的逻辑。在这里，我们使用导入的辅助函数来返回球员表现统计数据。
`
1. import { comparePlayersForNextMatchup } from '../../../lib/comparePlayers.js'
2. import { createTool } from "@mastra/core/tools";
3. import { z } from "zod";
5. export const playerComparisonTool = createTool({
6. id: "Compare two NBA players",
7. inputSchema: z.object({
8. player1:z.string(),
9. player2:z.string()
10. }),
11. description: "Use this tool to compare two players given in the user prompt.",
12. execute: async ({ context: { player1, player2 } }) => {
13. return await comparePlayersForNextMatchup(player1, player2);
14. },
15. })
`AI写代码
添加处理中间件以支持 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"]
允许请求中使用的自定义头部字段
`
1. import { Mastra } from '@mastra/core/mastra';
2. import { basketballAgent } from './agents';
4. console.log('Starting Mastra server...');
6. export const mastra = new Mastra({
7. agents: { basketballAgent },
8. server:{
9. timeout: 10 * 60 * 1000, // 10 minutes
10. cors: {
11. origin: ['http://localhost:5173'],
12. allowMethods: ["GET", "POST"],
13. allowHeaders: [
14. "Content-Type",
15. "Authorization",
16. "x-mastra-client-type",
17. "x-highlight-request",
18. "traceparent",
19. ],
20. exposeHeaders: ["Content-Length", "X-Requested-With"],
21. credentials: false,
22. },
23. },
25. });
27. console.log('Mastra server configured.'); // Log after server configuration
`AI写代码
第 8 步：集成前端
这个 React 组件提供了一个简单的聊天界面，使用 @ai-sdk/react 中的 [useChat()](https://mastra.ai/en/docs/frameworks/ai-sdk "useChat()") hook 连接到 Mastra AI 代理。我们还会用这个 hook 显示 token 使用情况、工具调用，并渲染对话内容。在系统提示词中，我们要求代理以 markdown 格式输出响应，所以会使用 react-markdown 来正确格式化响应。
- 在 frontend 目录下，安装 @ai-sdk/react 包以使用
useChat()hook。
`npm install @ai-sdk/react`AI写代码
2）在同一目录下，安装 React Markdown，以便我们能够正确格式化代理生成的响应内容。
`npm install react-markdown`AI写代码
3）实现 useChat()。这个 hook 将管理前端与 AI 代理后端之间的交互。它负责处理消息状态、用户输入、交互状态，并提供生命周期钩子用于可观测性。我们传入的选项包括：
-
api：定义 Mastra AI 代理的接口地址。默认使用 4111 端口，并添加支持流式响应的路由。 -
onToolCall：每当代理调用某个工具时执行；我们用它来追踪代理调用了哪些工具。 -
onFinish：代理完整响应完成后执行。尽管启用了流式响应，onFinish仍会在完整消息接收后执行，而不是每个 chunk 后执行。我们在这里用它来统计 token 使用量，这对监控 LLM 成本和优化非常有帮助。
4）最后，进入 frontend/components 目录下的 [ChatUI.jsx](https://github.com/jdarmada/nba-ai-assistant-js/blob/main/frontend/components/ChatUI.jsx "ChatUI.jsx") 组件，创建用于显示对话的界面。然后使用 ReactMarkdown 组件包裹响应内容，以便正确格式化代理的 markdown 响应。
`
1. import React, { useState } from 'react';
2. import { useChat } from '@ai-sdk/react';
3. import ReactMarkdown from 'react-markdown';
5. export default function ChatUI() {
6. const [totalTokenUsage, setTotalTokenUsage] = useState(0);
7. const [promptTokenUsage, setPromptTokenUsage] = useState(0);
8. const [completionTokenUsage, setCompletionTokenUsage] = useState(0);
9. const [toolsCalled, setToolsCalled] = useState([]);
11. const { messages, input, handleInputChange, handleSubmit, status } = useChat({
12. api: 'http://localhost:4111/api/agents/basketballAgent/stream', //Replace with your own endpoint for your agent
13. id: 'my-chat-session',
15. //Optional parameter to check agent tool calls
16. onToolCall: ({ toolCall }) => {
17. setToolsCalled((prev) => [...prev, toolCall.toolName]);
18. },
20. //Optional parameter to check token usages
21. onFinish: (message, { usage }) => {
22. setTotalTokenUsage((prev) => prev + usage.totalTokens);
23. setPromptTokenUsage((prev) => prev + usage.promptTokens);
24. setCompletionTokenUsage((prev) => prev + usage.completionTokens);
25. },
27. //Optional parameter for error handling
28. onError: (error) => {
29. console.error('Agent error:', error);
30. },
31. });
33. return (
34. <div>
35. <div class>
36. <h4 class>What's My Agent Doing?</h4>
38. <div class>
39. <strong class>Tools Called:</strong>
40. <ul class>
41. {toolsCalled.map((tool, idx) => (
42. <li key={idx}>{tool}</li>
43. ))}
44. {toolsCalled.length === 0 && <li>No tools called yet.</li>}
45. </ul>
47. <div class>
48. <p>Prompt Token Usage: {promptTokenUsage}</p>
49. <p>Completion Token Usage: {completionTokenUsage}</p>
50. <p>Total Token Usage: {totalTokenUsage}</p>
51. </div>
52. </div>
53. </div>
55. <strong>Conversation:</strong>
56. <div class>
57. {messages.map((msg) => (
58. <div key={msg.id} class>
59. <strong class>{msg.role === 'assistant' ? 'Basketbot' : 'You'}:</strong>
60. <ReactMarkdown>{msg.content}</ReactMarkdown>
61. </div>
62. ))}
63. </div>
65. <form onSubmit={handleSubmit}>
66. <input
67. type="text"
68. value={input}
69. onChange={handleInputChange}
70. placeholder="Input two players you want to compare."
71. class
72. />
73. <button type="submit" disabled={status === 'streaming'}>
74. {status === 'streaming' ? 'Thinking...' : 'Send'}
75. </button>
76. </form>
77. </div>
78. );
79. }
`AI写代码
第 9 步：运行应用程序
恭喜！现在你已经可以运行整个应用程序了。按照以下步骤同时启动后端和前端：
1）在终端窗口中，从项目根目录开始，进入 backend 目录并启动 Mastra 服务器：
`
1. cd backend
3. npm run dev
`AI写代码
2）在另一个终端窗口中，从项目根目录开始，进入 frontend 目录并启动 React 应用：
`
1. cd frontend
3. npm run dev
`AI写代码
3）打开浏览器，访问：
你应该能看到聊天界面。试试以下示例提示：
- "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 服务器和当前生态的内容。
这些改进正在进行中，敬请期待！
总结
在这篇博客中，我们用 JavaScript、Mastra 和 Elasticsearch 构建了一个 agentic RAG 助手，为你的 fantasy 篮球队提供个性化推荐。我们介绍了：
-
Agentic RAG 的基本原理，以及如何将 AI 代理的自主性与 RAG 工具结合，从而实现更细致、更动态的智能助手；
-
Elasticsearch 的数据存储能力和强大的原生聚合功能，使其成为 LLM 知识库的理想搭档；
-
Mastra 框架，以及它如何简化 JavaScript 生态中开发 AI 代理的流程。
无论你是篮球迷、AI 代理开发者，还是两者兼具，希望这篇博客能为你提供一些构建起点。完整代码仓库已上传至 GitHub，欢迎克隆和自由探索。
现在，去赢下你那场 fantasy 联赛吧！
原文：Building an agentic RAG assistant with JavaScript, Mastra and Elasticsearch - Elasticsearch Labs
