Files and artifacts

A live file belongs to the Session environment. An Artifact is a stored copy of a deliverable from a completed Turn. Updating the live file later does not change an existing Artifact.

Supply input files

Include base64-encoded inline files when creating the Environment:

const environment = {
  type: 'openai_hosted',
  files: [{
    type: 'inline', path: '/workspace/notes.txt',
    data: Buffer.from('Summarize these notes.').toString('base64'),
  }],
};

Use the Environment files endpoint to write additional inline files or list live files. Upload requests use inline bytes; references to an external Files API are not supported.

Files remain within that Session's Sandbox. They are not shared with other Sessions created from the same Agent.

Read documents and images

Hosted Sessions include two file tools automatically. list_files returns registered uploads with their Session file IDs, paths and sizes. The agent calls read_file with one of those IDs to inspect a document or image. This interface is shared across models; applications do not need to parse documents themselves.

// These are agent tool arguments, not separate SDK methods.
// Read the first PDF page as text:
{ file_id: 'file_...', page: 1, offset: 0, view: 'text' }
// Inspect a scanned page or chart visually:
{ file_id: 'file_...', page: 1, view: 'image' }

read_file supports PDF, DOC, DOCX, UTF-8 TXT/Markdown/CSV/JSON and JPEG/PNG/WebP/GIF, up to 10 MiB per file. Text results include next_offset for chunks of at most 20,000 UTF-16 code units. PDF results include page and total_pages; request the next page explicitly. Word extraction includes body text and notes, without embedded images or layout.

Images and rendered PDF pages become typed visual content. Rebyte translates their base64 data URLs into the selected model's provider protocol. Merely returning base64 text would not supply image input. The selected model must still support vision; Rebyte does not switch models or run a separate OCR model. Images use their first frame and are normalized to JPEG at up to 1600 pixels per side. Original environment files remain unchanged.

Parsing runs in a disposable process with a 30 second deadline. Unsupported, damaged, encrypted or overly complex files return tool errors. File contents are untrusted reference data and must not override the agent's instructions.

The Session resource's environment.files contains registered file IDs. Additional uploads also return an id; overwriting a registered path retains that ID. IDs cannot be used in another Session. list_files accepts an offset and returns next_offset for lists longer than 100 files; generated workspace files remain accessible through the existing environment and shell tools.

Produce Artifacts

Instruct the Agent to save deliverables under /workspace/outputs. At Turn completion, Rebyte copies those files into private storage and exposes them as Session Artifacts.

const artifacts = await client.beta.agents.sessions.artifacts.list(sessionId);
for (const artifact of artifacts.data) {
  const content = await client.beta.agents.sessions.artifacts.content(
    artifact.id, { session_id: sessionId },
  );
  console.log(artifact.path, artifact.size_bytes);
  // Use content.arrayBuffer() for binary files.
  console.log(await content.text());
}

Wait for the Turn outcome before expecting final deliverables. List results support cursor pagination.

Rebyte scans the current contents of /workspace/outputs on every completed Turn. A file left there can produce a new Artifact ID in a later Turn even if its bytes are unchanged. path is therefore not an Artifact identity or a deduplication key. Use artifact.id for downloads and turn_id to group deliveries. An older Artifact keeps its original bytes when the live path changes. If your application wants one latest version per path, make that a display policy rather than overwriting stored Artifact records.

Environment file operations enter the lazy Sandbox guard. Creating an Environment configuration with inline files alone does not allocate a VM; the first operation that needs the filesystem does. A text-only Turn does not create a Sandbox merely to scan outputs.

Delete and retain

Deleting an Artifact removes its stored copy, not the live file. Deleting a Session removes both its environment and stored Artifacts. Download deliverables before Session deletion if your application needs to retain them.

Artifact reads require organization authorization and the matching Session ID. Current limits are 10 MiB per inline file, 50 MiB per HTTP request and 50 MiB per Artifact. Upload multiple large files through separate requests to stay within the HTTP limit.