GuidesLangChain
Handling Files
Learn how to work with files in Bluebag sessions.
Bluebag persists files in the sandbox so your agents have access to them across tool calls within a session.
Uploading files
Use the files.create method to upload files to the Bluebag sandbox:
import { Bluebag } from "@bluebag/langchain";
const client = new Bluebag({
apiKey: process.env.BLUEBAG_API_KEY!,
});
const uploaded = await client.files.create({
file: myFile,
filename: "report.pdf",
mediaType: "application/pdf",
});
console.log(uploaded.fileId);The uploaded file is now available to your agent's tools. You can reference it by fileId when mounting files into code execution.
Accessing file artifacts
When tools create files, metadata is included in the tool result's artifacts array:
const toolResult = JSON.parse(lastToolMessage.content);
if (toolResult.artifacts?.length) {
for (const artifact of toolResult.artifacts) {
console.log(`Created: ${artifact.filename} (${artifact.size} bytes)`);
console.log(`File ID: ${artifact.fileId}`);
}
}Each artifact includes:
fileId: Unique identifier for the filefilename: Original filenamepath: Path inside the sandboxsize: File size in bytesexpiryAt: When the file will be deleted
Downloading files
Generate a signed download URL for any file:
const downloadUrl = await client.files.mintShortLivedDownloadUrl(artifact.fileId);Or download the file directly:
const blob = await client.files.download(artifact.fileId);Retrieving file metadata
Fetch metadata for a file by its ID:
const metadata = await client.files.retrieveMetadata(fileId);
console.log(metadata.filename, metadata.size);Persisting files
By default, files expire after a period of time. To keep a file beyond its default expiry:
const persisted = await client.files.persist(fileId);
console.log(`File will now expire at: ${persisted.expiryAt}`);You can also set a custom expiry:
const persisted = await client.files.persist(fileId, {
expiryAt: new Date("2025-12-31"),
});