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.

The SDK exports a client singleton and individual endpoint functions. Configure the client once with your API key, then call the functions directly.

Install

npm install asteroid-odyssey

Or with pnpm:

pnpm add asteroid-odyssey

Quickstart

import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

const { data, error } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: {
      customerName: 'Jane Doe',
    },
    metadata: {
      source: 'docs',
    },
  },
});

if (error) throw new Error(JSON.stringify(error));
const executionId = data.executionId;

// Poll until complete
let exec;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const res = await executionGet({ path: { executionId } });
  exec = res.data;
} while (exec?.status === 'running' || exec?.status === 'starting');

console.log(exec?.status, exec?.inputs);

Run it with:

npx tsx run_agent.ts

Client Configuration

All SDK functions share the singleton client. Configure it once at startup:

import { client } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  // Optional: override the base URL
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
});

Every function accepts an optional client override if you need per-request auth:

const { data } = await executionGet({
  client: myOtherClient,
  path: { executionId },
});

Common Functions

The most frequently used functions are listed below. See the API reference for the full set.

Function	Purpose
contextGet	Fetch your user context, including organization IDs
agentList	List agents with pagination
agentCreate	Create an agent with an initial workflow
agentByIdUpdate	Rename an agent (name must be 1-100 characters)
agentByIdDelete	Delete an agent and its workflows
agentExecutePost	Execute an agent
executionGet	Fetch execution details
executionsList	List executions with filters
executionActivitiesGet	Fetch execution activities (returns Array)
executionStatusUpdate	Update execution status (e.g. cancel)
executionUserMessagesAdd	Send a user message to a running execution
executionContextFilesGet	List files on an execution
executionContextFilesUpload	Upload files to a running execution
tempFilesStage	Stage temporary files before execution
agentProfilesList	List agent profiles (filter with organizationId)
agentProfilesCreate	Create an agent profile
agentProfileGet	Fetch a single profile
agentProfileUpdate	Update a profile
agentProfileDelete	Delete a profile
agentWorkflowsExecute	Execute a specific workflow version

Common Patterns

Executions

import {
  client,
  agentExecutePost,
  executionsList,
  executionActivitiesGet,
  executionUserMessagesAdd,
} from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

const { data } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: {
      task: 'Summarize the attached invoice',
    },
  },
});
const executionId = data!.executionId;

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

const { data: activities } = await executionActivitiesGet({
  path: { executionId },
  query: { limit: 20, order: 'desc' },
});

await executionUserMessagesAdd({
  path: { executionId },
  body: { message: 'Please use the latest file only.' },
});

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

Files

import {
  client,
  agentExecutePost,
  tempFilesStage,
  executionContextFilesUpload,
  executionContextFilesGet,
} from 'asteroid-odyssey';
import { readFileSync, writeFileSync } from 'node:fs';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

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

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

const { data } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: { task: 'Read the staged file' },
    tempFiles: staged?.tempFiles,
  },
});
const executionId = data!.executionId;

await executionContextFilesUpload({
  path: { executionId },
  body: { files: [invoice] },
});

const { data: files } = await executionContextFilesGet({
  path: { executionId },
});
for (const file of files ?? []) {
  const response = await fetch(file.downloadUrl, {
    headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
  });
  if (!response.ok) throw new Error(`Download failed: ${response.status}`);
  // Strip any path components from the server-provided name to avoid path traversal.
  const safeName = file.fileName.replace(/[/\\]/g, '_');
  writeFileSync(`./downloads/${safeName}`, Buffer.from(await response.arrayBuffer()));
}

Profiles

import {
  client,
  agentProfilesList,
  agentProfilesCreate,
  agentProfileUpdate,
} from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

const { data: profiles } = await agentProfilesList({
  query: { organizationId: 'your-org-id', page: 1, pageSize: 20 },
});
console.log(profiles?.items?.map((p) => `${p.id}: ${p.name}`));

const { data: created } = await agentProfilesCreate({
  body: {
    name: 'Shared Billing Profile',
    description: 'Reusable browser profile for billing workflows',
    organizationId: 'your-org-id',
    proxyMode: 'managed',
    proxyCC: 'us',
    captchaSolverActive: false,
    stickyIP: false,
    credentials: [],
    cookies: [],
  },
});

await agentProfileUpdate({
  path: { profileId: created!.id },
  body: { description: 'Updated description' },
});

Notes

• Use inputs for execution variables — dynamicData is deprecated.
• executionActivitiesGet returns Array<AgentsExecutionActivity> directly, not a wrapped object.
• All functions return { data, error }. Check error before using data.
• File list responses include a downloadUrl per file. Fetch it with your API key in the X-Asteroid-Agents-Api-Key header.

Related Resources

Python SDK

See the Python SDK guide

API

Browse the API landing page and common workflows