在建立一款真正可落地的 Flutter Agent 时最常见的痛点是：缺乏从零到完整的工程实例。说起来，许多人只看到官方示例，却不知如何把它们映射到自己的业务场景。下面通过一个完整的 GenKit-Flutter 方案。帮你快速搭建公司级 Agent，并解决常见痛点。

1️⃣ 先说说为什么要用 GenKit

GenKit-Dart 是 Google 官方为 Flutter 提供的 Agent SDK，几乎是唯一可直接使用的选择。它与 LangChain 类似，但更轻量、更贴合 Flutter 开发流程。

• 主要能力模型、Prompt、工具、RAG、结构化输出、观测、评测、部署等全部集成。老实说，
• Flow 思路GenKit 用 Flow 而不是 Chain 来组织 AI 业务逻辑。强调“把业务拆成可验证函数”。这也是使用者经常困惑的地方——“为什么不直接用 Chain？”因为 Flow 更适合描述状态流和调试过程。

再看痛点一，Chain 与 Flow 的区别导致实现难度上升

很多人习惯 LangChain 的链式调用。但在 GenKit 中，一切围绕 Flow 才能得到类型校验、追踪和部署支持。 理解这一点后就能更快地把业务拆成可复用模块。

2️⃣ 建立完整的数据流图

在实际项目里我们会把一次交互拆成若干 Turn 并通过 Flow 编排。说起来，每个 Turn 包含：

• intent
• requiredToolNames / forbiddenToolNames / candidateToolNames
• activeSkillIds
• modelCapabilities

痛点二这方面。如何让模型知道哪些工具可用/不可用？

A+B+C 的三集合模式解决了这个问题：模型只需要接收到“必须使用某些工具”或“不允许使用某些工具”的提示，而不必自己去判断隐私或权限。

3️⃣ Turn Plan 与 Execution Plan 的设计原则

Plan = Intent + Tool Set + Hint

4️⃣ Prompt 模板管理

Dart 层只负责注入变量；模板本身保持极简，只包含 {{systemInstruction}} 等占位符。从而避免语言死结和逻辑混杂。

• The prompt is generated at runtime via PromptMessages.systemInstruction.
• The system uses “双预算裁剪”：先按字符数粗筛。再按 token 数细调，确保使用者输入永不被截断。
• Pretend you’re a designer who hates hard‑coded Chinese strings—use i18n everywhere.
• A single prompt can be versioned via YAML frontmatter,so you can edit text without touching code.
.
• *If you have multiple locales and your prompts are mis‑aligned*—you’ll see weird outputs in or languages. This is a common debugging nightmare solved by this approach.

5️⃣ 状态机 & 并发控制

6️⃣ Agent Loop — 别自己写循环!

• Dart side never runs a while loop;let GenKit handle it via ai.generateStream.
`
• If tool call fails or context overflows,we throw exceptions that higher layers catch and retry automatically . • Required tool missing → _GenkitToolRequiredException • Context overflow → runCompleteContextOverflowRetries • Truncated answer → stream_continuation_instruction or _synsizeAnswerFromToolResults The Prefill mechanism runs non‑mutating tools once before first round so that model sees grounding facts immediately. The key principle:*Loop stays inside GenKit;Dart only supplies boundary checks.*

  7️⃣ 工具定义 & 信任矩阵

  This is where most teams hit a wall because y try to hard‑code logic instead of using declarative metadata.. If you skip this step you’ll end up with unsafe calls or missed de‑sensitization in production!

  维度	字段	语义
  Schema inputJsonSchema & validateInput	严格 + additionalProperties:false 副作用级别 : readOnly/idempotent/mutating/externalAction 并行性 : only readOnly+parallelSafe can be parallel 风险 : low/medium/high 隐私 网络 预算+trimResultContent	runtime 决策依据 – ToolBroker 根据这些字段决定是否并行、是否脱敏、是否审批等。
  The trust × side effect matrix defines what tools can run automatically vs requiring approval:   @localTrusted ✅ auto ✅ auto ⚠️审批 ❌拒绝      @hostTrusted ✅ auto ✅ auto ⚠️审批 ⚠️ 审批      @externalUntrusted ✅ auto ⚠️ 审批 ❌ 拒绝 ❌ 拒绝     Trust \ SideEffect readOnly idempotent mutating externalAction If you downgrade an internal tool to externalUntrusted but it still uses network access,its result must be redacted before feeding back to model. If your team keeps “auto‑run everything” without this matrix you’ll face silent data leaks in logs or responses. ### RAG Strategy - **knowledge_search** – static docs - **local_data_summary** – dynamic data like orders - **web_search + fetch_url** – internet - **memory_get** – long‑term memory Each channel is decoupled through its own provider interface so you can swap any one out without breaking ors. In practice I use four retrievers: * hashLexical * bm25 * hybrid * embedding + hybridEmbedding and an RRF fusion layer that mixes raw scores with rank-based penalties for 娱乐ter recall across modalities. ### 💡 常见 RAG 痛点： | Problem | Fix | |---------|-----| | BM25 poor on Chinese | Generate n‑gram tokens for all substrings | | Missing fact due to wrong query | Query rewrite into multiple variants | | Overlap hits from same source | Source diversity reranker limits K chunks per source | --- 8️⃣ Trace & 可观测性