TypeScript SDK

The Asteroid Odyssey TypeScript SDK provides a simple way to interact with the Asteroid Agents API for triggering and monitoring agent executions, checking statuses, and retrieving results.

​

Quick Start

npm install asteroid-odyssey typescript ts-node

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

(async () => {
  // Initialize the client with your API key
  const client = AsteroidClient('YOUR_API_KEY');

  // Execute an agent with prompt variables, assuming the agent has a {{.DATA}} variable configured
  const executionId = await executeAgent(client, 'YOUR_AGENT_ID', {
    dynamic_data: {
      DATA: "First name: John, Last name: Smith"
    },
    agent_profile_id: 'YOUR_AGENT_PROFILE_ID'
  });
  console.log("Agent execution started:", executionId);

  // Wait for execution to complete and retrieve the result
  try {
    const result = await waitForExecutionResult(client, executionId);
    console.log("Agent result:", result);
  } catch (err) {
    console.error("Agent execution failed:", err);
  }
})();

npx ts-node example.ts

​

Quick Reference

​

API Reference

​

AsteroidClient

Create an API client with authentication.

import { AsteroidClient } from 'asteroid-odyssey';

// Basic usage
const client = AsteroidClient('YOUR_API_KEY');

// With custom base URL
const client = AsteroidClient('YOUR_API_KEY', {
  baseUrl: 'https://your-custom-domain.com/api/v1'
});

Parameters:

• apiKey (string): Your API key for authentication
• options (optional): Configuration object
  • baseUrl (string, optional): Custom API base URL. Defaults to https://odyssey.asteroid.ai/api/v1

Returns: A configured API client

​

executeAgent

Execute an agent with prompt variables.

import { executeAgent } from 'asteroid-odyssey';

const executionId = await executeAgent(client, 'YOUR_AGENT_ID', {
  dynamic_data: {
    DATA: "First name: John, Last name: Smith"
  },
  agent_profile_id: 'YOUR_AGENT_PROFILE_ID'
});

Parameters:

• client: The configured API client
• agentId (string): The ID of the agent to execute
• executionData (object): Prompt variables for your agent

Returns: Promise<string> - The execution ID

Throws: Error if the execution fails to start

​

waitForExecutionResult

Wait for an agent execution to complete and return the result.

import { waitForExecutionResult } from 'asteroid-odyssey';

// With default settings (1s polling, 1h timeout)
const result = await waitForExecutionResult(client, executionId);

// With custom settings
const result = await waitForExecutionResult(client, executionId, 2000, 1800000);

Parameters:

• client: The configured API client
• executionId (string): The execution ID
• interval (number, optional): Polling interval in milliseconds. Default: 1000ms
• timeout (number, optional): Maximum wait time in milliseconds. Default: 3600000ms (1 hour)

Returns: Promise<Record<string, unknown>> - The final result

Throws: Error if execution fails, is cancelled, or times out

​

getExecutionStatus

Check the current status of an execution.

import { getExecutionStatus } from 'asteroid-odyssey';

const status = await getExecutionStatus(client, executionId);
console.log("Status:", status.status); // "running", "completed", "failed", "cancelled"

Parameters:

• client: The configured API client
• executionId (string): The execution ID

Returns: Promise<ExecutionStatusResponse> with:

• status: Current execution status
• reason: Optional reason for failure/cancellation

​

getExecutionResult

Get the result of a completed execution.

import { getExecutionResult } from 'asteroid-odyssey';

const result = await getExecutionResult(client, executionId);

Parameters:

• client: The configured API client
• executionId (string): The execution ID

Returns: Promise<Record<string, unknown>> - The result object

Throws: Error if there’s an error retrieving the result

​

Basic Error Handling

try {
  const result = await waitForExecutionResult(client, executionId);
  console.log("Success:", result);
} catch (error) {
  console.error('Execution failed:', error.message);
  // Error messages include context like:
  // "Execution abc123 ended with status: failed - Agent encountered an error"
  // "Execution abc123 timed out after 3600000ms"
}

​

Prompt Variables

Example with multiple variables:

const executionId = await executeAgent(client, 'form-filler-agent', {
  dynamic_data: {
    FIRST_NAME: "John",
    LAST_NAME: "Smith", 
    EMAIL: "john.smith@example.com"
  },
  agent_profile_id: 'YOUR_AGENT_PROFILE_ID'
});

​

Best Practices

• API Keys: Use environment variables (process.env.ASTEROID_API_KEY)
• Error Handling: Always wrap SDK calls in try-catch blocks
• Long Executions: Use custom timeout values for agents that take longer
• Debugging: Log execution IDs for troubleshooting in the platform

​

Common Issues

For detailed examples and advanced usage patterns, see TypeScript Examples.

For more help, visit the Asteroid Platform or check your execution logs there.