构建一个能说会做的智能体

基于 MCP 的 AI Agent 智能体系统设计与实现

一、项目基本信息

项目	内容
所属课程	课程连接
作业要求	作业要求
项目目标	基于 MCP 的 AI Agent 智能体系统设计与实现
项目类型	基于大语言模型与MCP的只能体应用
项目源码	GitHub仓库
项目开发语言	后端是python、前端是html和pythpn
项目主要模块	前端、后端、测试
项目目标	实现自然语言交互与工具调用相结合的智能体系
小组成员	郑乐冰3224004234、钟楚楠3224004271、苏拉娅·斯地克阿吉3224004384、黄泽欣3224004268、艾柯代·吐尔逊3224004266、王昊圆3224004232、李宇晴3224004230、陈嫒琳 3224004228

二、项目背景与目标

2.1 项目背景
随着人工智能技术的不断发展，大语言模型已经具备了较强的自然语言理解、文本生成和任务分析能力。但是，单纯依靠大语言模型进行对话，仍然存在一定的局限性。例如，当用户需要完成具体操作、查询外部数据或执行某项任务时，仅仅生成文字回复并不能完全满足实际需求。
因此，我们小组选择以 AI Agent 为项目方向，尝试将大语言模型的自然语言理解能力与外部工具的实际执行能力相结合，设计并实现一个能够理解用户需求、根据任务需要调用工具，并将执行结果反馈给用户的智能体系统。
本项目采用 Python 与 MCP（Model Context Protocol，模型上下文协议）相关技术进行开发。MCP 为智能体与外部工具之间的交互提供了统一的连接方式，使模型能够根据用户提出的任务，选择适当的工具完成相应操作。
在本次软件工程课程实践中，我们小组完成了前端界面、后端逻辑和测试等工作，并在此基础上整理项目文档，记录系统的需求分析、业务流程、实现思路和测试情况。

2.2 项目目标
本项目的主要目标包括以下几个方面：

• 实现自然语言交互。 用户能够通过自然语言表达自己的需求，降低使用系统的操作门槛。

• 实现智能体任务处理。 系统能够结合用户输入分析任务，并根据任务需要进行后续处理。

• 实现工具调用能力。 通过 MCP 等机制连接智能体与外部工具，使系统不仅能够生成文字，还能够在适当情况下执行具体操作。

• 实现前后端协同。 前端负责用户交互和结果展示，后端负责接口调用、任务编排以及相关业务处理。

• 开展系统测试。 对智能体的基本功能进行测试，发现问题后及时反馈给开发成员，并在修复后进行验证。

• 形成完整项目文档。 通过编写博客和 Agent 说明文档，总结项目的需求、业务流程、实现方法、使用方式及团队协作经验。

三、小组分工

分工	姓名、学号	负责模块	主要内容
分工1	陈嫒琳3224004228、郑乐冰3224004234	前端	负责智能体前端用户界面的设计与实现，完成基本 UI 布局和用户交互功能，并配合后端完成前后端联调
分工2	钟楚楠3224004271、李宇晴3224004230	后端	负责后端接口的开发与调用、业务逻辑处理和任务编排，协调智能体相关功能的运行，并配合前端完成接口联调。
分工3	苏拉娅·斯地克阿吉3224004384、黄泽欣3224004268	测试	根据课程作业要求制定并执行测试，对智能体的基本功能进行验证；发现问题后及时反馈给前端或后端成员，协助完成问题修复后的复测，并在功能验证通过后录制系统使用示例视频。
分工4	艾柯代·吐尔逊3224004266、王昊圆 3224004232	撰写博客	根据课程作业要求编写项目博客及 Agent 说明文档，整理项目需求描述、业务流程、实现说明和使用示例，并汇总 GitHub 仓库链接、小组分工及成员心得等内容。

四、需求分析
4.1 功能需求

结合本项目的设计目标，系统的功能需求主要包括以下几个方面。

（1）用户交互需求

系统需要提供用户能够使用的交互界面，使用户可以输入自然语言指令，并查看智能体返回的处理结果。界面应尽量保持简洁，降低用户的学习成本。

（2）任务理解与处理需求

系统需要接收用户输入的任务内容，并通过后端相关逻辑完成任务处理。对于需要调用模型或外部工具的任务，应能够按照相应流程进行处理。

（3）工具调用需求

