#Files

Managed Agents files are reusable inputs and session-scoped artifacts for agent runs. Use the official Anthropic SDK against the Sandbox0 Managed Agents endpoint.

Official reference: Claude Managed Agents files.

Sandbox0 stores file bytes outside PostgreSQL in the team asset store. PostgreSQL remains the metadata and scope source of truth.

Upload A File#

typescript
import { toFile } from "@anthropic-ai/sdk";

const uploaded = await client.beta.files.upload({
    file: await toFile(
        Buffer.from("hello from managed agents\n"),
        "input.txt",
        { type: "text/plain" },
    ),
});

The returned object includes the file id, filename, MIME type, size, download flag, optional scope, and creation time.

typescript
const metadata = await client.beta.files.retrieveMetadata(uploaded.id);

const files = await client.beta.files.list({
    limit: 20,
});

Sandbox0 currently supports downloading file content:

typescript
const response = await client.beta.files.download(uploaded.id);
const text = await response.text();

Delete files that are no longer needed:

typescript
await client.beta.files.delete(uploaded.id);

Attach Files To Sessions#

Uploaded files can be attached as session resources:

typescript
const resource = await client.beta.sessions.resources.add(session.id, {
    type: "file",
    file_id: uploaded.id,
    mount_path: "/workspace/input.txt",
});

When a file is attached to a session, Sandbox0 creates a session-scoped copy and returns that scoped file id on the resource. The resource file id is intentionally different from the uploaded file id.

typescript
console.log(resource.file_id === uploaded.id); // false

If mount_path is omitted, Sandbox0 mounts the scoped file under /mnt/session/uploads/ using the scoped file id.

List Session-Scoped Files#

Use scope_id to list files associated with a session:

typescript
const scopedFiles = await client.beta.files.list({
    scope_id: session.id,
    limit: 20,
});

Session-scoped files include:

Deleting a file resource removes the session-scoped copy for that resource. Deleting a session removes its scoped files.

Output Files#

Agent runs can write files under /mnt/session/outputs. After the run reaches session.status_idle with a terminal stop reason, or reaches session.status_terminated, Sandbox0 captures those output files into the Files API with scope.id = session.id.

typescript
const outputs = await client.beta.files.list({
    scope_id: session.id,
});

The output file name is derived from the path under /mnt/session/outputs. Nested output paths are flattened into safe filenames.

File-Backed Message Content#

Uploaded files can also be referenced directly from user messages:

typescript
await client.beta.sessions.events.send(session.id, {
    events: [{
        type: "user.message",
        content: [
            { type: "text", text: "Summarize this document." },
            {
                type: "document",
                source: { type: "file", file_id: uploaded.id },
                title: "input",
                citations: { enabled: true },
            },
        ],
    }],
});

For file-backed input, use a file id returned by the Files API. Sandbox0 reads the file content and forwards it to the selected harness as model input.

Limits#

Filenames must be valid UTF-8, must not be empty, must not contain path separators or control characters, and must be at most 500 characters.

Next Steps#