TypeScript SDK

Installation

npm install asteroid-odyssey

Or with pnpm:

pnpm add asteroid-odyssey

Create your TypeScript file (run_agent.ts)

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

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

// Terminal statuses
const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];

// Execute an agent
const { data } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: { username: 'john@example.com' },
  },
});

const executionId = data?.executionId;
console.log(`Execution started: ${executionId}`);

// Poll for result
let execution: AgentsExecutionListItem | undefined;
while (true) {
  const { data: result } = await executionGet({
    path: { executionId: executionId! },
  });
  execution = result;
  console.log(`Status: ${execution?.status}`);

  if (TERMINAL_STATUSES.includes(execution?.status ?? '')) {
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 2000));
}

console.log(`Final status: ${execution?.status}`);

Run the agent

Replace your API key, your agent_id, and update the inputs with your agent’s variables (or remove if no variables), then run:

npx tsx run_agent.ts

Agent Creation: Agents can only be created through the Asteroid Platform web interface. The API is designed for executing existing agents, not creating them.

SDK Functions

The SDK provides the following functions:

Function	Purpose
`agentList`	List agents
`agentExecutePost`	Execute an agent
`executionsList`	List executions with filtering
`executionGet`	Get execution details and status
`executionActivitiesGet`	Get execution activities
`executionStatusUpdate`	Pause, resume, or cancel an execution
`executionUserMessagesAdd`	Send a message to a running execution
`executionContextFilesGet`	Get files from an execution
`executionContextFilesUpload`	Upload files to a running execution
`tempFilesStage`	Stage files before starting an execution
`agentProfilesList`	List agent profiles
`agentProfileGet`	Get a specific profile
`agentProfilesCreate`	Create a new profile
`agentProfileUpdate`	Update an existing profile
`agentProfileDelete`	Delete a profile
`agentProfileClearBrowserCache`	Clear browser cache for a profile

Quick Reference

Agents
Executions
Files
Agent Profiles

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

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

// List all agents
const { data: agents } = await agentList();
for (const agent of agents?.items ?? []) {
  console.log(`${agent.id}: ${agent.name}`);
}

// List with pagination and search
const { data: filtered } = await agentList({
  query: {
    pageSize: 10,
    page: 1,
    searchName: 'My Agent',
  },
});

// Execute an agent
const { data: execution } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: { username: 'user@example.com', date: '2025-01-15' },
    agentProfileId: 'optional-profile-id', // Optional
  },
});
console.log(`Execution ID: ${execution?.executionId}`);

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

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

// List executions
const { data: executions } = await executionsList({
  query: { pageSize: 10 },
});
for (const exec of executions?.items ?? []) {
  console.log(`${exec.id}: ${exec.status}`);
}

// Get execution details
const { data: execution } = await executionGet({
  path: { executionId: 'your-execution-id' },
});
console.log(`Status: ${execution?.status}`);
console.log(`Agent ID: ${execution?.agentId}`);

// Get execution activities
const { data: activities } = await executionActivitiesGet({
  path: { executionId: 'your-execution-id' },
});
for (const activity of activities ?? []) {
  console.log(`Activity: ${activity.payload.activityType}`);
}

// Send a message to a running execution
await executionUserMessagesAdd({
  path: { executionId: 'your-execution-id' },
  body: { message: 'Hello from the user!' },
});

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

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

// Get files from an execution
const { data: files } = await executionContextFilesGet({
  path: { executionId: 'your-execution-id' },
});
for (const f of files ?? []) {
  console.log(`${f.fileName}: ${f.fileSize} bytes`);
  // Download using the signed URL
  const response = await fetch(f.signedUrl);
  const buffer = await response.arrayBuffer();
  // Save to disk or process as needed
}

// Upload files to a running execution
const fileContent = readFileSync('myfile.pdf');
const file = new File([fileContent], 'myfile.pdf', { type: 'application/pdf' });
await executionContextFilesUpload({
  path: { executionId: 'your-execution-id' },
  body: { files: [file] },
});

// Stage files before starting an execution
const { data: staged } = await tempFilesStage({
  path: { organizationId: 'your-org-id' },
  body: { files: [file] },
});

// Use staged files when starting execution
const { data: execution } = await agentExecutePost({
  path: { agentId: 'your-agent-id' },
  body: {
    inputs: { task: 'Process these files' },
    tempFiles: staged?.tempFiles,
  },
});

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

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

// List profiles for an organization
const { data: profiles } = await agentProfilesList({
  query: { organizationId: 'your-org-id' },
});
for (const profile of profiles?.items ?? []) {
  console.log(`${profile.id}: ${profile.name}`);
}

// Get a specific profile
const { data: profile } = await agentProfileGet({
  path: { profileId: 'your-profile-id' },
});
console.log(`Name: ${profile?.name}`);
console.log(`OS: ${profile?.operatingSystem}`);

// Create a new profile
const { data: newProfile } = await agentProfilesCreate({
  body: {
    name: 'My Profile',
    description: 'Profile description',
    organizationId: 'your-org-id',
    proxyCC: 'us',
    proxyType: 'residential',
  },
});

// Update a profile
await agentProfileUpdate({
  path: { profileId: 'your-profile-id' },
  body: { name: 'Updated Profile Name' },
});

// Delete a profile
await agentProfileDelete({
  path: { profileId: 'your-profile-id' },
});

// Clear browser cache for a profile
await agentProfileClearBrowserCache({
  path: { profileId: 'your-profile-id' },
});

Complete Examples

Execute an agent and wait for completion

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

