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

> Learn to integrate AI SDK tools with Cloudflare Workspace for agent workflows. Discover how to manage files and execute tasks in isolated environments with createAITools().

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) (lines 31-45) and [`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/read.ts) |
| `ls` | List directory contents | [`packages/computer/src/tools/fs/ls.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/ls.ts) |
| `find` | Recursive file search | [`packages/computer/src/tools/fs/find.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/find.ts) |
| `grep` | Content search with regex | [`packages/computer/src/tools/fs/grep.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/grep.ts) |
| `write` | Create or overwrite files | [`packages/computer/src/tools/fs/write.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/write.ts) |
| `edit` | In-place text replacement | [`packages/computer/src/tools/fs/edit.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/edit.ts) |
| `delete` | Remove files or directories | [`packages/computer/src/tools/fs/delete.ts`](https://github.com/cloudflare/computer/blob/main/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.

```typescript
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`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) (lines 56-58)

### Complete Implementation Example

```typescript
// 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:

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

```

*Source:* [`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) (lines 38-43) and [`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) (lines 45-47)

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) | Core factory `createAITools` that wires the Workspace to the AI SDK tools |
| [`docs/09_tool_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) | Complete specification of the tool set, options, and behavior |
| [`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md) | Overview of the Workspace, backends, and agent integration patterns |
| [`examples/think/README.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/exec.ts) | Execution tool with backend routing |
| [`packages/computer/src/tools/publish.ts`](https://github.com/cloudflare/computer/blob/main/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()`:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/read.ts) enforces these bounds before returning content.