当任务需要外部工具提供支持时，智能体应能够根据任务内容选择相应工具，并按照工具接口的要求传递参数。工具执行完成后，系统需要获取执行结果，并将其反馈给用户。

（4）前后端协同需求

前端与后端需要通过约定的接口进行数据交互。前端负责接收用户输入和展示处理结果，后端负责接口调用、任务编排以及与智能体相关的处理逻辑，保证系统各模块能够协同工作。

（5）异常处理需求

当接口调用失败、工具执行异常或输入参数不符合要求时，系统应尽可能提供明确的错误反馈，方便用户了解问题，也便于开发和测试成员定位、修复问题。

（6）测试与验证需求

系统开发完成后，需要对基本功能进行测试，检查用户输入、任务处理、工具调用和结果返回等环节是否符合预期。对于测试中发现的问题，应及时反馈给对应的开发成员，并在修复后重新验证。

4.2 非功能需求

• 除基本功能外，系统还需要考虑以下非功能需求：

• 可用性： 界面布局清晰，主要操作流程易于理解。

• 可维护性： 前端、后端和测试代码尽量保持清晰的模块划分，便于后续修改。

• 可靠性： 对常见异常进行合理处理，减少错误对正常使用流程的影响。

• 可扩展性： 在现有架构基础上，为后续增加工具或扩展智能体能力预留空间。

• 可测试性： 通过相应的测试用例验证系统功能，为问题定位和功能改进提供依据。

五、项目业务流程
本项目的基本业务流程可以概括为以下几个阶段：

• 用户输入： 用户通过前端界面输入自然语言指令。

• 请求传递： 前端将用户请求传递给后端进行处理。

• 任务分析： 后端相关逻辑结合模型能力，对用户请求进行分析，判断任务的处理方式。

• 工具调用： 如果任务需要外部工具支持，智能体按照相应接口和流程发起工具调用。

• 结果处理： 后端接收工具执行结果，并结合任务处理逻辑整理返回内容。

• 结果展示： 前端接收后端返回的数据，并将处理结果展示给用户。

• 测试与反馈： 开发过程中通过测试验证功能是否正常；发现问题后反馈给对应成员，修复后再次测试。

通过上述流程，系统将用户交互、任务处理、工具执行和结果反馈连接起来，形成相对完整的智能体应用流程。

六、项目源码与目录说明
项目GitHub 公共仓库地址
目前仓库主要包含以下目录和文件：

目录或文件	主要作用
backend	存放后端相关代码，负责接口处理、业务逻辑及智能体任务编排等工作。
frontend/	存放前端相关代码，负责用户交互界面及相关展示功能。
tests/	存放项目测试相关代码，用于验证系统功能是否符合预期。
.gitignore	配置 Git 版本管理时需要忽略的文件和目录。
README.md	项目说明文档，介绍项目基本信息、需求、业务流程及运行方式等内容。
requirements.txt	记录 Python 项目所需的依赖包，便于配置运行环境。
workspace_data.db	SQLite 数据库文件，用于存储项目运行过程中涉及的数据；具体存储内容需要结合数据库结构进一步说明。

项目采用前端、后端和测试代码分开组织的方式，将不同职责的代码放置在相应目录中，便于小组成员进行分工开发、功能联调和测试验证。
其中，前端主要负责用户界面和交互，后端负责业务逻辑与接口处理，测试目录用于组织相关测试代码。根目录中的项目说明文件和依赖配置文件则为项目的开发、部署和使用提供必要的信息。
此外，项目根目录包含 SQLite 数据库文件 workspace_data.db，说明项目中涉及本地数据库的使用。后续可结合实际数据库表结构，进一步介绍数据存储方式及其在智能体功能中的作用。
七、系统总体设计与核心功能实现
7.1系统总体设计
本项目采用前后端分离的设计思路，结合大语言模型与 MCP 工具调用机制，实现用户交互、任务处理和工具执行等功能。系统主要由前端界面、后端接口、智能体处理逻辑和相关工具组成，各模块相互配合，完成从用户输入到结果返回的处理流程。

7.2核心功能特性