// Terminal statuses
const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];

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

  // Execute agent
  const { data, error } = await agentExecutePost({
    path: { agentId: 'your-agent-id' },
    body: {
      inputs: {
        username: 'user@example.com',
        order_id: 'ORD-12345',
      },
    },
  });

  if (error || !data) {
    console.error('Failed to start execution:', error);
    return;
  }

  const executionId = data.executionId;
  console.log(`Execution started: ${executionId}`);

  // Poll for completion
  let execution: AgentsExecutionListItem | undefined;
  while (true) {
    const { data: result } = await executionGet({
      path: { executionId },
    });
    execution = result;
    console.log(`Status: ${execution?.status}`);

    if (TERMINAL_STATUSES.includes(execution?.status ?? '')) {
      break;
    }
    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  console.log(`Execution finished with status: ${execution?.status}`);
}

main().catch(console.error);

Interactive agent with user messages

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

const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];

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

  // Start execution
  const { data } = await agentExecutePost({
    path: { agentId: 'your-agent-id' },
    body: {
      inputs: { task: 'Book an appointment' },
    },
  });

  if (!data) {
    console.error('Failed to start execution');
    return;
  }

  const executionId = data.executionId;
  console.log(`Execution started: ${executionId}`);

  while (true) {
    const { data: execution } = await executionGet({
      path: { executionId },
    });
    const status = execution?.status;
    console.log(`Status: ${status}`);

    if (TERMINAL_STATUSES.includes(status ?? '')) {
      console.log(`Execution completed with status: ${status}`);
      break;
    }

    if (status === 'paused_by_agent') {
      // Agent is waiting for user input
      console.log('Agent is waiting for input...');

      const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
      });

      const userInput = await new Promise<string>(resolve => {
        rl.question('Your response: ', answer => {
          rl.close();
          resolve(answer);
        });
      });

      await executionUserMessagesAdd({
        path: { executionId },
        body: { message: userInput },
      });
      console.log('Message sent!');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

main().catch(console.error);

Upload files to an execution

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

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

  const executionId = 'your-execution-id';

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

  await executionContextFilesUpload({
    path: { executionId },
    body: { files: [file] },
  });
  console.log('File uploaded successfully!');

  // Upload multiple files
  const files = ['file1.txt', 'file2.txt'].map(filename => {
    const content = readFileSync(filename);
    return new File([content], filename, { type: 'text/plain' });
  });

  await executionContextFilesUpload({
    path: { executionId },
    body: { files },
  });
  console.log(`Uploaded ${files.length} files`);
}

uploadFilesExample().catch(console.error);

Create and use an agent profile

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

const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];

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

  // Create a profile with proxy and cookies
  const { data: profile } = await agentProfilesCreate({
    body: {
      name: 'E-commerce Profile',
      description: 'Profile for e-commerce automation',
      organizationId: 'your-org-id',
      proxyCC: 'us',
      proxyType: 'residential',
      captchaSolverActive: true,
      cookies: [
        {
          name: 'session',
          key: 'session_id',
          value: 'abc123',
          domain: 'example.com',
          secure: true,
          httpOnly: true,
          sameSite: 'Lax',
        },
      ],
    },
  });
  console.log(`Created profile: ${profile?.id}`);

  // Execute an agent with the profile
  const { data: execution } = await agentExecutePost({
    path: { agentId: 'your-agent-id' },
    body: {
      inputs: { product_url: 'https://example.com/product/123' },
      agentProfileId: profile?.id,
    },
  });
  console.log(`Execution started: ${execution?.executionId}`);

  // Wait for completion
  while (true) {
    const { data: result } = await executionGet({
      path: { executionId: execution?.executionId! },
    });
    if (TERMINAL_STATUSES.includes(result?.status ?? '')) {
      console.log(`Finished with status: ${result?.status}`);
      break;
    }
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

profileExample().catch(console.error);

Configuration Options

import { client } from 'asteroid-odyssey';

// Basic configuration
client.setConfig({
  headers: {
    'X-Asteroid-Agents-Api-Key': 'your-api-key',
  },
});

// Custom host (for self-hosted or development)
client.setConfig({
  baseUrl: 'https://custom-host.example.com/agents/v2',
  headers: {
    'X-Asteroid-Agents-Api-Key': 'your-api-key',
  },
});

Execution Statuses

Status	Description
`starting`	Execution is initializing
`running`	Agent is actively working
`paused`	Execution is paused
`paused_by_agent`	Agent is waiting for user input
`awaiting_confirmation`	Waiting for confirmation
`completed`	Successfully finished
`failed`	Execution failed
`cancelled`	Execution was cancelled

Error Handling

import { agentExecutePost } from 'asteroid-odyssey';

const { data, error } = await agentExecutePost({
  path: { agentId: 'invalid-id' },
  body: { inputs: {} },
});

if (error) {
  // error contains the error response from the API
  console.error('API Error:', error);
  return;
}

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

Cookbook Examples

More practical examples including complex workflows

API Reference

Complete API documentation with all available endpoints

Get Started

Astro

Fundamentals

SDKs

What's New

Support & Security

SDK Functions

Quick Reference

Complete Examples

Configuration Options

Execution Statuses

Error Handling

Cookbook Examples

API Reference

Get Started

Astro

Fundamentals

SDKs

What's New

Support & Security

​SDK Functions

​Quick Reference

​Complete Examples

​Configuration Options

​Execution Statuses

​Error Handling

Cookbook Examples

API Reference

SDK Functions

Quick Reference

Complete Examples

Configuration Options

Execution Statuses

Error Handling