AI SDK's fx Adapter Refactor: Model Requests Return to the Host Process

Title

AI SDK's fx Adapter Refactor: Model Requests Return to the Host Process

Meta Description

AI SDK's HarnessAgent fx adapter has been refactored: the harness and model requests now run in the same process as the host, while filesystem and shell operations remain isolated in the sandbox. Credentials are no longer forwarded into the sandbox, and new capabilities include built-in tool filtering, mid-turn intervention, structured output, and image tool results.

Article Content

The fx adapter for HarnessAgent in AI SDK has undergone an architectural refactor. The core change is straightforward: the harness and model requests no longer run inside the sandbox but instead run in the same process as the application, while built-in filesystem and shell operations remain isolated and executed within the sandbox. This adjustment is driven by libfx—the TypeScript library for fx—and it also removes a set of sandbox dependencies that were previously required.

From Cross-Sandbox Bridging Back to Same-Process

The old adapter's execution path was more convoluted: it required installing fx inside the sandbox, running a sandbox bridge layer, and exposing a sandbox port for external communication. The new adapter uses libfx to complete harness and model calls directly within the same process, so all three of these dependencies disappear.

What changes accordingly is where credentials are stored. Model credentials stay on the host side and are no longer forwarded into the sandbox. For teams that need to separate sensitive API keys from untrusted code execution environments, this is a boundary adjustment worth noting: credentials no longer cross the sandbox boundary, and the exposure surface is correspondingly narrowed.

Sandbox and Trust Boundaries: In agent systems, a sandbox refers to a restricted execution environment, typically using OS-level isolation (such as containers, namespaces, seccomp, or microVMs) to limit the files, network, and system calls a process can access. Its purpose is to confine the impact within an isolated domain even if the agent executes untrusted code or invokes dangerous commands. "Cross-sandbox bridging" in this article refers to the old architecture where the fx process inside the sandbox and the host application outside the sandbox required an additional channel (such as a port or IPC) to communicate. This increased deployment complexity and expanded the attack surface—the bridge itself became a boundary that needed protection. The new architecture moves "low-risk, credential-requiring" model calls back to the host and keeps "high-risk, credential-free" file and shell operations in the sandbox. This is essentially a re-partitioning of trust domains: credentials and model interaction belong to the trusted domain, while arbitrary code execution belongs to the isolated domain, and the two no longer mix in the same environment.

New Capabilities: Finer Agent Control and Output Constraints

The refactor is not just subtraction. The adapter also adds several capabilities around controlling agent behavior.

Built-in Tool Filtering

You can specify which built-in tools the agent is allowed to use. For scenarios that need to limit the scope of agent behavior—for example, allowing only file reads but not shell execution—this provides an explicit gate.

Mid-Turn Intervention

While a turn is still running, new instructions can be sent to adjust direction. This shifts the agent from a "dispatch task once and wait for the result" model to an interactive mode that can be guided during execution.

Turns and the Agent Loop: In the agent context, a "turn" refers to one complete cycle in which the model receives input, reasons, calls tools, and produces a final response; a single task may include multiple turns. Traditional batch-style invocation is "dispatch task—wait for completion," with no way to change the goal midway. Mid-turn intervention allows new instructions to be injected before the loop ends (such as correcting direction, adding constraints, or stopping a particular tool path), requiring the runtime to support streaming events, interruptible tool execution, and message queues so that humans or upper-layer policies can intervene at key points. This is closely related to "human-in-the-loop" and is an important means of controlling risk and cost when moving agents from demos to production.

Structured Output

Supports generating responses that conform to a specified schema, reducing the need for secondary parsing of free text on the application side.

Structured Output and JSON Schema: Large models return free text by default, and applications often need to parse fields using regex or secondary model calls, which is both fragile and adds latency. Structured output requires the model to generate responses according to a given schema (usually JSON Schema describing field names, types, required fields, and enum constraints). The SDK enforces constraints during decoding (such as constrained decoding, grammar guidance, or validation retries), so the returned result can be directly deserialized into a type-safe object. For agent systems, this means tool call parameters, task planning results, or multi-step decision outputs can be stored or passed downstream in a verifiable format, reducing ambiguity between "what the model said" and "how the program understands it," and making it easier to run regression tests on output contracts in CI.

Image Tool Results

Via toModelOutput(), images can be returned to the model as tool results, extending the return types of tool calls.

Sessions Can Be Resumed Across Processes

The new adapter supports saving and restoring sessions in a new host process. Combined with the design of running the harness on the host side, this means session state is no longer bound to the lifecycle of a particular sandbox instance, and there is still a path to continue the conversation after a process restart.

To upgrade, update from @ai-sdk/harness-fx to the latest version. For specific usage, refer to the official fx harness documentation.

What This Change Means

Moving model requests from the sandbox back to the host is essentially re-drawing the trust boundary: model calls and credentials belong to the trusted domain on the host side, while high-risk operations such as filesystem and shell belong to the isolated domain on the sandbox side. This aligns better with security intuition in real deployments than the previous approach of "stuffing everything into the sandbox."

At the same time, the three capabilities—tool filtering, mid-turn intervention, and structured output—point in the same direction: making agent behavior more constrainable and more predictable. They are not a pile-up of features but the control plane needed to move agents from the demo stage to engineering use.

For projects already using the fx adapter, the migration cost of this refactor is mainly concentrated in the three removed sandbox dependencies; for teams considering introducing sandboxed execution agents, the fact that credentials do not enter the sandbox may be more attractive than the new features.

One-line Summary

fx adapter refactor: harness and model requests return to the same process, credentials no longer enter the sandbox, and several new agent control capabilities are added.

Paragraph Summary

The fx adapter for HarnessAgent in AI SDK has completed an architectural refactor: the harness and model requests no longer run inside the sandbox but execute in the same process as the application, with only filesystem and shell operations remaining isolated in the sandbox. This change is driven by the TypeScript library libfx and removes three dependencies: installing fx inside the sandbox, the sandbox bridge, and exposing a sandbox port. Model credentials also stay on the host side and no longer cross the sandbox boundary. At the same time, new capabilities include built-in tool filtering, mid-turn intervention, structured output, image tool results, and cross-process session restoration, all pointing toward making agent behavior more constrainable and predictable. To upgrade, update @ai-sdk/harness-fx to the latest version.