1. 为什么我选择 Flutter LLM 多智能体这条技术路线移动端做 AI 应用最容易踩的坑就是“把大模型当接口调”。我最早也是这么干的Flutter 页面里塞一个输入框用户打字请求发到后端等模型返回渲染结果。跑通 Demo 没问题但一旦要做稍微复杂点的任务——比如让 AI 帮我整理一份会议纪要、自动拆解一个待办清单、或者根据一段需求描述生成多个可执行步骤——单次调用就完全不够用了。模型会忘上下文、会跑偏、会在多轮对话里自相矛盾。后来我开始接触多智能体Multi-Agent这套思路才意识到问题的本质不是模型不够强而是我把所有活儿都压给了一个“大脑”。多智能体的核心逻辑是把一个复杂任务拆成若干角色每个角色有自己的职责、工具和记忆彼此之间通过消息传递协作。这跟现实里的团队分工是一个道理——你不会让一个人同时当产品经理、程序员和测试AI 也一样。那为什么客户端选Flutter我试过原生 Android 和 iOS 各写一套也试过 React Native。Flutter 的优势在于一套代码两端跑UI 一致性好热重载调试快而且 Dart 的异步模型Future、Stream天然适合处理 LLM 这种流式返回的场景。特别是Flutter 3.44之后Impeller 渲染引擎在 iOS 和 Android 上都稳定了列表滚动、流式文字渲染的卡顿问题基本消失。再加上part文件机制可以把 Agent 的逻辑拆成独立模块代码组织起来很清爽。这篇文章适合谁看如果你已经会一点 Flutter想往 AI 应用方向走或者你是做后端的想理解客户端怎么跟 LLM 协作再或者你纯粹对 Agent 开发感兴趣想找一个能跑起来的实战入口——那这篇就是给你写的。我会从整体架构讲到具体代码从工具选型讲到踩坑记录尽量把每个“为什么”都说清楚。提示本文涉及的多智能体方案基于常见工程实践补充具体模型接口和框架选型请以你实际使用的服务为准。2. 多智能体到底在解决什么问题从单次调用到角色协作2.1 单 Agent 的天花板在哪里先说说单 Agent 的典型结构。一个 Agent 通常包含四部分模型LLM、工具Tools、记忆Memory、规划Planning。你给它一个目标它自己决定调哪个工具、怎么一步步推进。听起来很美好但实际用起来单 Agent 有三个绕不过去的坎。第一个坎是上下文窗口的物理限制。哪怕模型支持 128K token当你把历史对话、工具返回结果、系统提示全塞进去很快就会撑满。撑满之后要么截断丢信息要么压缩丢细节无论哪种都会导致 Agent “失忆”。第二个坎是角色冲突。你让一个 Agent 既当“需求分析师”又当“代码生成器”它在不同阶段需要切换完全不同的思维模式。实际测试下来模型很容易把两种角色的输出风格混在一起生成的代码里夹杂着需求描述或者需求文档写得像代码注释。第三个坎是错误累积。单 Agent 执行多步任务时每一步的输出都依赖上一步。如果第三步理解错了第四步、第五步会沿着错误方向一路狂奔而且它自己意识不到。这就像一个人做数学题第一步符号抄错了后面全错。2.2 多智能体的分工逻辑多智能体的思路是把上面这些坎逐个拆解。核心做法是定义多个角色每个角色有独立的系统提示、独立的工具集、独立的记忆空间通过一个协调者Orchestrator来调度。我常用的一个最小可行结构是三个 Agent规划 AgentPlanner负责理解用户意图把大任务拆成有序的子任务列表。它不直接干活只输出“要做什么”。执行 AgentExecutor接收子任务调用具体工具比如搜索、计算、文件读写完成。它不关心全局只关心当前这一步。审查 AgentReviewer检查执行结果是否符合预期如果不符合给出修改意见并打回重做。这三个角色的系统提示完全不同。Planner 的提示强调“拆解”和“排序”Executor 的提示强调“准确调用工具”和“返回结构化结果”Reviewer 的提示强调“找茬”和“给出可操作的修改建议”。因为提示隔离角色冲突的问题自然就消失了。2.3 通信机制消息总线还是直接调用多智能体之间怎么通信有两种常见方案。一种是消息总线Message Bus所有 Agent 往总线发消息总线负责路由。另一种是直接调用Orchestrator 持有各个 Agent 的引用按顺序调用。我一开始用的是消息总线觉得解耦彻底、扩展方便。但实际写下来发现在客户端场景里消息总线引入了额外的复杂度你需要定义消息格式、处理消息丢失、管理订阅关系。而 Flutter 客户端的多智能体通常 Agent 数量不多3 到 5 个任务流程相对固定直接调用反而更简单可控。所以我的选择是Orchestrator 模式 直接调用。Orchestrator 是一个普通的 Dart 类持有 Planner、Executor、Reviewer 的实例按规划 - 执行 - 审查 - 循环的流程调度。每个 Agent 是一个独立的类实现统一的Agent接口接口里只有一个FutureAgentResult run(AgentInput input)方法。这样既保证了角色隔离又避免了过度设计。注意如果你的 Agent 数量超过 8 个或者任务流程是动态变化的那消息总线可能更合适。但在客户端场景下Orchestrator 模式足够用而且调试起来直观得多。3. Flutter 侧的核心架构设计怎么把 Agent 塞进 App 里3.1 分层结构UI 层、Agent 层、模型层在 Flutter 里做多智能体我习惯分三层UI 层负责展示对话、任务进度、Agent 状态。用flutter_bloc或cubit管理状态。为什么选 Bloc 而不是 Provider因为多智能体的状态变化是“事件驱动”的——用户发消息是一个事件Agent 返回结果是一个事件审查不通过又是一个事件。Bloc 的Event - State模型跟这个场景天然契合。而且 Bloc 的emit机制可以很方便地做流式更新比如 Executor 每调用一个工具就 emit 一次中间状态。Agent 层包含 Orchestrator 和各个 Agent 的实现。这一层不依赖任何 Flutter UI 组件纯 Dart 代码。好处是可以单独写单元测试不用起模拟器。我通常会把 Agent 相关的代码放在lib/agents/目录下用part文件拆分orchestrator.dart是主文件planner.dart、executor.dart、reviewer.dart作为 part 引入。这样既保持了文件独立性又避免了循环依赖。模型层封装 LLM 调用。这一层要处理的事情包括请求构造、流式解析、错误重试、Token 计数。我建议把模型调用抽象成一个LlmClient接口具体实现可以是 OpenAI 兼容接口、也可以是本地模型接口。这样切换模型时只需要换实现类Agent 层代码不用动。3.2 状态管理为什么用 Cubit 而不是 setState有人会问一个聊天界面用setState不就行了吗单 Agent 场景确实可以但多智能体场景下状态太多了当前哪个 Agent 在运行、任务拆解到第几步、每步的执行结果、审查意见、错误信息……这些状态散落在各个 Widget 里用setState管理会变成一团乱麻。Cubit 的好处是状态集中管理。我定义一个AgentState类包含ListAgentMessage messages、AgentPhase currentPhase、int currentStep、String? error等字段。UI 层只监听这一个 State任何变化都通过emit触发重建。这样调试的时候我只需要在emit处打日志就能看到完整的状态流转。另外Cubit 的emit是同步的但 Agent 的执行是异步的。所以我在 Cubit 里用async方法处理事件每完成一步就emit一次。这样 UI 上能看到“规划中 - 执行第1步 - 审查中 - 执行第2步”这样的实时进度用户体验比转圈等待好得多。3.3 流式渲染LLM 返回的文字怎么逐字显示LLM 的流式返回是提升体验的关键。用户看到文字一个个蹦出来会觉得“AI 在思考”而不是“卡死了”。Flutter 里实现流式渲染核心是StreamBuilder配合StreamString。具体做法LlmClient的chatStream方法返回一个StreamString每收到一个 chunk 就 yield 一次。Cubit 里订阅这个 Stream每收到一个 chunk 就更新当前消息的content字段并emit。UI 层用ListView.builder渲染消息列表当前正在流式输出的消息用一个特殊的 Widget 显示配合AnimatedSize或AnimatedOpacity做平滑过渡。这里有个细节流式输出的文字如果直接 append会导致整个 Text Widget 重建长文本时性能很差。我的做法是把消息内容拆成“已完成部分”和“流式部分”已完成部分用普通 Text 渲染流式部分单独用一个 Text 渲染。这样每次 chunk 到达时只有流式部分的 Text 重建性能好很多。实操心得Flutter 的SelectableText在流式更新时会有光标跳动问题。如果不需要选中复制用普通Text就行。如果需要选中建议等流式结束后再切换成SelectableText。4. Agent 核心模块的代码实现与关键细节4.1 Agent 接口定义与 Orchestrator 调度逻辑先定义统一的 Agent 接口。这是整个多智能体系统的契约abstract class Agent { String get name; FutureAgentResult run(AgentInput input); } class AgentInput { final String task; final MapString, dynamic context; final ListAgentMessage history; AgentInput({required this.task, this.context const {}, this.history const []}); } class AgentResult { final bool success; final String output; final MapString, dynamic metadata; AgentResult({required this.success, required this.output, this.metadata const {}}); }Orchestrator 的调度逻辑是一个循环Planner 拆解任务 - 对每个子任务Executor 执行 - Reviewer 审查 - 如果审查不通过把审查意见塞回 Executor 重做 - 所有子任务完成后汇总输出。class Orchestrator { final PlannerAgent planner; final ExecutorAgent executor; final ReviewerAgent reviewer; final int maxRetries; Orchestrator({required this.planner, required this.executor, required this.reviewer, this.maxRetries 2}); StreamAgentEvent execute(String userTask) async* { yield AgentEvent.phase(AgentPhase.planning); final plan await planner.run(AgentInput(task: userTask)); final steps _parseSteps(plan.output); for (var i 0; i steps.length; i) { yield AgentEvent.stepStart(i, steps[i]); var retries 0; var result await executor.run(AgentInput(task: steps[i], context: {step: i})); while (retries maxRetries) { final review await reviewer.run(AgentInput(task: steps[i], context: {result: result.output})); if (review.success) break; retries; yield AgentEvent.retry(i, retries, review.output); result await executor.run(AgentInput(task: steps[i], context: {feedback: review.output})); } yield AgentEvent.stepDone(i, result.output); } yield AgentEvent.phase(AgentPhase.done); } }这里用StreamAgentEvent而不是Future是为了让 UI 层能实时收到每一步的进度。AgentEvent是一个密封类包含phase、stepStart、stepDone、retry等子类型。Cubit 订阅这个 Stream把事件转换成 State。4.2 Planner 的提示工程怎么让模型稳定输出结构化任务Planner 的核心难点是输出格式的稳定性。你让模型“拆解任务”它可能返回一段散文也可能返回带编号的列表格式每次都不一样。解析起来很痛苦。我的做法是在系统提示里强制要求 JSON 输出并且给出明确的 schema。比如你是一个任务规划专家。请把用户的任务拆解成 3 到 7 个有序子任务。 输出必须是严格的 JSON 数组每个元素包含 step序号和 description子任务描述。 不要输出任何 JSON 之外的内容。 示例输出 [ {step: 1, description: 收集用户需求中的关键信息}, {step: 2, description: 根据关键信息生成初步方案} ]然后在 Dart 侧用jsonDecode解析如果解析失败走一个 fallback用正则提取编号列表。实测下来加了 schema 约束后JSON 解析成功率从 60% 左右提升到 95% 以上。还有一个技巧在提示里加一句“如果任务无法拆解返回空数组”。这样遇到简单任务时Planner 不会硬拆避免过度规划。4.3 Executor 的工具调用Function Calling 的落地方式Executor 是真正干活的 Agent它需要调用工具。LLM 的 Function Calling 机制允许模型输出一个结构化的工具调用请求客户端解析后执行工具再把结果返回给模型。在 Flutter 里工具的定义是一个 Mapfinal tools [ { type: function, function: { name: search_web, description: 搜索互联网获取最新信息, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词} }, required: [query] } } }, { type: function, function: { name: calculate, description: 执行数学计算, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式} }, required: [expression] } } } ];Executor 的run方法里把 tools 传给 LLM。如果模型返回tool_calls就解析出工具名和参数调用对应的 Dart 函数把结果作为tool角色的消息追加到对话历史再次请求模型。循环直到模型返回普通文本不再调用工具。这里有个坑工具执行可能失败。比如搜索超时、计算表达式非法。我的做法是捕获异常把错误信息作为工具结果返回给模型让模型自己决定是重试还是换方案。这比直接抛异常中断流程要健壮得多。4.4 Reviewer 的审查策略怎么判断“做得好不好”Reviewer 是最容易被忽视但最重要的角色。它的提示需要非常具体不能只说“检查结果是否正确”而要给出检查维度。我常用的提示模板你是一个严格的质量审查员。请从以下三个维度审查执行结果 1. 完整性是否覆盖了任务描述中的所有要求 2. 准确性输出内容是否有事实错误或逻辑矛盾 3. 格式是否符合任务要求的输出格式 如果三个维度都通过返回 {pass: true, comment: 通过}。 如果有任何维度不通过返回 {pass: false, comment: 具体问题描述和修改建议}。Reviewer 的输出也是 JSON解析后决定是否打回重做。这里的关键是修改建议要具体。如果 Reviewer 只说“结果不好”Executor 重做时还是不知道往哪个方向改。所以提示里强调“具体问题描述和修改建议”。注意事项Reviewer 本身也会犯错可能把正确结果判为错误。所以maxRetries不能设太大我一般设 2 次。如果重做 2 次还是不过就接受当前结果并标记“审查未通过”让用户自己判断。无限重试会导致 Token 消耗失控。5. 实操全流程从零跑通一个多智能体 Demo5.1 环境搭建与依赖配置先说环境。Flutter 版本建议 3.44 以上因为 Impeller 在这个版本对 Android 的支持已经稳定。创建项目flutter create multi_agent_demo cd multi_agent_demopubspec.yaml里加依赖dependencies: flutter: sdk: flutter flutter_bloc: ^8.1.0 http: ^1.1.0 uuid: ^4.0.0flutter_bloc用于状态管理http用于调用 LLM 接口uuid用于生成消息 ID。不需要额外的 Agent 框架——多智能体的核心逻辑自己写反而更可控第三方框架往往引入不必要的抽象。Android 侧需要注意如果用的是 Android 原生项目嵌入 Flutter 页面要确保settings.gradle里的 Flutter SDK 路径配置正确。我遇到过The current configured Flutter SDK is not known to be fully supported的警告通常是因为 Flutter 版本和 Gradle 插件版本不匹配。解决办法是在android/settings.gradle里显式指定 Flutter SDK 路径并确保flutter.gradle插件的 apply 方式正确。5.2 LLM 客户端的封装与流式解析LlmClient的封装要点class LlmClient { final String baseUrl; final String apiKey; final String model; LlmClient({required this.baseUrl, required this.apiKey, required this.model}); StreamString chatStream(ListMapString, dynamic messages, {ListMapString, dynamic? tools}) async* { final request http.Request(POST, Uri.parse($baseUrl/chat/completions)); request.headers.addAll({ Content-Type: application/json, Authorization: Bearer $apiKey, }); request.body jsonEncode({ model: model, messages: messages, stream: true, if (tools ! null) tools: tools, }); final response await http.Client().send(request); if (response.statusCode ! 200) { throw LlmException(请求失败: ${response.statusCode}); } await for (final chunk in response.stream.transform(utf8.decoder).transform(const LineSplitter())) { if (chunk.startsWith(data: )) { final data chunk.substring(6); if (data [DONE]) break; try { final json jsonDecode(data); final delta json[choices][0][delta]; if (delta[content] ! null) { yield delta[content] as String; } } catch (_) { // 忽略解析失败的 chunk } } } } }这里有几个细节。第一stream: true开启流式。第二SSE 格式的响应以data:开头需要去掉前缀再解析。第三[DONE]是结束标记。第四解析失败的 chunk 直接忽略不要抛异常中断整个流——网络抖动时偶尔会有不完整的 chunk。5.3 完整调用链路用户输入到结果展示把整个链路串起来用户在输入框打字点击发送。Cubit 收到SendMessage事件把用户消息加入 Stateemit。Cubit 调用Orchestrator.execute(userTask)订阅返回的 Stream。Orchestrator 先调 PlannerPlanner 内部调LlmClient.chatStream收集完整输出后解析 JSON得到子任务列表。对每个子任务Orchestrator 调 Executor。Executor 调LlmClient.chatStream如果返回 tool_calls执行工具把结果追加到消息历史再次调用直到返回普通文本。Executor 返回结果后Orchestrator 调 Reviewer。Reviewer 同样调LlmClient解析 JSON 判断是否通过。每一步的结果都通过 Stream 事件推给 CubitCubit 更新 StateUI 重建。所有子任务完成后Orchestrator 发出done事件Cubit 把最终结果展示出来。整个链路的耗时主要在 LLM 调用上。一个 3 步任务加上审查和可能的 retry大概需要 5 到 10 次 LLM 调用。如果用流式用户能看到每一步的实时输出感知上的等待时间会短很多。5.4 参数选择温度、最大 Token 与重试次数几个关键参数的取值经验参数PlannerExecutorReviewertemperature0.30.70.1max_tokens10242048512重试次数120Planner 需要稳定输出温度调低。Executor 需要一定创造性温度稍高。Reviewer 需要严格判断温度最低。max_tokens 根据角色输出长度预估Planner 输出任务列表1024 够用Executor 可能生成较长内容2048Reviewer 只输出审查意见512 足够。重试次数方面Planner 如果解析失败重试 1 次Executor 被 Reviewer 打回后重试最多 2 次Reviewer 本身不重试它如果输出解析失败直接视为“审查通过”避免死循环。6. 踩坑记录与常见问题排查6.1 流式输出中断与状态丢失问题用户切换页面再回来流式输出断了状态也没了。原因Flutter 的Navigator切换页面时如果页面被销毁Cubit 也跟着销毁Stream 订阅自然就断了。解决把 Cubit 的生命周期提升到页面之上。用BlocProvider在更上层的 Widget 提供 Cubit或者用AutomaticKeepAliveClientMixin保持页面状态。另外Stream 订阅要用StreamSubscription持有在 Cubit 的close方法里取消订阅避免内存泄漏。6.2 JSON 解析失败的兜底策略问题Planner 或 Reviewer 返回的 JSON 格式不对jsonDecode抛异常。解决三层兜底。第一层尝试直接jsonDecode。第二层用正则提取 JSON 块\{[\s\S]*\}或\[[\s\S]*\]再解析。第三层如果还是失败用正则提取编号列表作为 fallback。实测下来三层兜底能覆盖 99% 的情况。6.3 Token 超限与上下文裁剪问题多轮对话后消息历史越来越长超过模型上下文窗口。解决在LlmClient里做 Token 估算粗略按字符数除以 4如果超过阈值比如模型上限的 80%就裁剪最早的消息。裁剪策略是保留 system 提示和最近 N 轮对话中间的工具调用结果可以摘要化。更精细的做法是用一个小的 LLM 调用做摘要但客户端场景下简单裁剪就够了。6.4 常见问题速查表问题现象可能原因排查方向解决方案流式输出卡顿每次 chunk 重建整个列表检查 UI 重建范围拆分已完成/流式部分Agent 死循环Reviewer 一直不通过检查 maxRetries限制重试次数超限强制通过工具调用失败参数格式不对打印 tool_calls 原始数据加参数校验和错误回传页面切换状态丢失Cubit 随页面销毁检查 BlocProvider 位置提升 Cubit 生命周期JSON 解析报错模型输出格式不稳定打印原始输出加 schema 约束和三层兜底请求超时网络或模型响应慢检查超时设置加超时和重试机制实操心得调试多智能体时最有效的方法是把每次 LLM 调用的输入和输出都打到日志里。我通常在LlmClient里加一个debugLog开关打开后把 messages 和 response 都打印出来。这样出问题时能快速定位是哪个 Agent 的哪一步出了偏差。7. 多智能体项目的扩展方向与个人体会这套架构跑通之后扩展空间其实很大。比如加一个Memory Agent专门负责从历史对话里提取关键信息存到本地数据库下次对话时自动加载。或者加一个Router Agent根据用户输入判断该走哪个流程——简单问答直接单 Agent 回复复杂任务才启动多智能体这样能省不少 Token。还有一个方向是本地模型。如果对隐私要求高可以把 LLM 换成端侧小模型。Flutter 可以通过平台通道调用 Android 的 NNAPI 或 iOS 的 Core ML。不过端侧模型的能力有限适合做意图识别、简单分类这类轻量任务复杂的规划和生成还是得靠云端。我自己做下来最大的体会是多智能体的难点不在 Agent 本身而在编排和容错。单个 Agent 的代码很简单无非是拼提示、调接口、解析结果。但把多个 Agent 串起来每一步都可能失败每一步的输出都可能不符合预期怎么让整个流程在部分失败的情况下还能给出有意义的结果这才是真正花时间的地方。我的经验是宁可让流程简单一点也不要为了“智能”而引入太多不确定性。三个 Agent 能解决的问题不要上五个。固定的流程能解决的不要上动态规划。先把最小闭环跑通再逐步加复杂度。最后分享一个小技巧在开发阶段给每个 Agent 加一个mock模式返回预设的固定输出。这样调试 UI 和流程逻辑时不用每次都调 LLM速度快很多也省 Token。等流程跑通了再切换到真实 LLM 调用。这个习惯帮我省了大量等待时间。