7.6 落地之前：实践清单与常见陷阱
7.6.1 实践清单与常见陷阱
把 AIoT Agent 从概念推入生产，技术选型与架构设计只是起点。真正的风险藏在运行时细节里：上下文可能串租户，工具参数可能越界，进程重启后可能重复副作用，审批与回执也可能无法追溯。以下清单按照“模型与上下文—能力契约—安全控制—运行时治理—测试发布”检查系统，而不是只检查模型能否调用 Tool。
表7-4：AIoT Agent 工程实践清单
| 检查领域 | 编号 | 检查内容 | 结果 | 备注 |
|---|---|---|---|---|
| 模型选型 | CHK-01 | Provider 协议是否属于当前支持的 OpenAI-compatible 或 Anthropic 类型？ | □通过 □未通过 | ChatClientFactory 会按 Provider 类型选择 OpenAiChatModel 或 AnthropicChatModel；其他协议需新增适配 |
| CHK-02 | 是否在 dc3_model_provider 与 dc3_model_config 中配置并验证了备用模型？ | □是 □否 | 请求可选择模型或回退到默认模型；配置多个 Provider 不等于已经具备自动故障转移 | |
| CHK-03 | 是否规划了简单查询与复杂诊断使用不同模型的路由策略？ | □是 □否 | 这是未来策略设计；当前项目没有按复杂度、成本或敏感标签自动路由的引擎 | |
| 工具设计 | CHK-04 | 每个 @Tool 方法的 description 和 @ToolParam 描述是否明确标注了参数单位、取值范围和典型示例？ | □通过 □未通过 | 模型依赖描述决定是否调用工具。描述含糊会导致该调的没调、不该调的乱调。示意：描述“期望的转速值（单位：rpm，范围 0-3000）”比“期望值”减少模型猜测。 |
| CHK-05 | 只读工具和写入工具是否在工具设计层明确分表？ | □是 □否 | 原理上只读工具在返回中注明“只读”，写入工具在描述中标明“写入操作+风险等级”。 | |
| CHK-06 | 写入工具是否在方法签名层之外做了参数范围校验和类型校验？ | □是 □否 | 示例：写入温度值应限制在 -50~150℃，超出范围直接抛异常拒绝。 | |
| CHK-07 | 每个工具是否包装了现有服务层方法，而非复制业务逻辑？ | □是 □否 | 逻辑一致性依赖单一定义源 | |
| 安全控制 | CHK-08 | 是否所有工具调用都携带并校验租户与用户上下文？ | □是 □否 | ToolContext 注入主体信息，实际授权仍由 Tool 调用的业务层和接口边界保证 |
| CHK-09 | 有副作用操作是否设置了人工确认或外部审批？ | □是 □否 | 当前明确实现的是位号写 Action；批量写、驱动变更和删除尚不能泛化为“内置确认按钮” | |
| CHK-10 | MCP 端点是否启用了 OAuth 2.1 + 工具白名单 + 风险分级？ | □是 □否 | 外部 Agent 接入时，必须做 OAuth 授权方可暴露工具 | |
| 运行时治理 | CHK-11 | 是否用统一 run_id 串联模型、Tool、Action、命令、回执和最终状态？ | □是 □否 | 当前尚无通用 run_id；建设 Runtime 时应先补齐统一执行标识 |
| CHK-12 | 任务状态是否独立于会话持久化，并支持等待确认、失败、取消与人工接管？ | □是 □否 | 会话记忆不能替代长期任务状态机；当前需要新增实现 | |
| CHK-13 | Tool 是否声明超时、重试、幂等、副作用、结果验证和补偿语义？ | □是 □否 | 设备命令通常不可撤回；副作用未知时不得盲目重试 | |
| 日志与审计 | CHK-14 | 每次工具调用是否记录租户 ID、操作时间、输入参数、返回状态和异常堆栈？ | □是 □否 | ToolContext 中已注入租户信息；缺失日志会导致无法追溯故障 |
| CHK-15 | 是否有监控看板展示任务状态、Tool 成功率、超时率、重复副作用和人工接管？ | □是 □否 | 观测单位应从单次模型请求提升为完整任务运行 | |
| 测试与部署 | CHK-16 | 是否用测试替身或隔离环境覆盖典型 Tool Calling 场景？ | □是 □否 | 当前没有通用“模拟模式”开关；测试环境不得连接真实关键设备 |
| CHK-17 | 是否先开放给内测租户和 R0/R1 场景，并设置明确的降级条件？ | □是 □否 | 自主度应按证据逐级开放，不使用全租户统一 Agent 开关 | |
| CHK-18 | 是否演练 Tool 超时、进程重启、回执丢失、重复事件与人工接管？ | □是 □否 | 没有恢复演练，不能进入 Workflow Runtime 或有界自治 | |
| 持续改进 | CHK-19 | 是否在模型、Prompt、Tool Schema 或策略变化后重跑 Agent Eval？ | □是 □否 | 发布门应覆盖结果、轨迹、安全、恢复和成本 |
| CHK-20 | 是否测试长上下文下的工具可见性、证据污染与跨任务记忆隔离？ | □是 □否 | 长对话可能弱化 Tool 描述；任务记忆还必须设置保留与淘汰边界 |
常见陷阱
陷阱 1：过度信任模型输出。 工程师容易把模型的“一本正经”当作“绝对正确”。模型在调用函数时可能填写错误参数，尤其当参数类型依赖它猜测时。规避方式是先校验设备、位号和租户归属，再按平台实际存在的元数据、值域规则和场景白名单检查参数；当前位号写还必须进入 Action 确认。@ToolParam 描述不能替代服务端强校验。这一判断与学术界一致：工业智能体综述（arXiv:2510.17491）在挑战部分同样指出 LLM 的长时序可靠性与实时性不足，不应承担高频控制环内的决策。
陷阱 2：忽略故障补偿。 “设备指令已经下发”本身没有通用撤回按钮。示意场景：未来若开放批量位号写入，若干条可能因通信超时失败，其余已生效。如果没有补偿方案，现场需要人工逐台恢复。规避方式是先校验、分小批执行、逐批确认结果，并为具体设备设计反向命令；当前 Provider 没有批量执行型 CommandTool，不要用不存在的接口说明现状。
陷阱 3：工具参数描述不严谨。 Spring AI 的 @ToolParam 标注本身不包含强校验逻辑。开发者必须在工具方法内部通过 Assert.notNull 或自定义验证器做二次约束。实践中常见的问题是：参数描述写成了“期望的转速值”，但没有明确单位（rpm 还是百分比），导致模型猜错。
陷阱 4：忽略上下文窗口对工具可见性的影响。 随着对话轮次增加，模型的前期 token 被挤压，早期的工具描述很可能被注意力机制遗忘。工程上需要在每轮对话中都注入当前可用的完整工具列表，而不是只在第一轮注入一次。Spring AI 的 ToolCallback 机制默认支持在同一线程内每轮重新注册工具，但开发人员需要在长对话压力测试下确认工具仍然能被正确调用。
陷阱 5：把演进路线写成当前模式开关。 当前实现是显式注册的 Tool、会话记忆和位号写 Action，不存在租户级 agent_mode 或一键切换的完整 Agent/Copilot 产品模式。未来增加编排器时，必须明确设备范围、场景白名单、确认或外部审批节点以及具体补偿策略；不要让模型自行判断并放行风险动作。
7.6.2 延伸参考
本章的知识密度较高，跨了模型原理、工程框架与平台实操三条线。以下资源按“理论→框架→落地”的顺序组织，方便深入时对照查阅。
官方文档与项目仓库
- Spring AI 官方文档：覆盖
ChatClient、Function Calling、对话记忆的配置和核心 API，是集成时的第一案头手册。 - IoT DC3 项目仓库（GitHub: pnoker/iot-dc3）：Agentic 源码的 Tool 注册情况见 7.3.1 节；阅读时应同时检查 Provider 配置，不能仅按类数量判断模型可见工具。
- LangChain 官方文档：提供 RAG 和 Agent 循环的参考实现，可与 Spring AI 的实践对照。
协议与标准
工业智能体综述（Tang et al., 2025）：Empowering Real-World: A Survey on the Technology, Practice, and Evaluation of LLM-driven Industry Agents（arXiv:2510.17491 摘要页）——哈工大（深圳）与华为 2025 年 10 月联合发布，系统梳理工业智能体的记忆/规划/工具三支柱演进、L1–L5 能力成熟度、评测方法与六大落地域。其中"LLM 实时性不足、不应进入高频控制环"的结论与本章"模型不进实时环、确定性兜底"的边界表述一致；评测三重矛盾（真实性 vs 可复现、成本 vs 效率、隐私 vs 数据质量）可与 7.5.4 对照阅读。
MCP（Model Context Protocol）：定义了模型与外部资源间的标准化接口，已于 2025 年 12 月捐赠给 Linux 基金会旗下的 Agentic AI Foundation，成为智能体接入工具时广泛采用的事实标准之一。IoT DC3 的 MCP 网关是此规范的工程落地示例；MCP 的协议层次与标准演进详见第 9 章 9.5 节。
OpenAI Chat Completions 与 Anthropic Messages API 规范：IoT DC3 当前分别通过 OpenAI-compatible 与 Anthropic Provider 接入。理解各自的 Tool Calling 协议与参数差异，有助于排查模型切换后的工具调用问题。
核心论文与框架代码
- 《ReAct: Synergizing Reasoning and Acting in Language Models》：Agent 领域的奠基论文。本章 Agentic Center 架构中的思考‑行动循环源自此项工作。
- Spring AI 官方示例工程：GitHub 上
spring-projects/spring-ai下的示范工程，提供可直接运行的最小原型。
私有化部署
- Ollama：本地模型部署的起点。支持 DeepSeek、Qwen 等模型的单机加载，暴露 OpenAI 兼容端点，适合敏感数据本地化验证。
- vLLM：生产级推理加速方案，提供 PagedAttention 优化和连续批处理。
建议阅读顺序：先通读 ReAct 论文，理解 Agent 循环；再跟 Spring AI 官方文档写一个“查询设备温度”的 ChatClient 原型；然后啃 IoT DC3 的 Agentic Center 源码，重点看 DeviceTool 和 PointValueTool 的安全上下文注入方式。每步都能与本章内容对照验证。
到这里，Agent 已能读取上下文、调用受控工具并生成候选动作，但“能调用”还不等于“应该获准”。第 8 章将把身份、最小权限、数据保护、确认和审计放到同一条调用链上，为本章的概率性能力建立不可绕过的确定性边界。
用四个词标记本章的位置：“推理”在这里落地，且带着它的边界——只产生候选；“行动”则刚拿到准入规则，完整的确定性边界在下一章合拢。