File operations

File operations are the built-in Tools an Agent uses to work with files and commands in its attached Sandbox. Enable them for coding, document generation, data processing, and other workflows that need durable mutable files.

Available operations

The file_operation_sandbox group selects these public Tools:

The group controls Tool availability. The model loop still runs in the trusted dispatcher rather than inside the Sandbox.

Requirements and confinement

The entire group requires an attached Sandbox. Agent creation and update reject a selection without sandboxId, and a Turn checks the invariant again before acquiring the environment.

Relative paths resolve beneath /workspace. Absolute paths must already be inside that root, and normalized paths that escape it are rejected. Selected Skill assets use a read-only virtual path; file mutation Tools cannot change them.

bash starts in /workspace, but shell commands can affect any workspace file allowed by the Sandbox. The environment denies guest network and environment access and exposes only its installed runtime commands; it does not receive Provider credentials.

Enable file operations

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});
const sandbox = await client.sandboxes.create({ name: "Writer Sandbox" });
const agent = await client.agents.create({
  name: "File Writer",
  sandboxId: sandbox.id,
  tools: ["file_operation_sandbox"],
});

const turn = await client.chat({
  agentId: agent.id,
  message: {
    id: crypto.randomUUID(),
    role: "user",
    parts: [{ type: "text", text: "Write hello.txt containing Hello!" }],
  },
});

for await (const chunk of turn.toUIMessageStream()) console.log(chunk);

The successful Turn stream includes the write Tool activity, and the transcript records its result. hello.txt remains in the private workspace for later Turns because the prompt did not ask the Agent to publish it.

Publishing is explicit

Writing a file does not make it an application output. The Agent must call save_artifacts with one or more workspace-relative paths to create Artifacts. Files that are never passed to that Tool remain private scratch or working state.

Artifact publication requires a stateful Session. Stateless generation can use the other file Tools in the attached Sandbox, but save_artifacts is not available because there is no Session to own the output.

Failure and cancellation

Tool validation and runtime errors are returned to the Agent. A command can return a nonzero exit code with partial output, and a Turn may fail or be canceled after earlier operations completed.

Filesystem changes are not transactional: completed writes and edits remain after partial failure or cancellation. A failed Turn does not commit new Session transcript events, so do not treat transcript persistence as proof that the workspace rolled back.

Production considerations

• Enable the group only for Agents that need workspace access.
• Treat model-generated commands and file contents as untrusted input.
• Keep secrets out of prompts, commands, and workspace files.
• Expect bounded Tool inputs and outputs plus Sandbox filesystem, process, descriptor, socket, memory, and compute limits.
• Validate files before consuming or publishing them in another system.
• Use save_artifacts only for intended outputs, not every intermediate file.

Related guides

• Configure file operations
• Build a coding Agent
• Publish and download Artifacts

Reference

• Files and outputs overview
• Agent Tool configuration: TypeScript SDK and REST API
• Generation: TypeScript SDK and REST API
• Artifact operations: TypeScript SDK and REST API
• Tools capability