TypeScript SDK

Use the Asteroid TypeScript SDK to execute agents, monitor runs, and manage profiles

Use the asteroid-odyssey TypeScript SDK to execute agents, monitor executions, work with files, and manage profiles from your application.

Most integrations start with AsteroidClient plus the high-level helpers such as executeAgent and waitForExecutionResult. If you need lower-level endpoint access, the package also exports generated namespaces.

Install

npm install asteroid-odyssey

Or with pnpm:

pnpm add asteroid-odyssey

Quickstart

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

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

const executionId = await executeAgent(client, 'your-agent-id', {
  dynamicData: {
    customerName: 'Jane Doe',
  },
  metadata: {
    source: 'docs',
  },
  version: 3,
});

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

Run it with:

npx tsx run_agent.ts

High-Level Exports

These are the top-level helpers exported from asteroid-odyssey:

Export	Purpose
AsteroidClient	Configure the SDK with your API key
executeAgent	Execute an agent with the v2 request shape
getAgents	List agents with pagination
getExecutions	List executions with filters
getExecutionStatus	Fetch execution status
getExecutionResult	Fetch the final execution result
waitForExecutionResult	Poll until an execution completes
getLastNExecutionActivities	Fetch recent execution activities
addMessageToExecution	Send a user message to a running execution
uploadExecutionFiles	Upload files to a running execution
getExecutionFiles	List files on an execution
downloadExecutionFile	Download an execution file using its signed URL
getAgentProfiles / getAgentProfile	Read agent profiles
createAgentProfile / updateAgentProfile / deleteAgentProfile	Manage agent profiles
getCredentialsPublicKey	Fetch the public key used for encrypting profile credentials
getBrowserSessionRecording	Fetch the v1 browser recording response

Generated Namespaces

If you need lower-level endpoint access instead of the helper layer, import the generated namespaces directly:

import { AsteroidClient, AgentsV2SDK } from 'asteroid-odyssey';

const { agentsV2Client } = AsteroidClient(process.env.ASTEROID_API_KEY!);

const { data, error } = await AgentsV2SDK.agentExecutePost({
  client: agentsV2Client,
  path: { agentId: 'your-agent-id' },
  body: {
    dynamicData: {
      customerName: 'Jane Doe',
    },
  },
});

if (error) {
  console.error(error);
} else {
  console.log(data?.executionId);
}

Useful generated namespaces include:

• AgentsV2SDK for execution, files, and list endpoints
• AgentsV1SDK for legacy helpers such as execution result and profile endpoints
• AgentsV2Types and AgentsV1Types for the generated request and response types

Common Patterns

Executions

import {
  AsteroidClient,
  executeAgent,
  getExecutions,
  getLastNExecutionActivities,
  addMessageToExecution,
} from 'asteroid-odyssey';

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

const executionId = await executeAgent(client, 'your-agent-id', {
  dynamicData: {
    task: 'Summarize the attached invoice',
  },
});

const page = await getExecutions(client, {
  query: {
    page: 1,
    pageSize: 10,
    executionId,
  },
});

const activities = await getLastNExecutionActivities(client, executionId, 20);
await addMessageToExecution(client, executionId, 'Please use the latest file only.');

console.log(page.items);
console.log(activities.map((activity) => activity.payload.activityType));

Files

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

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

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

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

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

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

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

Profiles

import {
  AsteroidClient,
  getAgentProfiles,
  createAgentProfile,
  updateAgentProfile,
} from 'asteroid-odyssey';

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

const profiles = await getAgentProfiles(client, 'your-org-id');
console.log(profiles.map((profile) => `${profile.id}: ${profile.name}`));

const created = await createAgentProfile(client, {
  name: 'Shared Billing Profile',
  description: 'Reusable browser profile for billing workflows',
  organization_id: 'your-org-id',
  proxy_cc: 'us',
  proxy_type: 'residential',
  captcha_solver_active: false,
  sticky_ip: false,
  credentials: [],
  cookies: [],
});

await updateAgentProfile(client, created.id, {
  description: 'Updated description',
});

Notes

• The v2 execution request shape uses dynamicData, not inputs.
• The top-level helpers do not currently expose profile pool operations. Use the profile pool endpoint pages under /api-reference/endpoints/agent-profile-pools/ when you need those workflows.
• AsteroidClient accepts optional v1.baseUrl and v2.baseUrl overrides if you need to point at non-default environments.

Related Resources

Python SDK

See the Python SDK guide

API

Browse the API landing page and common workflows