能力	说明
自然语言对话	通义千问 qwen-plus，支持 Markdown 回答
MCP 工具调用	根据用户任务自动选择合适的工具，包括本地文件读写、数学计算、图片分析和待办事项管理。
多轮对话记忆	服务端按 session_id 保存上下文，历史对话可切换
流式反馈	SSE 实时展示“思考 → 调工具 → 整理结果”的全过程
工具可视化	前端展示工具名称、参数、返回值，可展开/折叠
语音输入	浏览器 Web Speech API，中文语音转文字
语音朗读	自动朗读 / 单条朗读，可随时关闭
会话管理	新建、切换、删除会话，最近记录本地持久化
界面体验	深浅色主题、响应式布局、代码复制、消息复制

7.2.1自然语言交互
用户可以通过前端界面输入自然语言指令，系统接收请求并返回相应结果。

7.2.2智能体任务处理
智能体通过后端接口接收用户输入，并调用 run_agent_turn() 执行任务处理。处理完成后，接口将会话 ID、最终回复及工具调用记录返回前端，同时对异常情况进行处理。

7.2.3后端接口实现
本项目使用 FastAPI 构建后端接口，为前端提供智能体对话和相关功能支持。

（1）流式对话接口

该接口通过 POST 方法接收前端传入的用户消息和会话 ID，并调用 run_agent_turn() 函数执行智能体任务。任务处理完成后，接口返回会话 ID、最终回复和工具调用记录。当处理过程中出现异常时，接口会根据异常类型返回相应的 HTTP 错误信息。
7.2.4 MCP 工具服务端实现
本项目通过 backend/server.py 实现工具服务端，提供本地文件读写、数学计算、图片视觉识别和 SQLite 待办事项管理等功能。各工具分别封装为独立函数，并通过统一的工具注册表进行管理，便于智能体根据任务需求调用相应功能。

项目通过 analyze_image() 函数实现图片内容分析。该函数支持读取本地图片或使用图片 URL，并将图片数据与用户提出的问题一起发送给支持视觉理解的模型。模型根据图片内容生成分析结果，再由工具执行逻辑返回给智能体，最终形成面向用户的回答。通过该功能，智能体能够根据用户的问题对图片内容进行分析。
（2）待办事项管理

项目使用 SQLite 数据库存储待办事项，并通过 manage_todos() 函数实现待办事项的新增、完成、删除和查询。对于新增操作，系统会检查任务内容是否为空；对于完成和删除操作，则根据待办事项 ID 执行对应的数据库操作。通过数据库持久化存储，用户可以对待办事项进行管理。
（3）图片视觉识别

项目通过 analyze_image() 函数实现图片内容分析。该函数支持读取本地图片或使用图片 URL，并将图片数据与用户提出的问题一起发送给视觉模型，最后返回图片识别结果。当图片不存在或识别过程发生异常时，系统会返回相应的错误信息。
（4）本地文件读写：介绍读取文件、写入文件，以及限制写入项目根目录之外路径的处理。
（5）数学计算工具：介绍 simple_calculator() 如何计算表达式，以及如何限制不安全的表达式执行。
八、团队测试与结果展示
8.1 功能测试与演示

在完成前端界面、后端接口及智能体工具开发后，小组对项目的主要功能进行了联调与测试。通过实际运行系统，检查用户输入、智能体任务处理、工具调用及结果返回等环节是否正常。

测试视频：https://weixin.qq.com/sph/AhlwOETizZ（登录微信视频号观看）

视频展示了智能体的实际操作过程，包括用户输入、功能执行和结果反馈。通过完整的操作演示，可以直观地了解系统的主要功能及运行效果。
8.2 测试结果

根据实际测试过程，对智能体对话、工具调用、图片识别、待办事项管理及前后端接口交互等功能进行检查，并记录相应的测试结果。
通过功能测试与运行演示，对系统的主要功能进行验证，并为后续改进提供依据。
九、项目运行与使用说明
9.1 运行环境与依赖安装
本项目基于 Python 开发，使用 FastAPI 提供后端接口，通过通义千问大模型实现自然语言理解与任务处理，并结合本地工具完成相应操作。
在运行项目之前，需要安装项目所需的 Python 依赖。在项目根目录打开终端，执行以下命令：
pip install -r requirements.txt
9.2 项目启动方法
本项目提供了统一启动脚本，可以同时启动后端服务并打开浏览器。
在项目根目录执行：

python frontend/app.py

启动成功后，可以通过以下地址访问系统：

智能体网页： http://127.0.0.1:8000

