切换主题
第 12 章：复杂案例，别被整机吓住
到这里，我们已经看过单 Agent、工具、记忆、Graph、多智能体和工程入口。复杂案例不是凭空冒出来的新世界，它们只是把前面学过的零件组合得更完整。
本章边界
本章教你怎么读复杂 examples：先看入口，再看配置、Agent、Graph/Node、工具和外部服务。没有 API Key、语音模型、MCP 服务或外部网络时，有些例子跑不起来很正常。
1. 生活类比：从零件盒到整机
你学修自行车，先认识车轮、链条、刹车、变速器。最后看整车时，不要被复杂外形吓到。复杂案例也是整车：入口、配置、Agent、工具、流式链路，每一块前面都见过。
读复杂案例时，按这条路线走：
text
Application -> Config -> Agent -> Graph / Node -> Tool / 外部服务不要从最深的工具实现开始钻。先抓主干，再拆分支。
2. DeepResearch：研究型 Agent
DeepResearch 可以理解成一个“研究助理团队”：一个 Agent 负责研究，一个 Agent 负责批判和修正，外部工具负责查资料或访问 MCP 服务。
读它时别先陷进某个工具参数。先看它怎么把“研究、批判、补充”组织成一个流程。
3. Voice Agent：不只是聊天加播放器
语音 Agent 比文本聊天多了三段流式链路：
这里的难点不是“Agent 会不会回答”，而是流：音频流、文本流、工具事件、TTS 输出流要串起来。任何一段慢了、断了、格式不对，体验都会崩。
4. Sandbox 和内置节点
Sandbox 解决的是“工具能干什么、不能干什么”。如果工具可以执行代码、读文件、访问网络，就必须有边界。
内置节点解决的是“常见节点能不能复用”。例如 LLM 节点、工具节点、Agent 节点，本质上是把前面学过的能力做成可复用积木。
| 能力 | 关注点 |
|---|---|
| Sandbox | 权限、目录、网络、命令、超时、审计 |
| 内置 LLM 节点 | 模型输入输出、流式返回、模板配置 |
| 内置工具节点 | 工具解析、执行、错误处理 |
| 内置 Agent 节点 | 在更大的 Graph 里复用一个 Agent |
5. 复杂案例运行前置
| 案例 | 运行前先确认 |
|---|---|
| DeepResearch | 模型 API Key、MCP 服务或远程工具、网络访问策略 |
| Voice Agent | 语音识别/语音合成模型、音频格式、WebSocket 或流式传输配置 |
| Multimodal | 模型是否支持多模态输入、文件大小、图片/音频格式 |
| Sandbox 工具 | 目录白名单、命令白名单、超时、审计日志、网络策略 |
| 内置节点 | 输入输出 key、state 合并策略、错误节点或兜底路径 |
排查顺序建议：
text
先确认外部能力可用 -> 再确认 Spring Bean 装配 -> 再确认 Agent / Graph 执行 -> 最后调模型效果不要一看到回答不理想就先改 Prompt。有时候真正的问题是语音模型没加载、工具没权限、MCP 服务没连上。
6. 新手容易误解什么
误解一：复杂案例等于新框架。
不是。DeepResearch、Voice、Sandbox 仍然围绕 Agent、Graph、Tool、State 展开。
误解二：实时语音只是普通聊天加播放器。
不是。实时语音要处理 ASR、Agent、TTS 多段流式链路。
误解三：Sandbox 是炫技。
不是。它是危险工具进入生产前的安全边界。
7. 本章小结
复杂案例的读法：
text
先看系统怎么分层，再看每层怎么接，最后才看具体实现。下一章收束整套教程，给一条后续源码阅读和问题定位路线。
8. 练习题
- 给 Voice Agent 画一张 ASR -> Agent -> TTS 的事件流，并标出可能失败的位置。
- 把 DeepResearch 拆成“研究、批判、补充、输出”四个阶段。
- 给 Sandbox 工具设计生产准入清单：目录、网络、命令、超时、日志、审批分别怎么限制。
课后源码索引：想验证实现时再打开
| 你想验证的结论 | 源码锚点 |
|---|---|
| DeepResearch 应用入口 | examples/deepresearch/src/main/java/com/alibaba/cloud/ai/examples/deepresearch/Application.java，类 Application，方法 main(...)、mcpSyncHttpClientRequestCustomizer()、applicationReadyEventListener(...) |
| DeepResearch 如何组合研究 Agent 和批判 Agent | examples/deepresearch/src/main/java/com/alibaba/cloud/ai/examples/deepresearch/DeepResearchAgent.java，类 DeepResearchAgent，方法 getResearchAgent(...)、createResearchAgent(...)、createCritiqueAgent(...)、subAgentAsInterceptors(...) |
| DeepResearch 如何暴露给 Studio | examples/deepresearch/src/main/java/com/alibaba/cloud/ai/examples/deepresearch/AgentStaticLoader.java，类 AgentStaticLoader，方法 listAgents()、loadAgent(...) |
| Voice Agent 启动与配置 | examples/voice-agent/src/main/java/com/alibaba/cloud/ai/examples/voiceagent/VoiceAgentApplication.java，类 VoiceAgentApplication，方法 main(...)；VoiceAgentConfig.java，方法 sandwichAgent(...)；RealtimeVoiceConfig.java，方法 dashScopeAudioTranscriptionModel(...) |
| Voice 流式编排 | examples/voice-agent/src/main/java/com/alibaba/cloud/ai/examples/voiceagent/stream/RealtimeVoiceAgentStreamService.java，类 RealtimeVoiceAgentStreamService，方法 streamWithAudioRealtime(...)、runAgentWithStreamingTts(...)、extractAudio(...)、parseArgs(...) |
| Sandbox 工具边界 | spring-ai-alibaba-sandbox/src/main/java/com/alibaba/cloud/ai/sandbox/SandboxAwareTool.java，类 SandboxAwareTool，方法 getSandbox()、setSandbox(...)、getSandboxClass() |
| 内置节点 | spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/AgentNode.java、LlmNode.java、ToolNode.java |