AI SDK的fx适配器重构：模型请求回归主机进程

AI SDK 中 HarnessAgent 的 fx 适配器迎来一次架构级重构。核心变化很直接：harness 与模型请求不再跑在沙箱里，而是与应用运行在同一进程中；内置的文件系统与 shell 操作仍被隔离在沙箱内执行。这一调整由 libfx——fx 的 TypeScript 库——驱动，同时也移除了一批过去必须存在的沙箱依赖。

从跨沙箱桥接回到同进程

旧版适配器的运行路径更绕：需要在沙箱内部安装 fx、运行一层 sandbox bridge，还要暴露一个沙箱端口供外部通信。新适配器借助 libfx 直接在同进程内完成 harness 与模型调用，因此这三项依赖全部消失。

随之改变的是凭证的存放位置。模型凭证留在主机侧，不再被转发进沙箱。对于需要把敏感 API Key 与不受信代码执行环境隔开的团队，这是一项值得关注的边界调整：凭证不再穿越沙箱边界，暴露面相应收窄。

沙箱（Sandbox）与信任边界：在代理（Agent）系统中，沙箱指一种受限的执行环境，通常通过操作系统级隔离（如容器、命名空间、seccomp 或 microVM）限制进程能访问的文件、网络与系统调用。其目的是即使代理执行了不受信代码或调用了危险命令，影响也被限制在隔离域内。文中“跨沙箱桥接”指旧架构下，沙箱内的 fx 进程与沙箱外的主机应用之间需要额外通道（如端口、IPC）通信，这既增加部署复杂度，也扩大了攻击面——桥接本身成为需要防护的边界。新架构把“低风险、需凭证”的模型调用放回主机，把“高风险、无需凭证”的文件与 shell 操作留在沙箱，本质上是对信任域的重新划分：凭证与模型交互属于可信域，任意代码执行属于隔离域，两者不再混在同一环境内。

新增能力：更细的代理控制与输出约束

重构并非只做减法。适配器同时补齐了几项围绕代理行为控制的能力。

内置工具过滤

可以指定代理允许使用哪些内置工具。对于需要限制代理行为范围的场景——例如仅允许读取文件而不允许执行 shell——这提供了一道显式闸门。

回合中途干预

在一个回合仍在运行时，可以发送新的指令来调整方向。这让代理从“一次性下发任务、等待结果”的模式，转向可在执行过程中被引导的交互模式。

回合（Turn）与代理循环：在代理语境中，“回合”指模型从接收输入、推理、调用工具到产出最终回复的一次完整循环；一次任务可能包含多个回合。传统批处理式调用是“下发任务—等待完成”，中途无法改变目标。回合中途干预允许在循环尚未结束时注入新指令（如修正方向、追加约束、叫停某条工具路径），要求运行时支持流式事件、可中断的工具执行与消息队列，使人类或上层策略能在关键节点介入。这与“人在回路”（human-in-the-loop）密切相关，是把代理从演示推向生产时控制风险与成本的重要手段。

结构化输出

支持生成符合指定 schema 的响应，减少了在应用侧对自由文本做二次解析的需要。

结构化输出（Structured Output）与 JSON Schema：大模型默认返回自由文本，应用侧往往需要用正则或二次模型调用解析出字段，既脆弱又增加延迟。结构化输出要求模型按给定 schema（通常以 JSON Schema 描述字段名、类型、必填项与枚举约束）生成响应，SDK 在解码阶段施加约束（如受限解码、语法引导或校验重试），使返回结果可直接反序列化为类型安全的对象。对代理系统而言，这意味着工具调用参数、任务规划结果或多步决策输出都能以可校验的格式落库或传给下游，减少“模型说了什么、程序怎么理解”之间的歧义，也便于在 CI 中对输出契约做回归测试。

图像工具结果

通过 toModelOutput() 可以把图像作为工具结果返回给模型，扩展了工具调用的返回类型。

会话可跨进程恢复

新的适配器支持在新主机进程中保存并恢复会话。结合主机侧运行 harness 的设计，这意味着会话状态不再被绑定在某个沙箱实例的生命周期上，进程重启后仍有继续对话的路径。

升级方式是从 @ai-sdk/harness-fx 更新到最新版本，具体用法可参考 fx harness 的官方文档。

这次改动意味着什么

把模型请求从沙箱挪回主机，本质上是在重新划分信任边界：模型调用与凭证属于主机侧的可信域，文件系统与 shell 这类高风险操作属于沙箱侧的隔离域。这比过去“什么都塞进沙箱”的做法更贴合实际部署中的安全直觉。

同时，工具过滤、中途干预与结构化输出这三项能力，指向的是同一个方向——让代理的行为更可约束、更可预测。它们不是能力上的堆叠，而是把代理从演示阶段推向工程化使用所需的控制面。

对于已经在使用 fx 适配器的项目，这次重构带来的迁移成本主要集中在那三条被移除的沙箱依赖上；而对于考虑引入沙箱执行代理的团队，凭证不进入沙箱这一点，可能比新增功能更具吸引力。