Files and artifacts

Files

const file = await client.uploadFile({
  filename: 'receipt.pdf',
  contentType: 'application/pdf',
  contentBase64: await toBase64(blob),
  metadata: { source: 'checkout-upload' },
});

const { files } = await client.listFiles();
const fetched = await client.getFile(file.fileRef);

Uploads are base64 in the request body — there is no separate multipart or signed-URL flow. Check policy.filePolicy first: it carries upload, read, maxUploadBytes, and allowedMimeTypes, all enforced server-side.

const { filePolicy } = await client.getEffectivePolicy();

if (!filePolicy.upload || !filePolicy.allowedMimeTypes.includes(blob.type)) {
  return refuseUpload();
}
if (blob.size > filePolicy.maxUploadBytes) {
  return refuseUpload();
}

Each file comes back as a RuntimeFile — fileRef, name, and optional mimeType, sizeBytes, status, createdAt, and metadata. status is worth branching on: a freshly uploaded file may be processing before it becomes available.

Pass fileRef values to streamMessage({ fileRefs }) to reference them in a turn — see Conversations and streaming.

Context-library operations need a workspace

File operations that touch the agent's context library require a materialized workspace binding from ensureWorkspace() and policy support. See Workspaces.

Artifacts

Artifacts are durable outputs an agent produces — a document, a table, a generated file. They arrive as artifact:created events mid-stream, and on message:complete in the artifacts array. Read one by ref:

const policy = await client.getEffectivePolicy();

if (policy.capabilities.artifacts) {
  const artifact = await client.getArtifact('artifact_public_12345678');

  console.log(
    artifact.title,
    artifact.status,
    artifact.contentType,
    artifact.contentText ?? artifact.contentJson,
  );
}

GetArtifactResult returns public-safe fields only: artifactRef, kind, title, status, contentType, contentText, contentJson, summaryText, renderHints, and createdAt. No raw internal IDs and no storage locations.

renderHints is advisory presentation metadata; treat it as a hint, not a contract, and always have a fallback rendering.

Error behaviour

Situation	Result
capabilities.artifacts is disabled	403 with a stable unsupported_capability SDK error
Ref outside the current session/workspace isolation boundary	404

Both are stable — the 404 is deliberate, so a ref belonging to another tenant is indistinguishable from one that does not exist.