How to Use AI SDK Tools with the Cloudflare Workspace for Agent Workflows

The Cloudflare Workspace provides a sandboxed virtual file system that integrates with AI SDK v7 tools through createAITools(), giving AI agents the ability to read, write, execute, and publish files within isolated environments.

The cloudflare/computer repository implements a complete agent infrastructure on Cloudflare Workers. At its core, the Workspace class (packages/computer/src/Workspace.ts) wraps a SQLite-backed virtual file system, while the AI SDK tools package exposes that filesystem to language models through a standardized tool interface. This guide walks through wiring these systems together for production agent workflows.

Setting Up a Workspace in a Durable Object

Agent state must survive individual requests. The Workspace achieves this persistence by binding to Durable Object storage, which commits filesystem operations to SQLite.

Inside your Durable Object class, instantiate Workspace with the state object:

import { Workspace } from "@cloudflare/computer";

export class Agent {
  workspace: Workspace;

  constructor(state: DurableObjectState) {
    this.workspace = new Workspace({ storage: state.storage });
  }
}

Source: packages/computer/README.md (lines 35-41)

The Workspace constructor accepts additional configuration for git repositories, asset bindings, and custom serialization—but storage is the only required parameter for basic operation.

Generating AI SDK Tools with createAITools()

The createAITools factory function (packages/computer/src/tools/ai.ts) transforms a Workspace instance into a ToolSet compatible with AI SDK v7. This bridges the gap between the model's function-calling interface and the Workspace's filesystem operations.

Basic invocation with filesystem tools only:

import { createAITools } from "@cloudflare/computer/tools";

const tools = createAITools({
  workspace: this.workspace,
  read: { maxBytes: 32 * 1024, maxLines: 800 },
});

Expanded configuration with execution and publishing capabilities:

const tools = createAITools({
  workspace: this.workspace,
  read: { maxBytes: 32 * 1024, maxLines: 800 },
  shell: {
    defaultBackend: "shell",
    backends: {
      shell: { description: "Fast Worker shell" },
      container: { description: "Full Linux container" },
    },
  },
});

Source: docs/09_tool_interface.md (lines 31-45) and packages/computer/src/tools/ai.ts (lines 23-49)

Default Tool Set

The factory returns these standard tools:

Tool	Description	Source Location
read	Read file contents with size/line limits	packages/computer/src/tools/fs/read.ts
ls	List directory contents	packages/computer/src/tools/fs/ls.ts
find	Recursive file search	packages/computer/src/tools/fs/find.ts
grep	Content search with regex	packages/computer/src/tools/fs/grep.ts
write	Create or overwrite files	packages/computer/src/tools/fs/write.ts
edit	In-place text replacement	packages/computer/src/tools/fs/edit.ts
delete	Remove files or directories	packages/computer/src/tools/fs/delete.ts

Optional tools:

• exec – Command execution (requires shell configuration)
• publish – R2 asset upload (requires assets service binding)

Integrating with AI SDK v7

Pass the generated ToolSet directly to AI SDK functions. The model receives tool schemas and can invoke them as ordinary functions.

import { generateText } from "ai";

const result = await generateText({
  model: aiModel,
  prompt: "List the files in the current workspace.",
  tools,
});

Source: docs/09_tool_interface.md (lines 56-58)

Complete Implementation Example

// 1️⃣ Set up a Workspace in a Durable Object
import { Workspace } from "@cloudflare/computer";

export class AssistantDO {
  ws: Workspace;

  constructor(state: DurableObjectState) {
    this.ws = new Workspace({ storage: state.storage });
  }
}

// 2️⃣ Build the AI SDK tools
import { createAITools } from "@cloudflare/computer/tools";

function getTools(ws: Workspace) {
  return createAITools({
    workspace: ws,
    read: { maxBytes: 64 * 1024 },
    shell: {
      defaultBackend: "shell",
      backends: {
        shell: { description: "Fast Worker shell" },
        container: { description: "Full Linux container" },
      },
    },
  });
}

