How AI SDK Tools Are Wired for Agents in Cloudflare Computer

Cloudflare Computer exposes a createAITools factory in packages/computer/src/tools/ai.ts that transforms a Workspace instance into a structured ToolSet, enabling agents to perform file operations and execute commands across sandboxed backends.

The cloudflare/computer repository provides a sandboxed execution environment where AI agents can autonomously read, write, and run code. Understanding how AI SDK tools are wired for agents requires examining the factory pattern that binds workspace capabilities to the AI model's tool-calling interface.

The Core Factory: createAITools

The entry point for agent tooling is the createAITools function defined in [packages/computer/src/tools/ai.ts](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts). This factory accepts a CreateAIToolsOptions configuration object and returns a ToolSet containing bound methods for workspace interaction.

Workspace Binding

Every tool set requires a workspace property implementing the FileWorkspaceLike interface. Internally, the factory constructs a WorkspaceFileStore to manage file-system state, which underlies all file-oriented tools and proxies calls to the appropriate backend storage.

Base Read-Only Tools

Regardless of configuration, the factory always includes four read-only tools in the returned ToolSet:

• read → Created by createReadTool for file content retrieval
• ls → Created by createListTool for directory listing
• find → Created by createFindTool for file searching
• grep → Created by createGrepTool for content pattern matching

Write-Enabled Tools

When the readonly option is set to false (the default), the factory appends three mutation tools to the ToolSet:

• write → createWriteTool for file creation and overwriting
• edit → createEditTool for partial file modifications
• delete → createDeleteTool for file and directory removal

Execution and Publishing Tools

Conditional tools extend the agent's capabilities based on additional configuration parameters:

• exec → Added when the shell option is provided, created by createExecTool. Supports multiple backends defined in the shell.backends map, allowing the AI to target different execution environments.
• publish → Added when the workspace exposes an assets field and assets are not explicitly disabled, created by createPublishTool for deployment operations.

Wiring Tools to an Agent

The Assistant agent implementation in [examples/src/agent.ts](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts) demonstrates the complete integration pattern used in production Durable Objects.

Workspace Construction with Backends

Agents instantiate a Workspace with two distinct backends to provide tiered execution capabilities:

1. WorkerShellBackend (id: "shell"): A fast just-bash environment for lightweight text processing and quick commands.
2. CloudflareContainerBackend (id: "container"): A full Linux container running computerd for comprehensive package installation and build processes.

Tool Set Instantiation

The agent's getTools() method invokes createAITools with the workspace instance and shell configuration. The configuration sets defaultBackend: "shell" and supplies a backends map describing each environment's latency characteristics and capabilities. This metadata allows the LLM to intelligently route commands—using "shell" for grep operations but "container" for npm install.

Integration with AI Models

The getModel() method uses createWorkersAI to obtain the LLM instance from the Workers AI provider. The system prompt explicitly lists the preferred tool order and describes the trade-offs between the bash and container backends, ensuring the model understands when to force a specific backend via the backend parameter in exec calls.

Practical Implementation Example

The following TypeScript implementation shows the complete wiring from workspace creation to autonomous tool execution:

import { Workspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import { CloudflareContainerBackend } from "@cloudflare/computer/backends/container";
import { createAITools } from "@cloudflare/computer/tools";

// 1️⃣ Create a Workspace with two backends
const ws = new Workspace({
  storage: SOME_DURABLE_OBJECT_STORAGE,
  backends: [
    new WorkerShellBackend({
      id: "shell",
      loader: SOME_LOADER,
      workspace: { binding: "MyDO", id: "do-id" },
      ctx: SOME_DO_STATE,
    }),
    new CloudflareContainerBackend({
      id: "container",
      container: () => SOME_DO_INSTANCE,
      workspace: { binding: "MyDO", id: "do-id" },
      egress: { mode: "direct" },
    }),
  ],
  useThink: true,
});

// 2️⃣ Build the AI‑aware tool set
const tools = createAITools({
  workspace: ws,
  shell: {
    defaultBackend: "shell",
    backends: {
      shell: { description: "just‑bash, fast text tooling" },
      container: { description: "full Linux container, slower startup" },
    },
  },
});

// 3️⃣ Use a tool (e.g. read a file)
const fileContent = await tools.read.run({ path: "README.md" });
console.log(fileContent);

// 4️⃣ Exec a command on the container backend
await tools.exec.run({
  command: "npm install",
  backend: "container",          // forces the container backend
  cwd: "/workspace/project",
});

Summary

• The createAITools factory in [packages/computer/src/tools/ai.ts](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) serves as the central mechanism for wiring AI SDK tools to agents.
• Read-only tools (read, ls, find, grep) are always present, while write tools (write, edit, delete) require readonly: false or the default configuration.
• The exec tool supports multiple shell backends defined in the shell.backends map, allowing agents to choose between lightweight bash environments and full Linux containers.
• The examples/src/agent.ts reference implementation demonstrates production-grade integration with Durable Objects, dual-backend workspaces, and the Workers AI provider.

Frequently Asked Questions

What is the entry point for creating AI tools in Cloudflare Computer?

The createAITools function exported from [packages/computer/src/tools/ai.ts](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) serves as the primary factory. It accepts a CreateAIToolsOptions object containing a workspace instance and optional shell configuration to generate a ToolSet that agents consume via the AI SDK.

How does an agent choose between different execution backends?

When the shell option is provided to createAITools, the factory creates an exec tool that exposes multiple backends through the shell.backends configuration. The agent's system prompt describes each backend's performance characteristics (e.g., "just-bash, fast" vs. "full Linux container, slower startup"), enabling the LLM to select the appropriate environment or allowing the developer to force a specific backend using the backend parameter in tool calls.

Can AI agents modify files in the workspace?

Yes, provided the readonly option is not explicitly set to true in the CreateAIToolsOptions. By default, createAITools includes write, edit, and delete tools that proxy mutations to the underlying WorkspaceFileStore, allowing autonomous file manipulation within the sandboxed environment while maintaining isolation through the workspace abstraction.

Where can I find a complete example of an agent using these tools?

The [examples/src/agent.ts](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts) file contains a reference implementation showing how to construct a Workspace with both WorkerShellBackend and CloudflareContainerBackend, wire them through createAITools, and expose the resulting ToolSet to an AI model using the Workers AI provider within a Durable Object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}