ai-agent框架spring ai alibaba (三)外部调用II-1 MCP

简介spring ai alibaba是java的ai agent框架本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理不仅指导agent的开发更可以改造框架增加新特性系列内容系列(一) 架构 完成系列(二) 调用I 工具II-1 MCP MCP能力工具资源Promptssampling。。。springboot自动配置-2 分布式 MCP-3 MCP securityIII skills 完成系列(六) RAGI 知识库文档读取分块嵌入向量store检索增强生成模块化II 混合检索融合重排系列(三) 模型I 模型模型chat模型; chat client提示词消息结构化输出II advisor组件chat记忆会话管理系列(四) graph 图结构节点和边StateGraphCompiledGraph图执行系列(五) I agentReactAgent另外FlowAgainA2A agent放在MASII 钩子和拦截器上下文工程系列(七) MASI FlowAgentsub agentagent toolhandoffs模式toolcalling模式II A2A分布式agentagent集群AP2APIII 集成agentscope-javaagentic模式消息hub系列(八) 模型评估和观测系列(九) agent管理平台(admin) agent发布列表提示词管理会话管理skill管理MCP服务管理评估观测其他 多模态本文分析外部调用II-1 MCP另外II-2 分布式MCPII-3 MCP securitybased spring ai aliba ba v1.1.2.2spring ai v1.1.2MCP sdk 0.17.0关键词缩写spring ai缩写saspring ai alibaba本文缩写saa参考资料https://java2ai.com/docs/overview spring ai alibaba官网文档https://docs.spring.io/spring-ai/reference/index.html spring ai官方文档组件视图上图是saa原理源码分析场景视图每个包对应着saa/sa组件或特性是本文分析的目录model大模型调用装模型包括Chat嵌入audioimage等类型其中chat模型包括chat clientadvisor组件提示词记忆等agent/graphagent和图紧密相关可以认为agent是一种既定的”图”形开发人员可以使用graph低层api直接构建graph也可以使用agent获得既定的图形简化和加快agent的开发外部调用(calling)调用可能是agent发展演变最快的部分最初的工具到mcp最近的CLIskillsRAG检索增强生成MAS多个agent协同工作每个agent有独立职能studio简易的agent管理工具嵌入到agent带有agent面板列表agent提供chat界面用于调试agentadmin管理台 agent的发布列表管理执行提示词工程评估和数据集观测外部调用如果说agent是一个人大模型是大脑调用是手脚执行动作干实事。调用在不断发展演变中目前已有工具MCPskillsCLI等多种方式MCP-sdk MCP的实现包括连接管理会话和传输协议能力(资源工具等)本文不分析MCP原理源码重点放在sa/saa集成MCPsaa分布式MCPMCP介绍本节介绍MCP上图sa文档MCP的描述3个关键词MCP是ai model调用工具和资源的标准协议MCP是ai model与外部交互的桥梁MCP能力(Capabilities)MCP规范定义MCP的能力Tools是主要能力其他能力有client侧有server侧的server侧Tools定义可执行的函数是目标本身让 AI 做事情如查天气、发邮件、写文件。Resources提供可读取的数据 Tool的“原材料”或“背景知识”。 执行Tool前通过Resource了解当前状态、配置、文档或待处理的数据。Prompts 提供预定义的提示词模板教AI正确使用Tool。避免 AI 自己乱编调用方式提供最佳实践和上下文示例。Completion自动补全能力允许服务器为 Prompts 和 Resources 的参数提供实时的、上下文感知的输入建议client侧Elicitation大模型反向询问client获取用户信息Rootsclient告诉server “用户的工作目录在哪”方面后续server获取client的文件数据Sampling 允许Tool在执行过程中请求AI生成内容让Tool 拥有“内省”或“补全”能力。一个复杂的Tool执行中需要 AI 进行推理、总结或决策时可以通过Sampling临时“借用”客户端的 LLM 来完成。Notifications变更通知能力client和server变更互相实时通知总结MCP以Tools为中心其他的能力为完成工具调用设置要么是给大模型工具使用的资料(Resources,Prompts)告诉大模型工具怎样使用要么server工具调用中向client询问信息(SamplingElicitation)与skills对比skills让大模型做好任务MCP让大模型用好工具两者可以互替MCP工具MCP工具sa使用ToolCallback/ToolCallbackProvider组件封装后续以工具管理和调用共享工具调用的运行环境上图MCP工具类图SyncMcpToolCallbackProvider接收McpSyncClient集为参数遍历McpSyncClient集每个McpSyncClient可带多个MCP工具(MCP.Tool类)每个MCP.Tool封装为SyncMcpToolCallbackSyncMcpToolCallbackToolCallback实例工具调用类引用McpSyncClient调用MCP .ToolMcpClient.SyncSpecSyncSpec是McpClient的builder可设置多种事件消费者监听能力的变更其中有Tool变更ApplicationListener/McpToolsChangedEvent SyncMcpToolCallbackProvider实现Tool变更监听使用spring的事件机制监听MCP工具的变更即上节的Notifications能力重刷一遍McpSyncClient集合构建新的SyncMcpToolCallback下面分析MCP集成springboot自动配置构建SyncMcpToolCallbackProvider/SyncMcpToolCallbackMCP集成本节分析sa的MCP集成spring boot自动配置分java配置和注解配置两部分其中java配置构建ToolCallback注解配置负责MCP能力构建client侧的McpSampling, McpElicitation, McpProgress等server侧的McpTool, McpResource, McpPrompt, McpComplete等MCP client本节分析MCP clientMCP client运行在AI应用与MCP sesrver调用MCP server工具和能力java配置上图自动配置Java配置类图为了展示清晰Transport有只展示Streamable只展示同步McpToolCallbackAutoConfiguration自动配置的C位自动配置最终目标是构建SyncMcpToolCallbackProviderSyncMcpToolCallbackProvider给ai应用提供McpToolCallback依赖McpClientAutoConfiguration 构建的McpSyncClientMcpClientAutoConfiguration负责构建McpSyncClient依赖McpTransport通讯传输实现McpSyncClientConfigurer给用户定制McpSyncClient的组件McpAsyncClientConfigure/McpSyncClientCustomizer使用SyncSpec定制McpSyncClient上一节介绍的设置MCP工具变更事件消费者就是这个组件完成StreamableHttpHttpClientTransportAutoConfiguration负责构建McpTransport使用配置属性(Properties)注解配置McpSyncClient的能力是由注解配置负责上图MCP client注解配置类图McpClientAnnotationScannerAutoConfiguration注解自动配置类职责实例化ClientMcpSyncHandlersRegistryClientMcpSyncHandlersRegistry扫描spring管理的类型找出带MCP标注的bean使用了spring两个机制--BeanFactoryPostProcessor扫描受spring管理的类(带Service注解)构建两个属性对象allAnnotatedBeans所有带有MCP注解的bean的名称capabilitiesPerClient保存每个client拥有的能力MCP client用它列举能力--SmartInitializingSingleton分析allAnnotatedBeans的MCP注解使用反射技术封装MCP能力处理器McpClientAutoConfiguration/McpSyncClient上节java配置分析过其中McpSyncClient能力设置是注解配置负责从ClientMcpSyncHandlersRegistry获取总结client侧的自动配置目标是构建SyncMcpToolCallbackProviderjava配置负责该类提供调用MCP工具的组件McpToolCallbackMcpToolCallback依赖McpSyncClient也是java配置负责注解配置负责McpSyncClient能力handlerMCP server上节分析MCP client侧自动配置server侧“套路”类似server侧的配置最终目的是构建Mcp Serverjava配置负责而注解配置负责初始化Mcp Server的能力上图 MCP server的自动配置图1负责构建McpSyncServerMcpServerAutoConfiguration负责构建McpSyncServer依赖各种能力SpecificationMcpSyncServer负责通讯处理能力请求能力Specification可以理解为药方构建能力需要的属性都在里面McpSyncServer用来构建能力对象ServerMcpAnnotatedBeans这对象在这里只是new了里面装着以注解类型分组的bean用来构建能力Specification下面分析能力Specification怎么来的下面继续分析上图 MCP server的自动配置图2负责构建各种能力SpecificationMcpServerSpecificationFactoryAutoConfiguration 能力Specification构建在这个自动配置SyncMcpAnnotationProviders 该对象的定义了各种能力Specification的实例方法Bean以tool能力规格实例方法toolSpecs为例SpringAiSyncToolProvider 构建tool能力规格的对象从ServerMcpAnnotatedBeans的beansByAnnotation获取带标注MCPTool的bean通过反射获取数据构建tool能力规格对象 SyncToolSpecification最后看看ServerMcpAnnotatedBeans的beansByAnnotation是怎么获得的上图 MCP server的自动配置图3负责beansByAnnotation的获取McpServerAnnotationScannerAutoConfiguration 负责注解扫描设定了扫描的注解ServerAnnotatedMethodBeanPostProcessor利用spring的机制BeanPostProcessor该机制开发者在 Spring 容器实例化Bean之后、初始化方法如PostConstruct、afterPropertiesSet、自定义 init-method调用之前和之后对 Bean 进行自定义的增强处理ServerAnnotatedMethodBeanPostProcessor使用了调用后的机制点AnnotatedMethodDiscovery 扫描BeanPostProcessor送过来的bean获取bean所有目标注解ServerMcpAnnotatedBeans AnnotatedMethodDiscovery扫描回来的注解(集)送个ServerMcpAnnotatedBeans按注解类型分组bean得到MapClass?extendsAnnotation, ListObject beansByAnnotation这个也是第二步用来构建能力规格的web serverMCP server不是web服务如 tomcatweb服务负责接收和处理web请求因此MCP 服务需要引用web服务本节以webmvc为例分析一下MCP server与web服务的关联上图是MCP server和web服务集成MCP server应用引入spring-ai-starter-mcp-server-webmvc引入tomcatRouterFunctionMapping/AbstractHandlerMapping spring-mvc负责路由请求的组件get/post请求交割WebMvcStreamableServerTransportProvider构建的RouterFunction最终调用McpSyncServer的能力示例与观测(TBD)