后端接口文档： http://127.0.0.1:8000/docs
项目也支持单独启动后端 API 服务：
uvicorn backend.api:app --reload --port 8000
如果需要在命令行中体验智能体，也可以执行：

python -m backend.client
9.3 大模型配置

项目通过大模型接口实现自然语言理解和工具调用。根据项目配置，可以通过环境变量设置 API 密钥、接口地址和模型名称。

以 Windows PowerShell 为例：

实际使用时，需要将示例内容替换为自己的有效配置。为避免密钥泄露，不应将真实 API Key 上传到公开代码仓库。
9.4 智能体使用方法

项目启动后，用户可以通过网页界面输入自然语言指令，系统会根据任务需求决定是否调用相应工具，并将处理结果返回给用户。

主要使用场景包括：

• 数学计算： 输入“帮我计算 (1024 × 8 + 256) ÷ 16”，查看智能体调用计算工具并返回结果的过程。

• 文件读取与总结： 输入“读取 README.md 并总结项目内容”，查看智能体读取文件并根据文件内容生成总结的过程。

• 多轮对话： 连续提出相关问题，验证智能体能否结合同一会话的上下文进行回答。

• 语音交互： 在浏览器允许麦克风权限的情况下，使用语音输入功能；开启语音朗读后，可以听取智能体的回答。

• 会话管理： 使用左侧会话列表切换历史对话，并体验新建和删除会话等功能。

9.5 常见问题与注意事项

• 页面显示服务未连接： 检查后端是否已启动，并确认通过 http://127.0.0.1:8000 访问页面，而不是直接打开 index.html。

• 大模型调用失败： 检查 API Key、接口地址、模型名称及网络连接是否正确。

• 读取文件失败： 检查文件是否存在，并确认使用相对于项目根目录的正确路径。

• 语音功能无法使用： 检查浏览器兼容性及麦克风权限，建议使用 Chrome 或 Edge 浏览器。
  十、小组成员心得体会

陈媛琳 3224004228（前端）心得

在本次智能体项目小组作业中，我主要负责智能体前端用户界面的设计与实现，搭建页面基础布局，完成聊天交互组件、消息展示、输入发送等基础交互功能。在开发前期，我们先一起确定界面整体风格和交互逻辑，画出简单的页面草图，再逐步编码实现。开发过程里，我需要持续和后端同学沟通接口规范，对齐请求和返回的数据格式。在前后端联调阶段，遇到了消息异步渲染错乱、请求超时没有友好提示等问题，经过反复沟通、增加异常捕获和加载状态提示才一一解决。这次实践让我理解到，前端是用户和智能体交互的窗口，不只是简单的页面美化，更需要保证交互流程通顺、数据传递稳定。通过这次协作，我熟悉了 AI 项目的前端开发流程，积累了和后端协同对接接口的经验，也对 Agent 智能体的交互形态有了更加直观的认识。

郑乐冰 3224004234（前端）心得

我和陈媛琳同学搭档完成前端模块的开发，重点负责页面交互细节优化、样式调整，配合完成图片上传、结果回显等交互功能，同时参与前后端联调测试。在界面开发过程中，我更加关注用户使用感受，比如按钮反馈、消息区分样式、上传失败提示等细节。一开始页面交互比较生硬，很多边界场景没有考虑到位，后续结合测试同学反馈不断修改打磨。在和后端对接的时候，我学会看懂接口文档、调试请求参数，理解前端如何把用户的文字、图片请求传递给智能体服务，再把工具调用、模型返回的结果展示在页面上。这次小组合作让我体会到前后端协同开发的意义，一个完整可用的智能体，离不开稳定流畅的交互界面支撑，也为之后课程大作业的前端开发打下基础。

钟楚楠 3224004271（后端）心得

本次作业我负责后端接口开发、基础业务逻辑实现与智能体任务编排工作，搭建后端服务基础框架，封装接口，实现大模型的调用入口，支撑前端发来的对话请求。在正式开发之前，我对智能体的认知局限于调用大模型 API，实际开发之后才明白 Agent 的核心在于任务编排：智能体需要理解用户指令，判断是否调用外部工具、规划执行步骤。开发阶段我遇到不少难题，比如工具调用参数解析失败、多轮对话上下文维护困难，需要不断调整提示词、增加日志定位问题。在联调中，我和前端同学对齐接口入参、出参，保证请求能够正常流转。这次项目让我完整感受了 MCP 智能体后端的开发流程，理解了智能体 “能说会做” 背后的调度逻辑，提升了接口设计与问题排查的能力。

