Matilda
Contact
Agent SDK · State and data

Files.

The runner files resource — upload, retrieve, and attach file IDs to a run.

The Runner exposes a files resource for uploading and retrieving files. Uploaded files can be attached to agent runs via fileIds.

runner.files.upload(file, options?)

Uploads a single file. Files at or above the server's chunked threshold use the parallel multipart protocol; smaller files use single-shot upload.

TypeScript
const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' });
const result = await runner.files.upload(file, {
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});
console.log(`File ID: ${result.fileId}, Status: ${result.status}`);

FileUploadOptions

Extends RequestOptions. All fields optional.

Fieldtypedescription
onProgress(pct: number) => voidProgress callback (0–100).
signalAbortSignalAbort the upload.
fingerprintstring | nullDevice fingerprint.
accessTokenstring | nullOverride access token.

Returns Promise<FileCompleteResponse>:

TypeScript
interface FileCompleteResponse {
  fileId: string;
  status: FileAttachmentStatus;
  failureReason?: FileFailureReason;
}

type FileAttachmentStatus = 'pending' | 'scanning' | 'processing' | 'ready' | 'failed' | 'rejected';

runner.files.uploadMany(files, options?)

Uploads multiple files in parallel. One file's failure does not abort the others.

TypeScript
const files = [
  new File(['doc 1'], 'doc1.txt', { type: 'text/plain' }),
  new File(['doc 2'], 'doc2.txt', { type: 'text/plain' }),
];

const results = await runner.files.uploadMany(files);
for (let i = 0; i < results.length; i++) {
  const result = results[i];
  if (result.status === 'fulfilled') {
    console.log(`File ${i}: ${result.value.fileId} (${result.value.status})`);
  } else {
    console.error(`File ${i} failed:`, result.reason);
  }
}

Returns Promise<PromiseSettledResult<FileCompleteResponse>[]>.

runner.files.retrieve(fileId, options?)

Retrieves metadata for a previously uploaded file.

TypeScript
const file = await runner.files.retrieve('file-abc123');
console.log(`${file.filename} — ${file.status} (${file.sizeBytes} bytes)`);

Returns Promise<FileAttachment>:

TypeScript
interface FileAttachment {
  id: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  status: FileAttachmentStatus;
  extractedText?: string;
  thumbnailUrl?: string;
  localUri?: string;
  failureReason?: FileFailureReason;
  createdAt: string;
}

Using files in agent runs

Upload a file, then reference its fileId in an agent run:

TypeScript
const fileResult = await runner.files.upload(
  new File(['Quarterly report content...'], 'report.txt', { type: 'text/plain' }),
);

const result = await runner.run(
  { name: 'analyst', purpose: 'analysis', instructions: 'Summarise the report.' },
  'What are the key findings?',
  { fileIds: [fileResult.fileId] },
);
console.log(result.finalOutput);