3.2 AI Agent逻辑:自然语言请求解读与任务规划
一个真正的 "AI Agent" 不仅仅是“问答机器”,它需要能够理解用户的意图,将复杂请求拆解为可执行的子任务,并逐步完成。本节我们将实战构建一个具备 ReAct (Reasoning and Acting) 能力的数据分析 Agent。
1. 意图识别 (Intent Recognition) 与 ReAct 模式
当用户输入:“帮我分析一下刚才上传的订单数据,计算出总销售额,并告诉我哪个订单金额最大”时,Agent 不能只是盲目回答,它需要:
- 思考 (Thought):我需要先计算总销售额,然后再找出最大金额的订单。
- 行动 (Action):调用具体的工具/函数来执行计算。
- 观察 (Observation):获取计算结果。
- 总结 (Final Answer):将结果转化为人类易读的自然语言。
这就是 ReAct (Reasoning and Acting) 模式的核心思想。
2. 实战:在 Nest.js 中实现 Agent 循环与工具调用
我们将对上一节中的 AnalysisService 进行深度升级,让它具备使用工具(Tools)的能力,并实现一个完整的 Agent 循环。
2.1 定义系统提示词与工具集 (Prompt Engineering)
首先,在 src/analysis/analysis.service.ts 中,我们需要设计一个强大的系统提示词,告诉 AI 它拥有哪些工具可以使用。
// ai-data-analyzer/backend/src/analysis/analysis.service.ts (新增或修改)
const AGENT_SYSTEM_PROMPT = `
你是一个专业的数据分析 AI Agent。请根据用户的请求和提供的数据,逐步进行分析。
你可以使用以下工具(Tools)来辅助你的分析:
1. [calculate_total]: 计算指定列的总和。参数格式: {"column": "金额列名"}
2. [find_max]: 找出指定列的最大值及对应行。参数格式: {"column": "金额列名"}
【执行规范】
你必须按照以下格式进行思考和行动:
Thought: 我需要做什么。
Action: 工具名称 (如果不需要工具,请填写 NONE)
Action Input: 工具的 JSON 参数 (如果没有,请填写 {})
--- (等待系统返回 Observation) ---
如果你已经得到了最终结论,请按照以下格式输出:
Thought: 我已经得出结论。
Final Answer: 你的最终自然语言回复。
`;
2.2 实现本地工具执行器 (Tool Executor)
接下来,我们在 AnalysisService 中实现大模型想要调用的具体方法。这些是真正执行数据处理逻辑的本地代码。为了满足 NestJS 严格的 TypeScript 检查(特别是 no-unsafe-assignment 和 no-unsafe-member-access),我们对变量进行了安全的类型转换。
// ai-data-analyzer/backend/src/analysis/analysis.service.ts (继续补充)
/**
* 工具执行器:根据 AI 的指令执行对应的本地代码
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
private executeTool(action: string, actionInput: string, data: any[]): string {
try {
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const input = JSON.parse(actionInput);
switch (action.trim()) {
case 'calculate_total': {
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
const colName = input.column as string;
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const total = data.reduce(
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return
(sum, row) => sum + (Number(row[colName]) || 0),
0,
);
return `列 [${colName}] 的总和为: ${total}`;
}
case 'find_max': {
if (data.length === 0) return '数据为空';
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
const colName = input.column as string;
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const maxRow = data.reduce((max, row) =>
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return
(Number(row[colName]) || 0) > (Number(max[colName]) || 0) ? row : max
);
return `列 [${colName}] 的最大值为: ${maxRow[colName]},完整行数据: ${JSON.stringify(maxRow)}`;
}
case 'NONE':
return '无需调用工具';
default:
return `未知的工具: ${action}`;
}
} catch (error) {
const err = error as Error;
return `工具执行失败: ${err.message}`;
}
}
2.3 实现 Agent 核心循环 (The Agent Loop)
这是最核心的部分。我们需要一个 while 循环,不断地把“用户请求 + 当前数据 + 历史执行记录”发给 OpenAI,然后解析它的回复。如果它决定调用工具,我们就执行本地代码,并将“观察结果 (Observation)”追加到上下文中,再次发给 OpenAI。
// ai-data-analyzer/backend/src/analysis/analysis.service.ts (继续补充)
/**
* Agent 核心循环
* @param rawData 解析后的结构化数据 (例如 CSV rows)
* @param userPrompt 用户的自然语言请求
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
async runAgentLoop(rawData: any[], userPrompt: string): Promise<string> {
// 为了节省 Token,如果数据量适中,我们可以将其转为 Markdown 表格作为上下文
const dataContext = this.preprocessPayload(rawData);
// 初始化对话上下文
let conversationHistory = `
${AGENT_SYSTEM_PROMPT}
【当前数据片段】
${dataContext}
【用户请求】
${userPrompt}
`;
const MAX_ITERATIONS = 5; // 防止死循环
let iterations = 0;
while (iterations < MAX_ITERATIONS) {
iterations++;
this.logger.debug(`Agent Iteration ${iterations}...`);
// 1. 调用大模型
const aiResponse = await this.openAIService.chat(conversationHistory);
this.logger.debug(`AI Response:\n${aiResponse}`);
conversationHistory += `\n${aiResponse}\n`; // 记录 AI 的回复
// 2. 解析 AI 的意图:是否得出了最终结论?
if (aiResponse.includes('Final Answer:')) {
const finalAnswer = aiResponse.split('Final Answer:')[1].trim();
return finalAnswer;
}
// 3. 解析 AI 的意图:是否需要调用工具?
const actionMatch = aiResponse.match(/Action:\s*(.+)/);
const inputMatch = aiResponse.match(/Action Input:\s*(.+)/);
if (actionMatch && inputMatch) {
const action = actionMatch[1].trim();
const actionInput = inputMatch[1].trim();
if (action !== 'NONE') {
this.logger.debug(`Executing Tool: ${action} with input: ${actionInput}`);
// 4. 执行本地工具
const observation = this.executeTool(action, actionInput, rawData);
// 5. 将观察结果追加到上下文中,进入下一次循环
const observationLog = `Observation: ${observation}`;
conversationHistory += `${observationLog}\n`;
this.logger.debug(observationLog);
}
} else {
// 容错处理:AI 没有按格式输出
conversationHistory += `Observation: 请严格按照 Thought / Action / Action Input / Final Answer 的格式输出。\n`;
}
}
return "Agent 执行达到了最大迭代次数,未能得出最终结论。";
}
3. 联调测试
为了能够直接测试我们刚才写的 Agent 代码,我们需要对 DataController 进行增强,使其在接收到上传的 CSV 文件和用户的 Prompt 后,直接触发 Agent 分析。
3.1 改造 DataController 触发 Agent 分析
首先,修改 src/data/data.controller.ts,增加接收 prompt 的逻辑,并调用 AnalysisService:
// ai-data-analyzer/backend/src/data/data.controller.ts (修改 uploadCsv 方法)
import {
Controller,
Post,
UseInterceptors,
UploadedFile,
BadRequestException,
Body,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { parse } from 'fast-csv';
import * as multer from 'multer';
import { AnalysisService } from '../analysis/analysis.service';
@Controller('data')
export class DataController {
constructor(private readonly analysisService: AnalysisService) {}
@Post('upload/csv')
@UseInterceptors(
FileInterceptor('file', {
storage: multer.memoryStorage(),
limits: { fileSize: 10 * 1024 * 1024 }, // 限制 10MB
}),
)
async uploadCsv(
@UploadedFile() file: Express.Multer.File,
@Body('prompt') prompt?: string,
) {
if (!file) {
throw new BadRequestException('请上传 CSV 文件');
}
const rows: Record<string, string>[] = [];
// 使用 fast-csv 流式解析内存中的 buffer
await new Promise<void>((resolve, reject) => {
const stream = parse({ headers: true, ignoreEmpty: true })
.on('error', (error: Error) =>
reject(new BadRequestException(`CSV 解析失败: ${error.message}`)),
)
.on('data', (row: Record<string, string>) => rows.push(row))
.on('end', () => resolve());
stream.write(file.buffer);
stream.end();
});
// 如果用户传了 prompt 参数,就调用 Agent 进行分析
if (prompt) {
const agentResult = await this.analysisService.runAgentLoop(rows, prompt);
return {
message: 'Agent 分析完成',
rowCount: rows.length,
prompt,
agentResult,
};
}
return {
message: '文件解析成功',
rowCount: rows.length,
preview: rows.slice(0, 3),
};
}
}
注意:为了让 DataController 能正常注入 AnalysisService,你需要在 AnalysisModule 中将 AnalysisService 导出 (exports: [AnalysisService]),并在 DataModule 中导入 AnalysisModule。
3.2 运行测试步骤
确保你的 NestJS 后端服务正在运行 (pnpm start:dev)。我们将使用终端的 cURL 来模拟客户端上传文件并提出分析请求。
第一步:准备测试数据 确保项目根目录下有 test-data.csv 文件,或者使用我们之前准备好的测试数据。
第二步:执行 cURL 请求 打开一个新的终端窗口,在 ai-data-analyzer/backend 目录下执行以下命令:
curl -X POST http://localhost:3001/data/upload/csv \
-F "file=@test-data.csv" \
-F "prompt=帮我计算一下 amount 列的总和,并找出金额最大的一笔订单。"
(注意:请根据你本地服务的实际端口调整 URL 中的端口号,比如可能是 3001。-F "file=@test-data.csv" 使用的是相对路径,确保终端当前所处目录正确,否则请使用绝对路径。)
预期的返回结果: 你会看到类似如下的完美 JSON 响应:
{
"message": "Agent 分析完成",
"rowCount": 8,
"prompt": "帮我计算一下 amount 列的总和,并找出金额最大的一笔订单。",
"agentResult": "amount 列的总和为 2281.98 元;金额最大的一笔订单是订单F(id=6),金额为 999.99 元,日期为 2024-03-04,当前状态为“退款中”。"
}
3.3 执行过程模拟还原 (控制台日志)
当你发出上述请求时,切回到运行着 NestJS 后端服务的那一个终端,你会清晰地看到 Agent 的“心理活动”。 提示:为了看到详细的日志,确保 main.ts 中 NestFactory.create 时启用了 debug 日志级别:const app = await NestFactory.create(AppModule, { logger: ['log', 'error', 'warn', 'debug', 'verbose'] }); 并在 OpenAIService 及 AnalysisService 中添加了适当的 this.logger.debug()。
- AI 第一次回复:
Thought: 用户需要计算 amount 的总和和最大值。我先计算总和。Action: calculate_totalAction Input: {"column": "amount"} - 系统拦截并执行工具,追加上下文:
Observation: 列 [amount] 的总和为: 2281.98 - AI 第二次回复:
Thought: 我已经得到了总和。接下来我要找出 amount 的最大值。Action: find_maxAction Input: {"column": "amount"} - 系统再次拦截执行:
Observation: 列 [amount] 的最大值为: 999.99,完整行数据: {"id":"6","name":"订单F","amount":"999.99","date":"2024-03-04","status":"退款中"} - AI 第三次回复(最终结论):
Thought: 我已经获取了所有需要的数据,可以回答用户了。Final Answer: amount 列的总和为 2281.98 元;金额最大的一笔订单是订单F(id=6),金额为 999.99 元,日期为 2024-03-04,当前状态为“退款中”。
通过这种模式,我们成功地将大模型的逻辑推理能力与后端系统的精确计算能力结合在了一起,避免了 AI 算错数的“幻觉”问题,构建了一个真正意义上的智能数据分析 Agent!
在下一节中,我们将探讨如何集成更多外部模型,甚至在本地运行模型来提升安全性和响应速度。
