这两年做 Flutter 的开发者想接大模型，应该都有过一种拧巴的感觉：在 Dart 里裸调 HTTP 拼 JSON，请求倒是发出去了，但模型返回的文本怎么清洗、怎么重试、怎么让模型自己决定要不要“调用工具”，全得自己造轮子。社区里倒是有几个被放弃的封装库，装完依赖才发现连流式响应都支持不完整。谷歌自己维护的 Genkit 在服务端生态里口碑不错，但官方长期只有 Node.js 版本，Dart 只能靠社区移植的预览包撑着，API 一个季度变一次，压根不敢上生产。一直到 Genkit Dart 1.0 正式发布，“Flutter 原生写 AI Agent”这件事才真正闭环。
这篇不聊发布会上的漂亮话，直接从 Flutter 开发者的视角拆开看：Genkit Dart 到底是什么、1.0 究竟完整在了哪、怎么把第一个 Agent 跑起来，以及我实测过程中踩过的那些坑。
1. Genkit Dart 到底是什么：一个纯 Dart 的 AI 编排框架
1.1 一句话讲清楚定位
Genkit Dart 不是一个“ChatGPT 套壳 SDK”，而是一个 AI 应用编排框架。英文叫 orchestration framework，翻译成人话就是：它帮你把“调模型、传上下文、调用工具、解析结构化输出、记录每次调用日志”这一整条链路串起来。
以前你在 Flutter 里写 AI 功能，是自己在拼积木；用了这个框架之后，积木之间的接口已经对好了，你只需要决定“放哪块积木、放几块”。模型提供商是积木，工具函数是积木，输出解析器是积木，甚至自定义的 Agent 行为逻辑也是积木。
这里要注意“编排”两个字的分量。它意味着 Genkit 不只是把chat.completions这样的底层接口翻译成 Dart，而是把一个 Agent 应用需要的完整生命周期都抽象好了：请求前怎么组装提示词，请求中怎么处理流式数据，请求后怎么验证输出格式，出错怎么降级重试，整个过程每一步都记录到 trace 里。
1.2 从预览到 1.0：这次“完整”到底完整在哪
“终于完整了”这个说法，只有被预览版折腾过的人才笑得出来。我印象里预览版的几次变化到现在还记忆犹新：
- 最初版的配置方式是全局单例，后来又改成了依赖注入风格，再后来抽象出了
Genkit实例对象。 - 工具的定义接口来回改过好几轮，
Tool、Flow、Agent之间的边界一度模糊。 - 流式输出接口在前几个版本里甚至会因为并发请求导致响应错乱。
1.0 版本把这些都收敛了。从发布公告和变更记录来看，有四个标志性变化最能说明“完整”：
第一，API 冻结。genkit、genkit_openai、genkit_googleai这些核心包统一到了 1.0 版本号，后续只做兼容性修复和增量扩展，不会再出现大面积命名推翻。
第二，工具协议重新设计。工具定义从“JSON Schema 参数”升级为完整的输入输出 Schema 描述，Agent 在决定调用工具时，可以更准确地理解参数结构和返回类型，减少模型“猜”的概率。
第三，官方补齐了 Trace 和调试面板的 Dart 接入。以前你只能靠print看大模型输出了什么，现在每次调用、每个工具执行、每段 token 的产出过程都能在一套可视化的 Trace 流里看。
第四，测试工具链成型。提供了FakeModel、InMemorySpanRecorder等测试组件，可以在不联网、不花钱的情况下，用固定返回数据来验证你的 Agent 逻辑是否正确。
1.3 适合谁用，我的判断
如果你属于下面这三类人，我建议认真试试：
第一类是 Flutter 应用开发者，想在 App 里直接接入模型能力，但不想花大量时间处理底层协议细节。Genkit Dart 开箱即用，环境变量配好模型密钥，写一个 Agent 对象就能跑。
第二类是做 AI 应用产品原型的团队。用 Dart 全家桶写客户端，服务端暂时不想接 Node.js，可以先在客户端把 Agent 逻辑跑通，之后需要时再平滑迁到云端。
第三类是技术敏感型开发者，想深度控制模型调用链路的。因为框架本身是开源的，每一层抽象都能往下钻，关键时刻可以自行修改甚至替换底层实现。
反过来，如果你的目标是做大规模线上高并发服务，那 Genkit Dart 1.0 本身是支持部署到服务端的，架构上没问题，只是运维和弹性伸缩还是得按后端服务的标准来准备，不能只把它当成客户端工具。
2. 为什么“原生”很重要：Flutter 写 Agent 的三种姿势对比
2.1 三种写 AI 的姿势：裸调、封装、原生
很多开发者会问：我直接在 Flutter 里用http包调大模型 API，不也能写 Agent 吗？能，但要看你愿意花多少成本。我梳理一下目前常见的三种姿势，对比着看会清楚。
裸调用方式，是指你直接用http.post发送请求，手动拼接 JSON body，手动解析流式 chunk。这种方式最灵活，但也最容易失控。Agent 场景里最难搞的是“函数调用循环”：模型返回一个工具调用意图，你的代码要执行工具、把结果塞回下一个请求，再让模型继续推理。这个循环用裸请求实现，代码会迅速膨胀成一座难维护的屎山，而且没有日志系统，出错基本靠猜。
社区兜封装方式，是指依赖某些个人开发者写的 SDK。这在小需求场景下很高效，但风险在于维护者随时可能弃坑，API 变更没人跟进，遇到学院派的模型提供商接口升级，你只能自己动手修依赖。我见过好几个项目就是因为底层库停更，被迫回退到裸调用。
原生框架方式，就是 Genkit Dart 这种由核心团队维护、与官方模型 SDK 同步更新的方案。它把最复杂的部分——多提供商抽象、函数调用循环、自动重试、输出解析、可观测性——都提前设计好了。你写的不是一次次 HTTP 请求，而是一个个声明式的组件，框架帮你编排执行顺序和数据流。
2.2 Genkit 的架构分层与设计思路
Genkit Dart 的架构分四层，从底往上分别是：模型抽象层、工具与数据层、Agent 编排层、界面应用层。
模型抽象层定义了统一接口GenerativeModel。不管你接的是谷歌的 Gemini、OpenAI 兼容接口还是本地模型，只要你实现了这个接口，上层代码就不需要感知具体模型差异。我告诉你一个细节：这种做法的好处是，哪天你想从 A 模型切到 B 模型，只需要改初始化时的模型实例，Agent 逻辑一行不动。
工具与数据层是 Genkit 最有设计感的部分。工具就是带 Schema 声明的异步函数。它跟普通函数最大的区别是：普通函数是程序员调用，工具是模型调用。为了让模型能正确理解该不该调用、参数怎么写、返回值什么格式，工具描述里包含了 name、description、inputSchema、outputSchema。模型把“用什么工具、填什么参数”以结构化数据返回，框架负责派发到对应函数执行。
Agent 编排层是 1.0 的核心。它内置了一个循环：模型推理 -> 检测是否请求工具 -> 执行工具 -> 把结果作为系统消息反馈给模型 -> 继续推理 -> 直到模型给出最终答案。这个 loop 看起来简单，实际调教过的大模型都知道难在哪里：循环得有最大次数限制、得处理某次工具调用失败的反馈、得防止模型被工具结果带偏跑题。Genkit 全部封装好了，你要做的只是设置参数。
界面应用层是 Flutter 真正发挥优势的地方。Genkit 的流式输出接口直接返回Stream，这意味着你可以非常自然地把模型输出接到 UI 上：setState中不断追加 token，界面就会实时展示打字机效果，不需要额外做状态同步。
2.3 和主流方案对比：选型不是跟风
市面上能写 Agent 的框架不少，像 LangChain、LlamaIndex 这些 Python/JS 生态的老牌框架，还有 Vercel AI SDK 在 JS/TS 世界的强势地位。
Genkit Dart 和它们最大的差异在于语言生态和运行环境。
如果你正在做纯 Flutter 应用，后端没有任何服务，用 LangChain 意味着你得先搭一套 Node.js 或 Python 服务，再想办法让 Flutter 去调用。这里就涉及谁写 Agent 逻辑的问题：让移动端工程师去维护一套 Python 后端代码，团队协作成本很高。Genkit Dart 的优势是 Flutter 工程师用 Dart 就能完成 Agent 开发，前后端语言统一，不需要跨语言转译。
当然，Genkit Dart 也有不擅长的场景。如果你需要海量向量知识库、复杂 RAG 管线、成熟的 Agent 框架生态，那 Python 生态依然是更成熟的选择。Genkit Dart 适合的是“轻到中型 AI 应用”，把模型接进来、配上几个工具、做结构化输出，这一系列需求用它是舒舒服服的；真要做大规模微调、数据管道、复杂检索系统，老老实实上专业后端框架。
3. 上手实操：把第一个 Agent 跑起来
3.1 环境准备与依赖配置
先交代一下我的实测环境：Flutter 3.24 及以上版本，Dart 3.6 及以上版本，平台以 Android、iOS、Web 为主。如果你还在用很老版本的 Flutter，建议先升级再试，否则可能遇到依赖解析冲突。
在pubspec.yaml里添加依赖：
environment: sdk: ">=3.6.0 <4.0.0" dependencies: flutter: sdk: flutter genkit: ^1.0.0 genkit_googleai: ^1.0.0 # 按需添加，这边以 Gemini 模型为例运行flutter pub get。装完后在项目根目录创建.env文件（或者通过--dart-define传参的方式），写入你的模型 API Key：
GOOGLE_AI_API_KEY=你的密钥我建议用flutter_dotenv包来加载.env，注意把.env文件加进.gitignore，否则密钥一旦传到公共仓库就很被动。另一个细节是：密钥不要硬编码在 Dart 代码里，编译产物反编译后是能搜到明文密钥的。
3.2 定义第一个模型
在 1.0 中，模型的初始化方式是这样的：
import 'package:genkit/genkit.dart'; import 'package:genkit_googleai/genkit_googleai.dart'; final genkit = Genkit(); Future<GenerativeModel> setupModel() async { final googleAI = GoogleAI(apiKey: Platform.environment['GOOGLE_AI_API_KEY']); genkit.registerProvider(googleAI); final model = await genkit.getGenerativeModel( provider: 'googleAI', name: 'gemini-2.0-flash', ); return model; }有几点说明一下。getGenerativeModel返回的是一个代理对象，它在底层帮你处理了模型请求的连接池、重试、版本兼容。如果你的项目以后要切换模型，比如从 flash 版换成 pro 版，只需要改动 name 参数，其他地方全部不用碰。
我第一次上手时的感受是：这个初始化步骤相对简单，难的反而是后续理解 Agent 循环。
3.3 给 Agent 装一个工具
工具是让 Agent 从“聊天机器人”进化为“能办事的助手”的关键。以一个查天气工具为例：
final weatherTool = Tool.json( name: 'get_weather', description: '查询任意城市的当前气温，入参为城市名称，返回摄氏度温度。', inputSchema: { 'type': 'object', 'properties': { 'city': {'type': 'string', 'description': '城市名，比如 杭州'}, }, 'required': ['city'], }, outputSchema: { 'type': 'object', 'properties': { 'temperature': {'type': 'number'}, }, }, execute: (params) async { // 真实项目里这里要调用天气服务 API return {'temperature': 26}; }, );这里有两处容易踩坑的地方。第一，description 一定要写清楚“该工具是做什么的、入参含义、返回值含义”，因为模型是通过文本来理解工具语义的，描述越精确，误调用概率越低。第二，outputSchema 里能约束返回结构，但如果你真的把结构化数据渲染回模型提示词时，框架会有默认处理，建议返回的数据本身保持简洁，不要塞一坨无关字段。
3.4 创建一个 Agent 并跑通对话
准备好模型和工具，就可以创建 Agent 了：
final agent = Agent( genkit: genkit, model: model, tools: [weatherTool], systemPrompt: '你是一个贴心的天气助手。当用户询问天气时，请先使用 get_weather 工具查询，查询完成后用一句话回答。', maxIterations: 5, ); final response = await agent.generate('杭州今天多少度？'); print(response.text);运行这段代码后，Genkit 会按以下流程走：
- 把“杭州今天多少度”和系统提示词拼在一起交给模型。
- 模型判断需要获取天气数据，于是返回一个结构化工具调用意图。
- Genkit 自动调用
execute函数，得到{'temperature': 26}。 - 框架把工具结果回传给模型，模型根据结果生成最终回答。
你看到的最终输出是一句话，但在 trace 里能看到完整的调用链。这里有一个早期容易忽视的点：maxIterations不要设得太小。如果你的 Agent 需要连续调用多个工具才能完成一个复杂任务，比如查天气后再查空气质量，那一次对话可能需要 3 到 4 次工具往返。设成 3 可能刚好不够，我一般建议业务初始设为 5 或 8，稳定后再根据实际场景收紧。
3.5 流式输出：把打字机效果接进 UI
用户不喜欢等模型把一整段话生成完再看到结果。把生成过程改成流式，体验会好很多：
final stream = agent.generateStream('杭州今天多少度？'); await for (final chunk in stream) { setState(() { _answer += chunk.text; }); }generateStream返回一个Stream<GenerationChunk>，每个 chunk 携带一批文本增量。把这个流直接接进 UI 的文本状态就行。有一点要提醒：Flutter 的setState不能太频繁，如果 chunk 频率非常高，建议做节流或批量更新，避免小屏设备掉帧。
另外，1.0 里流式接口的chunk.text属性在个别模型提供商下可能返回空字符串（比如某些模型只在流结束时给出完整结果）。为了兼容这种边界情况，建议保留一个fullText的累计拼接逻辑，最后用累计值覆盖最终界面显示。
3.6 结构化输出：让 Agent 返回能直接用的 JSON
很多业务场景下，我们不想让模型输出自由文本，而是希望它返回实体数据。比如做一个“简历信息提取”功能，希望从一段文本里抽出姓名、年龄、技能列表。
Genkit 提供了输出解析器，配合 JSON Schema 做约束：
class Profile { final String name; final int age; final List<String> skills; Profile({required this.name, required this.age, required this.skills}); factory Profile.fromJson(Map<String, dynamic> json) => Profile( name: json['name'] as String, age: json['age'] as int, skills: (json['skills'] as List).cast<String>(), ); } final response = await agent.generate( '从一个简历文本中提取用户画像：王小明，28 岁，熟悉 Flutter、Go、Docker', outputFormat: JsonOutputParser<Profile>(Profile.fromJson), ); final profile = response.output;这里有一个很隐蔽的坑：模型返回的“JSON”有时候会被 markdown 代码块包裹，比如json ...这种格式，导致jsonDecode直接报错。Genkit 的输出解析器已经内置了大部分清洗逻辑，如果你是自己写解析，一定要记得先剥离代码块标记。实测下来，遇到这种问题优先检查是不是模型的 temperature 设置太高（建议稳定任务设为 0.2 左右），再检查调试一下 model 返回的原始文本格式。
4. 核心能力拆解：1.0 真正补齐的五块拼图
4.1 工具调用循环：Agent 是怎么“跑起来”的
Agent 和普通对话机器人最大的区别是能不能“自己决定用工具”。1.0 在工具调用循环上做得很扎实。
整个循环在框架内部是这样实现的：
- 构建消息序列，加入系统提示和用户输入。
- 调用模型，得到一个生成结果。如果结果中包含
toolCalls字段，说明模型想要调用工具。 - 框架遍历每个工具调用请求，校验其参数是否符合对应工具的
inputSchema，符合才派发到execute。 - 执行完成后，框架把工具结果序列化为一条
toolResponse消息，追加到会话历史。 - 带着新消息再次调用模型，重复第 2 步，直到模型不再请求工具，生成最终文本。
这个机制实现起来本身不复杂，难的是处理异常路径。比如工具抛异常了怎么办？Genkit 的做法是捕获异常，把错误信息作为工具结果回传给模型，让模型自己决定是换一种参数重试还是向用户说明失败。这种设计虽然初看有点绕，但实测比直接在 Agent 层中断要好得多，因为模型能根据错误信息自我纠正，不需要你硬编码一堆try-catch。
参数校验也很关键。假设模型返回了一个{'city': 12345}而不是字符串，如果直接执行工具，很可能因为类型不对崩在运行时。Genkit 在 1.0 里对工具参数做了严格校验，不匹配的调用请求会在进入 execute 之前就被拦截，并在 trace 里标记为一个警告，这就能让你快速定位是不是工具 description 写得有歧义。
4.2 trace 调试：一套看完调用全链路
我最喜欢的 1.0 新特性就是 trace 调试面板。
过去在 Flutter 里调试 AI 功能，基本靠print大法：在请求前打印 prompt、在响应后打印输出、在工具执行时打印参数和返回。一旦对话轮次变多，print 出来的东西根本对不上号，你不知道哪次工具调用结果是哪一轮对话产生的。
Genkit 提供的 trace 机制不一样。每次generate或generateStream调用都会生成一条 trace 记录，里面包含了：
- 完整的提示词，包括系统提示、用户消息、历史上下文。
- 模型返回的中间结果，尤其是工具调用请求的结构化数据。
- 每个工具的执行耗时、入参、出参、是否有异常。
- 模型最终输出的完整内容和每个 token 的耗时分布。
- 整个调用链路的总延迟和 token 消耗量。
在调试模式下，你可以在开发期打开调试面板实时查看这些数据。调试完成后，也可以把 trace 导出，放进持续集成里做回归。
这个能力对 Agent 项目的价值怎么强调都不为过。因为 Agent 行为是“非确定性”的，同一段输入可能每次都产生不同的内部路径，如果没有 trace，你根本复现不了问题。有了 trace，你可以针对某一条失败的调用链逐段分析：到底是提示词没写清楚、工具描述有歧义，还是模型本来就不该调用这个工具。
4.3 从客户端到服务端：什么时候拆成后端
很多 Flutter 工程师容易陷入一个误区：既然 Genkit Dart 能在客户端跑，那是不是所有逻辑都塞客户端就完事了？
现实没那么简单。你把 API Key 放进客户端，用户逆向 App 后可以直接提取，然后拿你的 Key 去刷模型接口，账单直接炸掉。密钥安全是第一个必须考虑的问题。哪怕你不在乎密钥泄露，客户端的模型调用频率也很不可控，容易被滥用。
所以我的建议是分层处理：
- 纯展示型的、不需要敏感数据的轻量任务，比如“润色一段文本”“把一段口语转换为书面语”，可以走客户端直连，用户体验好，实时性强。
- 涉及私有业务数据、用户个人信息、需要审计日志的任务，必须放到后端服务上。客户端把请求发给你的后端接口，由后端持有密钥、调用模型、做权限校验，再把结果返回给客户端。
在这种架构下，Genkit Dart 同样适用，只是它的角色变了：后端用 Dart 写一个服务，部署在云端，客户端通过 API 与它通信。这样做的好处是，Agent 逻辑本身还是你用 Dart 写的那套代码，不需要切成另一种语言后端，团队心智负担大大降低。
我在实际项目中是这么拆的：把 Agent 定义放在一个独立的 Dart 包（agent_core）里，Flutter App 直接引用这个包，服务端也引用同一份包，两端共用 Agent 逻辑，只是入口一个是 UI 层，一个是 API 层。这样既保住了客户端体验，也保住了密钥安全。
5. 常见问题与排查实录：我踩过的坑
5.1 常见问题速查表
整理一份我在预览版和 1.0 实测过程中遇到的典型问题，适合先收藏再看：
| 问题现象 | 可能原因 | 解决方式 |
|---|---|---|
调用generate后长时间无响应 | 网络超时或代理配置异常 | 检查网络连通性，设置合理的timeout参数，并用 trace 看请求耗时分布 |
| Agent 不调用工具，直接瞎编答案 | 工具 description 太模糊，或systemPrompt没强调必须使用工具 | 重写工具描述，明确说明“当遇到 X 场景时必须调用 Y 工具” |
| 模型返回的 JSON 带 markdown 代码块 | 模型本身的行为差异，或temperature过高 | 使用 Genkit 内置输出解析器，或把 temperature 调到 0.2 左右 |
| 工具循环无限跑不到头 | maxIterations设置过大，或工具结果让模型无法收敛 | 收窄 maxIterations 到 5 以内；检查是否两个工具互相触发形成死循环 |
jsonDecode报错 | 输出被截断，或模型输出不是合法 JSON | 开启流式模式并做完整性校验；在输出解析前增加字符串后处理，如截取首个{到最后一个} |
| Android 上请求网络时报错 | 缺少INTERNET权限 | 在AndroidManifest.xml声明的 application 里加<uses-permission android:name="android.permission.INTERNET"/>（实际要加在 manifest 根节点） |
| 切换模型后输出风格变化很大 | 不同模型对系统提示的遵从度不同 | 调整系统提示措辞，按模型的格式偏好微调提示模板 |
5.2 三个容易被忽略的细节
第一，关于工具返回数据的格式。很多开发者喜欢在工具里返回一整个复杂对象，比如天气助手返回了湿度、气压、风向、空气质量指数等十几个字段。这些字段全部会拼进模型的下一次上下文中，会白白消耗 token 数量，而且关键信息反而被淹没。我建议工具返回只保留必要字段，能用一句话描述的绝不返回整表。
第二，关于并发测试。Agent 工具调用是按顺序串行执行的，但模型请求本身可以并发。如果你在一个工具流程里又嵌套调用了另一个generate，要注意 Genkit 对并发的限制，否则可能把模型服务的限流给触发。
第三，关于 hot reload。在很多 Flutter 版本上，改完Agent定义代码后做热重载，可能会发现新代码没生效。这是因为Agent对象持有的模型连接和会话状态是内存态。热重载不会重置这些状态，建议在调试 Agent 逻辑时使用hot restart而不是hot reload，否则你会被“改了这么多怎么行为没变”这个问题折磨半天。
5.3 两个容易被遗漏的配置项
除了上面速查表里整理的问题，1.0 里还有两个配置项，官方文档写得很低调，但实际用起来特别有用。
第一个是Temperature。在初始化模型时，可以通过一个配置对象传入生成参数，而不是每次调用单独指定。比如，你希望这个 Agent 偏向稳定、严格的 JSON 输出，就把 temperature 固定在 0.1 或 0.2；如果偏向创意文案，就把它放到 0.8 左右。这个参数往往是决定 Agent 跑偏与否的关键。
第二个是maxOutputTokens。模型默认的输出长度上限有时候会限制结构化输出的完整性。比如你要生成一份长报告，输出在中途被截断，生成的 JSON 不完整，解析自然失败。我建议对可能产生长文本的 Agent 提前调大上限。代价是单次请求延迟变高，需要结合业务场景做权衡。
6. 一些操作上的个人体会
6.1 我建议的落地路径
如果你现在手头有一个 Flutter 项目，想引入 AI 能力，我建议按这个顺序推进：
第一周先跑通一个最简单的单轮对话，不接工具，不搞流式，先确认模型网络链路通、密钥配置对。这一步的目的是把所有环境层面的问题先暴露干净。
第二周给 Agent 接一个对你业务真正有用的工具，做好 trace 调试，把工具调用的路径理清楚。这一步可以顺手把输出稳定性调好——把你想要的输出格式用systemPrompt写清楚，配合结构化输出解析器。
第三周再上流式输出和 UI 层的状态管理。之后根据业务需要决定是否把 Agent 逻辑拆到服务端。这个节奏比较稳，每一步都有明确的检验标准，不会一上来就被 Agent 循环的各种边界情况劝退。
6.2 心理预期管理
还有一个想多说两句的体会：1.0 的“完整”指的是框架能力的完整，不代表“AI 功能开箱即用”。模型调用本身就是不确定的，哪怕你用同样的提示词和工具，两次跑出来的结果都可能不一样。这不是框架的问题，是大模型本身的固有特性。
所以调试 Agent 时不要陷入“为什么这次没走对路径”的钻牛角尖。正确做法是：尽量用确定性强的方式约束模型行为，比如清晰的 system prompt、严格的结构化输出、低 temperature；然后通过 trace 去对比不同路径的消息序列，找到偏差的源头再改。
另外，不管你用哪个模型，都建议在完成开发后补充一套简单的自动化测试，用假模型固定返回数据，验证你的工具调度逻辑和输出解析逻辑是否正确。这比每次手工跑对话验证要高效得多。
最后再分享一个小技巧：在Agent的systemPrompt里，把产品对回答风格的要求写得像一个“人设”，而不是冷冰冰的几条规定。模型对这种提示词的遵从度比想象中高得多，实测下来，给 Agent 做一个简洁的人设设定，能让输出质量和稳定性明显提升，这也是我最近几次项目里最省力的调优手段。