// 3️⃣ Use the tools with the AI SDK (v7)
import { generateText } from "ai";

async function askAgent(ws: Workspace, userPrompt: string) {
  const tools = getTools(ws);
  const response = await generateText({
    model: env.AI,          // Workers AI binding
    prompt: userPrompt,
    tools,
  });
  return response;
}

// Example: ask the agent to list files and edit one
await askAgent(ws, "List the files, then add a line to /notes.md.");

Backend Selection for Command Execution

The exec tool routes commands to configurable backends based on model-selected descriptions. Two built-in backends ship with the repository:

• shell – Lightweight bash environment inside a Dynamic Worker (worker-shell backend). Fast cold starts, limited to available Worker binaries.
• container – Full Linux container running computerd with complete filesystem isolation and standard Linux toolchains.

Backend selection happens through natural language. When the model requests "run this in a full Linux environment," the description match routes to the container backend:

shell: {
  defaultBackend: "shell",
  backends: {
    shell: { description: "Fast Worker shell" },
    container: { description: "Full Linux container" },
  },
}

Source: packages/computer/src/tools/ai.ts (lines 38-43) and packages/computer/README.md (lines 37-44)

Concurrency Control and Atomic Operations

All file-mutating tools share a locking mechanism through WorkspaceFileStore, keyed by the workspace's lockIdentity. This guarantees:

• Edit atomicity – No write can interleave between the read-modify-write phases of an edit operation
• Recursive deletion safety – delete on directories locks the entire subtree

Source: docs/09_tool_interface.md (lines 224-229)

Asset Publishing with R2 Integration

When the Workspace is configured with an assets service binding, createAITools adds a publish tool that:

1. Uploads the specified file to Cloudflare R2
2. Returns a presigned URL for external access

This enables agent workflows that generate artifacts and immediately expose them via CDN.

Source: packages/computer/src/tools/ai.ts (lines 45-47)

Key Source Files Reference

File	Purpose
packages/computer/src/tools/ai.ts	Core factory createAITools that wires the Workspace to the AI SDK tools
docs/09_tool_interface.md	Complete specification of the tool set, options, and behavior
packages/computer/README.md	Overview of the Workspace, backends, and agent integration patterns
examples/think/README.md	End-to-end example: Durable Object agent with Workspace and AI SDK tools
packages/computer/src/tools/fs/*	Individual filesystem tool implementations
packages/computer/src/tools/exec.ts	Execution tool with backend routing
packages/computer/src/tools/publish.ts	R2 asset publishing tool

Summary

• Workspace + Durable Objects provide persistent, sandboxed filesystem state for agents
• createAITools() generates a complete AI SDK v7 ToolSet from a Workspace instance
• Seven default tools cover filesystem operations; optional exec and publish extend to command execution and asset distribution
• Dual execution backends let models choose between fast shell environments and full Linux containers
• Built-in locking ensures atomic edits and safe concurrent access

Frequently Asked Questions

What AI SDK version does Cloudflare Computer require?

The tools factory createAITools() produces a ToolSet compatible with AI SDK v7. Earlier versions used different tool definition formats and are not supported. Verify your ai package version matches before integration.

Can I use the Workspace without Durable Objects?

No. The Workspace requires a storage binding that implements the Durable Object storage API for SQLite persistence. While you could theoretically pass a mock storage implementation for testing, production deployments must run inside Durable Objects to maintain filesystem state across requests.

How do I add custom tools alongside the generated ones?

The createAITools() return value is a plain object mapping tool names to tool definitions. Spread additional tools into this object before passing to generateText() or streamText():

const cloudflareTools = createAITools({ workspace: ws });
const customTools = { myTool: { ... } };
const allTools = { ...cloudflareTools, ...customTools };

What limits apply to file reads?

The read tool respects maxBytes and maxLines parameters passed to createAITools(). By default, unconfigured reads may truncate large files—always specify limits appropriate to your model's context window. The implementation in packages/computer/src/tools/fs/read.ts enforces these bounds before returning content.

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