Cookbook

Practical examples for the current Asteroid TypeScript and Python SDKs

These examples are aligned with the current SDK surfaces documented on the TypeScript SDK and Python SDK pages.

Basic Execution

Start an execution and wait for the result using the high-level SDK helpers.

import { AsteroidClient, executeAgent, waitForExecutionResult } from 'asteroid-odyssey';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

const executionId = await executeAgent(client, 'your-agent-id', {
  dynamicData: {
    patientName: 'Jane Doe',
    appointmentDate: '2026-03-27',
  },
  metadata: {
    source: 'cookbook-basic',
  },
});

const result = await waitForExecutionResult(client, executionId);
console.log(result);

Interactive Run

Handle runs that pause and need a user message before they can continue.

import {
  AsteroidClient,
  executeAgent,
  getExecutionStatus,
  addMessageToExecution,
  waitForExecutionResult,
} from 'asteroid-odyssey';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

const executionId = await executeAgent(client, 'your-agent-id', {
  dynamicData: {
    task: 'Ask the user to confirm before submitting the final form',
  },
});

const status = await getExecutionStatus(client, executionId);
if (status.status === 'paused_by_agent') {
  await addMessageToExecution(client, executionId, 'Confirmed. Please continue.');
}

const result = await waitForExecutionResult(client, executionId);
console.log(result);

Files

Attach files to executions and download the files produced by a run.

import {
  AsteroidClient,
  AgentsV2SDK,
  executeAgent,
  getExecutionFiles,
  downloadExecutionFile,
  uploadExecutionFiles,
} from 'asteroid-odyssey';
import { readFileSync } from 'node:fs';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

const invoiceBytes = readFileSync('./invoice.pdf');
const invoice = new File([invoiceBytes], 'invoice.pdf', { type: 'application/pdf' });

const { data: staged } = await AgentsV2SDK.tempFilesStage({
  client: client.agentsV2Client,
  path: { organizationId: 'your-org-id' },
  body: { files: [invoice] },
});

const executionId = await executeAgent(client, 'your-agent-id', {
  dynamicData: {
    task: 'Read the attached invoice and summarize it',
  },
  tempFiles: staged?.tempFiles,
});

await uploadExecutionFiles(client, executionId, [invoice]);

const files = await getExecutionFiles(client, executionId);
for (const file of files) {
  console.log(`${file.fileName}: ${file.fileSize} bytes`);
  await downloadExecutionFile(client, file, './downloads/');
}

Related Resources

TypeScript SDK

See the current TypeScript helper and generated namespaces

Python SDK

See the current Python high-level client and generated subpackages