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
/workspaceinside 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.
Related capabilities
SDK and REST reference
- Read the Agent:
agents.get()andGET /v1/agents/:agentId - Update Tool configuration:
agents.update()andPUT /v1/agents/:agentId - Create the Turn:
client.chat()andPOST .../sessions - Inspect Tool results:
sessions.messages()andGET .../messages