1. 项目概述基于MCP协议的AI应用构建实践这个项目记录了一个完整的AI应用开发过程从最初的简单脚本到最终的多智能体系统架构。核心在于利用模型上下文协议(MCP)来构建可扩展的人工智能应用特别是处理存储在Box云存储中的非结构化文档如PDF发票的场景。项目最初实现了一个简单的本地发票处理脚本能够从PDF文件中提取文本并使用Gemini模型解析关键字段。随后引入了Box MCP服务器将文件处理和AI能力集成外包给专门的MCP服务。最终演进为多智能体架构通过A2A(Agent-to-Agent)协议实现智能体间的协作。2. 核心需求与技术选型2.1 业务场景与痛点典型的发票处理场景面临几个核心挑战文件格式多样性PDF、Word、JPEG等不同格式需要不同的处理方式数据提取复杂性需要从非结构化文本中准确识别关键业务字段系统扩展性随着业务增长需要处理的文件数量可能急剧增加安全性要求发票通常包含敏感财务信息需要安全处理传统解决方案通常需要为每种文件类型编写自定义处理代码并直接集成各种AI服务API导致维护成本高且难以扩展。2.2 MCP协议的核心价值模型上下文协议(Model Context Protocol, MCP)通过标准化AI应用与外部系统的交互方式解决了上述痛点解耦应用逻辑与数据集成应用只需与MCP服务器交互无需直接对接各种数据源和工具统一工具调用接口不同服务提供的功能通过标准化方式暴露给AI应用简化扩展新增数据源或工具只需在MCP服务器实现不影响现有应用在本项目中Box MCP服务器提供了与Box平台交互的标准工具集包括文件列表获取(list_folder_contents)自由格式数据提取(ai_extract_freeform)文档搜索等能力2.3 技术栈选择项目采用的技术栈经过精心选择平衡了功能需求与实现复杂度技术组件选型理由大语言模型Gemini 2.0 Flash/ProGoogle提供的强大模型良好的API支持MCP服务器Box MCP服务器专为Box平台优化的MCP实现数据库SQLite轻量级适合原型开发智能体框架Google ADK官方提供的智能体开发工具包通信协议A2A协议标准化的智能体间通信方式3. 系统架构演进路径3.1 阶段一自定义脚本方案初始实现是一个独立的Python脚本主要流程包括使用PyPDF2从本地PDF文件提取文本调用Gemini API解析发票字段将结果存储到SQLite数据库生成汇总报告这种方案虽然简单直接但存在明显局限仅支持PDF格式需要预先下载所有文件到本地业务逻辑与数据处理紧密耦合难以扩展新功能3.2 阶段二MCP集成方案引入Box MCP服务器后架构发生了重要变化文件访问方式不再需要本地下载直接通过MCP工具访问Box中的文件数据处理位置文本提取和字段解析在Box服务器端完成能力扩展通过MCP工具定义可以轻松支持新文件类型和数据处理方式关键改进点使用list_folder_contents工具获取文件列表通过ai_extract_freeform工具提取结构化数据应用代码仅需关注业务逻辑不涉及具体数据处理细节3.3 阶段三多智能体架构最终架构将系统分解为多个专用智能体文件智能体专精于文件列表获取提取智能体负责从文档中提取结构化数据协调智能体接收用户请求并协调其他智能体工作智能体间通过A2A协议通信每个智能体有明确的职责边界通过标准化接口暴露能力可以独立开发、部署和扩展这种架构的优势在于职责分离降低单个组件的复杂度支持并行开发和团队协作可以根据负载单独扩展特定智能体更容易替换或升级单个组件4. 关键实现细节4.1 MCP服务器集成与Box MCP服务器的交互遵循标准流程初始化连接server_params StdioServerParameters( commanduv, args[run, --directory, MCP_SERVER_PATH, mcp-server-box] )工具发现async def get_mcp_tools(session): response await session.list_tools() return [tool for tool in response.tools if tool.name in TOOLS_TO_USE]工具调用async def generate(prompt, tools_definitions, session): # 发送提示词和工具定义给模型 response await chat.send_message_async(prompt, toolstools_definitions) if response.candidates[0].content.parts[0].function_call: fc response.candidates[0].content.parts[0].function_call # 通过MCP会话调用工具 tool_response await session.call_tool(fc.name, fc.args) return parse_json_response(tool_response.content[0].text)4.2 智能体定义与通信每个智能体都有明确的定义和接口文件智能体定义files_agent adk.Agent( namefiles_agent, instructions你的职责是列出指定Box文件夹中的所有文件ID。, tools[list_box_folder_tool] )智能体卡片描述智能体能力files_agent_card adk.AgentCard( namefiles_agent, endpointfhttp://localhost:{FILES_AGENT_PORT}, input_schema{type: object, properties: {folder_id: {type: string}}}, output_schema{type: array, items: {type: string}}, skills[list_files] )智能体间通信# 协调智能体将任务委托给文件智能体 response await client.send_task({ action: list_files, folder_id: BOX_FOLDER_ID })4.3 数据处理流程优化从原始文本到结构化数据的转换经过多次优化初始方案手动编写提示词直接解析模型返回的非结构化文本改进方案要求模型返回标准JSON格式并添加错误处理最终方案利用MCP服务器的标准化数据提取工具返回结构一致的数据关键提示词设计prompt fExtract the following fields from the invoice: - Client Name - Invoice Amount (as number) - Product Name Return as JSON with keys: client_name, invoice_amount, product_name5. 部署与运维考量5.1 环境配置项目需要正确配置以下环境Box开发者账号获取API凭证和文件夹访问权限Gemini API密钥用于访问大语言模型MCP服务器依赖Python 3.8和必要的库依赖推荐使用.env文件管理敏感配置GEMINI_API_KEYyour_api_key BOX_FOLDER_IDyour_folder_id MCP_SERVER_PATH./mcp-server-box5.2 性能优化针对不同场景的性能优化策略场景优化手段效果大批量文件处理异步IO并行处理吞吐量提升3-5倍复杂文档解析使用Gemini Pro模型准确率提升但延迟增加频繁小文件处理本地缓存机制减少MCP服务器调用5.3 监控与日志建议添加的监控维度MCP工具调用成功率、响应时间、错误类型模型使用Token消耗、响应质量智能体协作任务分发效率、通信延迟示例日志记录import logging logging.basicConfig( levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s ) logger logging.getLogger(__name__) logger.info(fProcessing invoice: {filename}) logger.error(fFailed to extract data: {error})6. 扩展与应用场景6.1 可能的扩展方向新增智能体类型验证智能体检查提取数据的合理性分类智能体根据内容自动分类文档工作流智能体管理复杂业务流程增强现有能力支持更多文件格式如扫描件OCR添加多语言支持实现更复杂的数据验证规则系统集成与企业ERP系统对接添加审批工作流与BI工具集成生成可视化报表6.2 适用场景迁移该架构可应用于其他类似场景合同管理系统提取合同关键条款跟踪义务和截止日期风险评估医疗记录处理从病历中提取诊断信息药物相互作用检查保险理赔自动化法律文档分析条款对比风险点识别案例检索7. 经验总结与最佳实践7.1 关键经验教训渐进式架构演进从简单原型开始验证核心想法随着需求复杂化逐步引入MCP、多智能体等概念避免过早优化导致的过度设计清晰的职责划分每个智能体应该只做一件事并做好通过明确的接口定义交互契约避免智能体间的隐式耦合标准化接口设计输入输出使用标准Schema定义错误处理遵循统一规范版本兼容性考虑7.2 推荐实践开发流程为每个智能体维护独立的代码库定义清晰的接口契约测试使用容器化部署保证环境一致性调试技巧记录完整的智能体间对话历史可视化任务执行流程图对MCP工具调用进行重放测试性能调优监控每个智能体的资源使用识别系统瓶颈智能体考虑有状态与无状态设计权衡8. 常见问题排查8.1 MCP连接问题症状无法连接到MCP服务器或工具调用失败排查步骤验证MCP服务器进程是否正常运行检查环境变量和路径配置确认网络权限和防火墙设置查看服务器日志获取详细错误典型解决方案# 确保服务器参数正确 server_params StdioServerParameters( commanduv, args[run, --directory, /correct/path, mcp-server-box] )8.2 数据提取不准确症状提取的字段值不正确或缺失优化策略改进提示词工程提供更明确的指令添加示例和预期输出格式实现后验证逻辑检查数据合理性考虑使用更强大的模型版本改进后的提示词示例prompt f从以下发票文本中精确提取 - 客户名称 (必须匹配^[A-Z][a-z] [A-Z][a-z]$) - 发票金额 (必须为数字如123.45) - 产品名称 (至少3个字符) 返回JSON格式缺失字段用null表示。8.3 智能体通信故障症状智能体间消息丢失或响应超时解决方案实现消息重试机制添加心跳检测使用持久化队列保证消息不丢失合理设置超时参数健壮性增强实现async def send_task_with_retry(client, task, max_retries3): for attempt in range(max_retries): try: return await client.send_task(task) except Exception as e: if attempt max_retries - 1: raise await asyncio.sleep(2 ** attempt)9. 资源与后续学习9.1 推荐学习资料官方文档Box MCP服务器GitHub仓库Google ADK文档A2A协议规范相关技术提示词工程最佳实践分布式系统设计模式微服务架构原则进阶主题智能体编排引擎模型微调技术复杂工作流管理9.2 社区资源论坛与群组MCP协议开发者社区企业AI应用实践小组智能体系统设计讨论组开源项目参考类似架构的参考实现智能体开发框架MCP服务器实现案例会议与活动AI工程化研讨会企业智能自动化峰会MCP协议相关技术分享