Skip to main content
Asteroid agents can work with files in multiple ways, enabling them to download files from websites, read various file types, and upload files to web applications. These capabilities are available through specialized tools in the AI Agent node. Files can also be downloaded via the API.

Staging Files

Pre-upload files before starting an execution

File Downloads

Automatically download files from websites

File Reading

Read and process images, PDFs, CSVs, and other file types

File Uploads

Upload files to web forms and applications

API Access

Programmatically manage files through the Asteroid Odyssey SDK

​
Staging Files

Use staging files when you need to provide files to an execution before it starts. If your execution is already running, use the upload files endpoint instead.
Staging files is useful when you have files that the agent needs from the very start of execution.

​
How It Works

  1. Stage: Upload files via POST /temp-files/{organizationId} - this returns an array of temp file objects with id and name
  2. Execute: Pass the temp file array in the tempFiles parameter when calling POST /agents/{agentId}/execute
  3. When the execution starts, your staged files are automatically attached to the execution context
Staged files expire after 60 minutes. You must start an execution using the staged files within this time window, or the files will be automatically deleted.

​
Code Examples

import {
  client,
  tempFilesStage,
  agentExecutePost,
} from 'asteroid-odyssey';
import { readFileSync } from 'fs';

// Configure client
client.setConfig({
  headers: {
    'X-Asteroid-Agents-Api-Key': 'YOUR_API_KEY',
  },
});

// Step 1: Stage files before execution
const fileContent = readFileSync('document.pdf');
const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

const { data: staged } = await tempFilesStage({
  path: { organizationId: 'YOUR_ORGANIZATION_ID' },
  body: { files: [file] },
});
// staged.tempFiles = [{ id: "uuid", name: "document.pdf" }]

// Step 2: Execute agent with staged files
const { data: execution } = await agentExecutePost({
  path: { agentId: 'YOUR_AGENT_ID' },
  body: {
    tempFiles: staged?.tempFiles,
    inputs: { /* your variables */ },
  },
});

console.log(`Execution ID: ${execution?.executionId}`);

​
File Downloads

Your agents can download files from websites during browser automation sessions. Downloaded files are stored in the execution context and can be accessed through the agents tools.
Downloaded files appear in the Files section at the top right of the screen

​
File Reading

Asteroid agents can read and process various file types.

​
Supported File Types

  • Images (PNG, JPEG)
  • PDFs
  • Text Files (TXT, MD)
  • CSVs

​
File Uploads

Agents can upload files to web applications using the Upload File tool, which supports:
  • Local file uploads
  • Previously downloaded files (using downloads/filename format)

​
API Access

File upload and downloads are also available programmatically through the Asteroid Odyssey SDK:

​
Upload Files

import { client, executionContextFilesUpload } from 'asteroid-odyssey';
import { readFileSync } from 'fs';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': 'YOUR_API_KEY' },
});

// Upload files to a running execution
const fileContent = readFileSync('document.pdf');
const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

await executionContextFilesUpload({
  path: { executionId: 'your-execution-id' },
  body: { files: [file] },
});

​
Download Files

import { client, executionContextFilesGet } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': 'YOUR_API_KEY' },
});

// Get list of execution files
const { data: files } = await executionContextFilesGet({
  path: { executionId: 'your-execution-id' },
});

// Download specific files using the signed URL
for (const file of files ?? []) {
  const response = await fetch(file.signedUrl);
  const buffer = await response.arrayBuffer();
  console.log(`Downloaded ${file.fileName} (${file.fileSize} bytes)`);
}

​
Use Cases

File handling capabilities enable powerful automation workflows:
  • Document Processing: Automatically download and analyze reports, invoices, or forms
  • Data Extraction: Process CSV files, spreadsheets, and structured data
  • Image Analysis: Download and analyze screenshots, charts, or visual content
  • Form Automation: Upload documents, images, or files to web applications
  • Content Management: Handle file uploads for content creation workflows