From Filesystem to Agent Workbench

In Cloudflare Computer, an agent workbench is not created by exposing the biggest shell available. It is created by placing bounded model-facing tools around the durable Workspace, then adding Git, imported data, versioned handoffs, or published files only where the task needs them. This chapter shows how those capabilities cross the host boundary and why dedicated file tools should usually come before unrestricted execution. The practical result is a tool design that keeps the agent productive without confusing convenience with authority.

A typical Think-style agent might inspect a project, read a few relevant files, edit one configuration value, run a check, and return a generated report. Each action could be expressed as shell text, but the shell is not always the best interface for the model. A purpose-built operation can bound how much data enters the model context, preserve the rest of a file exactly, coordinate concurrent mutations, and make the action’s authority legible.

Give the model the smallest useful tool

Cloudflare Computer’s tools entry point can create AI SDK tools for reading, listing, finding, grepping, writing, editing, and deleting Workspace files. Execution is optional, and publishing is offered only when the Workspace has an Assets publisher. A read-only configuration keeps the inspection tools while omitting mutation, command execution, and publishing. This lets the application shape the agent’s working environment before the model ever chooses an action.

The distinction between read and exec cat is not cosmetic. A model-facing read tool can return text with line and byte limits and tell the model how to continue. If the first call stops at a boundary, the result supplies a next line offset and a byte continuation. Passing both to the next call lets the Workspace open the later range instead of transferring the already-read bytes again. The model receives enough context to proceed without turning a large source file into one oversized prompt.

The same bounded design applies to search. ls, find, and grep paginate results rather than requiring the tool layer to materialize an entire tree or match set. An exclusion can prune a generated directory before the walk descends into it. This matters for agent work because a repository often contains a small amount of relevant source surrounded by dependency, build, or cache trees. A tool that can omit those trees structurally gives the model a better signal, not merely a shorter display of the same expensive search.

Writes and edits solve a different problem. A whole-file write is useful when the agent is generating a new artifact, but a targeted edit is safer when it is changing a known part of an existing file. The edit tool applies a batch against the original content, requires each old range to be unique and non-overlapping, and returns a unified diff. It can tolerate limited differences in whitespace, quotes, dashes, or Unicode normalization while splicing the replacement into the original bytes. Untargeted content remains unchanged.

Those operations also share locks. A write cannot slip between an edit’s read and write phases, and a recursive delete locks its subtree against mutations to descendants or ancestors. The lock is not a distributed collaboration protocol; it coordinates the adapters that represent the same Workspace resource.