GuidesFiles and durable work

Build a coding Agent

Use a coding Agent for a small, explicit task that must inspect and change files inside a durable Sandbox. This guide exercises the six read, write, edit, search, and command Tools without adding a framework or repository setup.

Outcome

The Agent will create one tiny file, edit it, inspect it with read, grep, and glob, run one harmless bash command, and report the verified file value and command output.

Before you begin

Complete Configure file operations so the Agent has a durable Sandbox. You also need a backend SDK client and a bounded workspace objective. Review Tools, file operations, and security and credentials.

Enable the coding Tools

Configure the file_operation_sandbox Tool group. It expands to the individual read, write, edit, grep, glob, bash, and save_artifacts Tools; there is no separate combined coding Tool.

const agent = await client.agents.get(agentId);
await client.agents.update(agentId, {
  tools: agent.tools.includes("file_operation_sandbox")
    ? agent.tools : [...agent.tools, "file_operation_sandbox" as const],
});
const turn = await client.chat({
  agentId,
  message: { id: crypto.randomUUID(), role: "user", parts: [{
    type: "text", text: "Use write to create status.txt containing PENDING plus a newline. "
      + "Use edit to replace PENDING with READY. Verify it with read, grep for READY, "
      + "and glob for status.txt. Run `wc -c < status.txt` with bash. Then summarize.",
  }] },
});
const sessionId = await turn.sessionId;
for await (const _chunk of turn.toUIMessageStream()) { /* drain */ }
const { data } = await client.sessions.messages(agentId, sessionId);
const parts = data.flatMap((message) => message.parts);
const result = (name: string) => parts.find((part) =>
  part.type === `tool-${name}` && part.state === "output-available")?.output;
const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null;
const has = (name: string, key: string, expected: unknown) => {
  const output = result(name);
  return isRecord(output) && output[key] === expected;
};
if (!has("write", "bytesWritten", 8) || !has("edit", "replacements", 1)) throw new Error("change failed");
if (!(JSON.stringify(result("grep")) ?? "").includes("READY")
  || !(JSON.stringify(result("glob")) ?? "").includes("/status.txt")) throw new Error("search failed");
if (!has("read", "content", "READY\n")) throw new Error("read failed");
if (!has("bash", "stdout", "6\n") || !has("bash", "exitCode", 0)) throw new Error("bash failed");

Give the Agent a bounded task

Name the exact file, original text, replacement text, search checks, and command. The expected workspace value is READY\n; wc -c must return 6 for those six bytes.

Run the Agent

client.chat() starts one Turn. The model loop remains in the trusted dispatcher while Tool calls execute in the Agent's attached Sandbox.

Verify the workspace

The persisted transcript must contain successful write, edit, grep, and glob Tool-result parts. The assertions independently require the read output to contain exactly READY\n and the bash output to contain stdout: "6\n" with exitCode: 0; model-authored summary text is ignored.

Reuse the workspace

Later chat, generation, and Task Turns for this Agent reuse the attached Sandbox without repeating setup. Start a new Turn with a precise follow-up task; the Sandbox attachment, not the Session, determines which durable workspace it uses.

Production notes

  • Guest networking and environment access are denied. Commands run from /workspace inside the WASM-confined AgentOS environment and remain subject to filesystem, process, descriptor, socket, memory, and compute limits.
  • Provider credentials stay in the trusted dispatcher and never enter the Sandbox. Keep application secrets out of prompts and workspace files too.
  • A Sandbox serializes complete Turns, and fleet-wide capacity can queue work. Sessions reserve no capacity between Turns.
  • Cancel with the Turn's signal. Completed writes and edits are not rolled back; accepted operations settle before the actor sleeps and capacity is released.
  • Treat model-produced commands and files as untrusted and validate them before use. See limits and reliability.

SDK and REST reference

On this page