[Agents] Draft workspaces documentation#31254
Draft
aron-cf wants to merge 4 commits into
Draft
Conversation
github-actions
Bot
added
product:agents
github-actions
Bot
assigned
elithrar,
irvinebroque,
rita3ko,
thomasgauvin,
threepointone and
whoiskatrin
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
aron-cf
force-pushed
the
agents-workspace-docs
branch
from
c66bfae to
7f59be8
Compare
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 critical issue and 13 suggestions.
- CRITICAL
src/content/docs/agents/tools/workspace.mdx:45—awaitin constructor is invalid TypeScript. - HIGH
src/content/docs/agents/tools/workspace.mdx:9,86,452— UsePackageManagerscomponent for install commands instead of bareshfences. - HIGH
src/content/docs/agents/tools/workspace.mdx:92,212,432—WranglerConfigrequires TOML input (JSON is auto-generated). Also use$todayforcompatibility_date. - HIGH
src/content/docs/agents/tools/workspace.mdx:367— Baretscode block for a type interface; useTypeScriptExample. - MEDIUM
src/content/docs/agents/tools/workspace.mdx:15,76,129— Run-on sentences and typo. - MEDIUM
src/content/docs/agents/tools/workspace.mdx:17,351— "Coming soon" phrases trigger Semgrep warnings in CI. - LOW
src/content/docs/agents/tools/workspace.mdx:300— Grammar.
Note: The PR description lists many unrelated changes. Update it to describe only the workspace docs addition.
| description: Give your agents a computer. Workspaces are shared between a Durable Object and a container, with built-in shell, mounts, and common filesystem tools. | ||
| --- | ||
|
|
||
| import { Aside, LinkCard, Tabs, TabItem, TypeScriptExample, WranglerConfig } from "~/components"; |
Contributor
There was a problem hiding this comment.
Add PackageManagers to imports for install commands:
Suggested change
| import { Aside, LinkCard, Tabs, TabItem, TypeScriptExample, WranglerConfig } from "~/components"; | |
| import { Aside, LinkCard, PackageManagers, Tabs, TabItem, TypeScriptExample, WranglerConfig } from "~/components"; |
|
|
||
| Most work performed by an agent that requires a filesystem doesn't require a heavy Linux environment. Workspaces live inside a [Durable Object](/durable-objects/) right next to your agent harness. | ||
|
|
||
| Take advantage of the speed of working on files within the Worker environment and should a Linux environment be needed, you can drop into a [Cloudflare Container](/containers/) to execute bash commands, changes in either environment are reflected everywhere. |
Contributor
There was a problem hiding this comment.
Split run-on sentence:
Suggested change
| Take advantage of the speed of working on files within the Worker environment and should a Linux environment be needed, you can drop into a [Cloudflare Container](/containers/) to execute bash commands, changes in either environment are reflected everywhere. | |
| Take advantage of the speed of working on files within the Worker environment. Should a Linux environment be needed, you can drop into a [Cloudflare Container](/containers/) to execute bash commands. Changes in either environment are reflected everywhere. |
|
|
||
| Take advantage of the speed of working on files within the Worker environment and should a Linux environment be needed, you can drop into a [Cloudflare Container](/containers/) to execute bash commands, changes in either environment are reflected everywhere. | ||
|
|
||
| File operations, R2 mounts and git clones within the Durable Object are all covered today, lightweight bash execution and code execution are coming soon! |
Contributor
There was a problem hiding this comment.
Fix comma splice and avoid "coming soon" (flagged by Semgrep):
Suggested change
| File operations, R2 mounts and git clones within the Durable Object are all covered today, lightweight bash execution and code execution are coming soon! | |
| File operations, R2 mounts, and git clones within the Durable Object are all covered today. Lightweight bash execution and code execution are not yet available. |
Comment on lines
+44
to
+46
|
|
||
| const report = await this.#workspace.fs.readFile("/workspace/data/report.csv", "utf8"); | ||
| } |
Contributor
There was a problem hiding this comment.
Remove await from constructor — constructors cannot be async:
Suggested change
| const report = await this.#workspace.fs.readFile("/workspace/data/report.csv", "utf8"); | |
| } | |
| } |
| ``` | ||
|
|
||
| 1. A Durable Object constructs a `Workspace` backed by the Durable Object SQLite storage and configures a backend (currently a Cloudflare Container). | ||
| 2. The backend starts the container, whose entrypoint is the a small `wsd` client. `wsd` mounts the workspace at a path inside the container using FUSE. |
Contributor
There was a problem hiding this comment.
Fix typo:
Suggested change
| 2. The backend starts the container, whose entrypoint is the a small `wsd` client. `wsd` mounts the workspace at a path inside the container using FUSE. | |
| 2. The backend starts the container, whose entrypoint is a small `wsd` client. `wsd` mounts the workspace at a path inside the container using FUSE. |
Comment on lines
+299
to
+301
|
|
||
| <Aside type="note" title="Prefer ReadableStream where possible"> | ||
| Durable Objects are limited to 128MiB memory so it is preferable to avoid buffering data, particularly files into memory. All operations will default to `ReadableStream` and provide non-streaming alternatives when needed. |
Contributor
There was a problem hiding this comment.
Tighten grammar:
Suggested change
| <Aside type="note" title="Prefer ReadableStream where possible"> | |
| Durable Objects are limited to 128MiB memory so it is preferable to avoid buffering data, particularly files into memory. All operations will default to `ReadableStream` and provide non-streaming alternatives when needed. | |
| <Aside type="note" title="Prefer ReadableStream where possible"> | |
| Durable Objects are limited to 128 MiB of memory, so it is preferable to avoid buffering data — particularly files — into memory. All operations default to `ReadableStream` and provide non-streaming alternatives when needed. | |
| </Aside> |
|
|
||
| ## Shell API | ||
|
|
||
| `ws.shell.exec(command, options?)` spawns a command inside the container and returns an `ExecHandle` stub. Today's API is run-and-wait — call `handle.result()` to await the exit code and collected output. Streaming exec is coming soon. |
Contributor
There was a problem hiding this comment.
Avoid "coming soon" (flagged by Semgrep):
Suggested change
| `ws.shell.exec(command, options?)` spawns a command inside the container and returns an `ExecHandle` stub. Today's API is run-and-wait — call `handle.result()` to await the exit code and collected output. Streaming exec is coming soon. | |
| `ws.shell.exec(command, options?)` spawns a command inside the container and returns an `ExecHandle` stub. Today's API is run-and-wait — call `handle.result()` to await the exit code and collected output. Streaming exec is not yet available. |
Comment on lines
+365
to
+373
| ### `ExecResult` | ||
|
|
||
| ```ts | ||
| interface WorkspaceExecResult<E extends "utf8" | undefined> { | ||
| exitCode: number; | ||
| stdout: E extends "utf8" ? string : Uint8Array; | ||
| stderr: E extends "utf8" ? string : Uint8Array; | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
Wrap interface in TypeScriptExample:
Suggested change
| ### `ExecResult` | |
| ```ts | |
| interface WorkspaceExecResult<E extends "utf8" | undefined> { | |
| exitCode: number; | |
| stdout: E extends "utf8" ? string : Uint8Array; | |
| stderr: E extends "utf8" ? string : Uint8Array; | |
| } | |
| ``` | |
| <TypeScriptExample> | |
| ```ts | |
| interface WorkspaceExecResult<E extends "utf8" | undefined> { | |
| exitCode: number; | |
| stdout: E extends "utf8" ? string : Uint8Array; | |
| stderr: E extends "utf8" ? string : Uint8Array; | |
| } | |
| </TypeScriptExample> |
Comment on lines
+432
to
+443
| <WranglerConfig> | ||
|
|
||
| ```jsonc | ||
| { | ||
| "r2_buckets": [ | ||
| { "binding": "Bucket", "bucket_name": "my-agent-data" }, | ||
| { "binding": "Skills", "bucket_name": "my-agent-skills" }, | ||
| ], | ||
| } | ||
| ``` | ||
|
|
||
| </WranglerConfig> |
Contributor
There was a problem hiding this comment.
Use TOML input for WranglerConfig:
Suggested change
| <WranglerConfig> | |
| ```jsonc | |
| { | |
| "r2_buckets": [ | |
| { "binding": "Bucket", "bucket_name": "my-agent-data" }, | |
| { "binding": "Skills", "bucket_name": "my-agent-skills" }, | |
| ], | |
| } | |
| ``` | |
| </WranglerConfig> | |
| <WranglerConfig> | |
| ```toml | |
| [[r2_buckets]] | |
| binding = "Bucket" | |
| bucket_name = "my-agent-data" | |
| [[r2_buckets]] | |
| binding = "Skills" | |
| bucket_name = "my-agent-skills" |
Comment on lines
+450
to
+452
|
|
||
| ```sh | ||
| npm install isomorphic-git diff |
Contributor
There was a problem hiding this comment.
Use PackageManagers for install commands:
Suggested change
| ```sh | |
| npm install isomorphic-git diff | |
| <PackageManagers pkg="isomorphic-git diff" /> |
Contributor
|
Applied labels Posted a review with 14 inline comments on PR #31254:
Also flagged that the PR description lists many unrelated changes instead of describing the workspace docs addition. |
Contributor
|
Preview URL: https://9d679040.preview.developers.cloudflare.com Files with changes (up to 15)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.