李宇晴 3224004230（后端）心得

我与钟楚楠同学配合完成后端模块，主要负责智能体工具能力封装、业务逻辑完善，配合完成接口联调，保障各个工具模块可以被智能体正常调度执行。我们项目包含待办管理、图像识别等工具能力，我负责把这些功能封装成可供大模型调用的工具，同时处理数据库读写逻辑，实现对话记录、待办信息持久化存储。调试的时候，很容易出现多个工具连续调用时会话状态混乱、数据库写入冲突等隐性 bug，需要仔细梳理任务执行链路，使用会话 ID 隔离不同用户对话。在和前端、测试同学配合的过程中，我学会从整体视角考虑系统稳定性，而不只是单独实现功能。这次实践加深了我对工具增强型智能体的理解，掌握了任务编排、工具注册的实现思路。

苏拉娅・斯地克阿吉 3224004384（测试）心得

本次小组作业中，我承担智能体功能测试工作，根据作业需求制定测试方案，编写基础测试用例，对智能体对话、待办管理、图片识别等核心功能逐一验证。测试时我以普通用户的身份在前端界面操作，检验智能体是否可以正确理解指令、调用工具并返回预期结果。一旦发现功能异常、回复错误、调用失败等问题，我会详细记录复现步骤、现象，清晰反馈给前端和后端组员，方便开发同学定位 bug。在开发同学修复完成之后，我会进行回归测试，确认问题真正解决。在一轮轮测试迭代中，我见证智能体从功能不完善到逐步稳定可用。这份工作让我意识到测试是项目质量的保障，同时也顺着测试流程吃透了整个智能体从请求输入到工具执行、结果返回的完整业务流程。

黄泽欣 3224004268（测试）心得

我和苏拉娅・斯地克阿吉同学共同负责测试工作，重点负责边界场景、复杂组合指令的测试，并且在全部功能验证通过后录制系统演示视频。基础功能正常不代表智能体足够健壮，因此我设计了模糊指令、多任务连续下达、交替调用不同工具、长轮对话等测试场景，用来挖掘上下文丢失、工具调用错乱这类不容易发现的隐性缺陷。等到所有 bug 修复、全部用例回归通过，我开始录制演示视频，反复排练操作顺序，依次展示文字对话、待办增删改查、图片识别等功能，保证视频流程连贯、画面清晰，满足作业对演示视频的要求。这次任务让我学会多角度评估软件的健壮性，理解测试工作的价值，同时熟悉了项目交付成果的展示方式。

艾柯代・吐尔逊 3224004266（撰写博客）心得

我负责博客文档的前期框架搭建与素材收集整理，对照课程作业要求，搭建博文整体结构，按照需求描述、业务流程、实现说明、使用示例、分工表格、成员心得这些模块梳理大纲。在撰写初稿的过程中，我主动和前端、后端、测试的组员沟通，了解项目架构、实现思路、开发过程遇到的难点，收集项目截图、仓库地址、演示视频链接等素材，把大家口头描述的开发内容整理成条理清晰、通顺规范的文字。在这个过程中，我慢慢理解 MCP 智能体、工具调用、前后端交互等相关知识，学习 Markdown 排版技巧。我认识到技术文档不只是简单记录文字，而是向阅读者清晰传递我们项目的设计思路与实现成果，是团队项目交付中很重要的一环。

王昊圆 3224004232（撰写博客）心得

我和艾柯代・吐尔逊同学搭档完成博客撰写任务，主要负责全文整合、内容校对、格式调整以及博文最终发布工作。我对照作业的全部要求逐项自查，完善 Agent 说明文档各个章节，汇总所有组员的心得，调整排版，嵌入演示视频，核对 GitHub 仓库链接、小组分工表等内容，保证整篇博客完整规范。整合文档的过程，也是对整个项目完整复盘的过程：用户在前端页面输入指令或者上传图片，请求发送到后端，智能体自主判断意图、调用对应工具执行任务，经过多轮测试验证稳定后，通过录屏视频展示效果。这份工作让我跳出单一岗位视角，建立起对整个项目完整的全局认知，熟悉课程作业的交付规范，学会规范化整理、包装团队开发成果，也为后续大型课程项目的文档交付积累了经验。