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.

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

Quick Start

1

Install Dependencies

Install the required packages:

npm install asteroid-odyssey typescript ts-node
2

Create Your File

Create a new file called example.ts and add this code:

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);
  }
})();
3

Run Your Code

Run the example using ts-node:

npx ts-node example.ts

Replace YOUR_API_KEY with your actual API key and YOUR_AGENT_ID with the ID of an agent you’ve created in the Asteroid Platform.

See API Keys for more details.

Quick Reference

OperationCodeReturns
Create ClientAsteroidClient('api_key')Client
Execute AgentexecuteAgent(client, agentId, { dynamic_data: data, agent_profile_id: 'YOUR_AGENT_PROFILE_ID' })Promise<string> (execution ID)
Wait for ResultwaitForExecutionResult(client, executionId)Promise<Record<string, unknown>>
Check StatusgetExecutionStatus(client, executionId)Promise<ExecutionStatusResponse>
Get ResultgetExecutionResult(client, executionId)Promise<Record<string, unknown>>

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

Your agent’s prompt variables depend on how you’ve configured them in the platform. The DATA parameter shown in examples assumes your agent has a {{.DATA}} variable configured.

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

IssueSolution
Authentication errorsVerify your API key is correct and active
Agent not foundEnsure the agent ID exists and you have access
Execution timeoutIncrease timeout or check agent performance
Missing prompt variablesMatch execution data keys to your agent’s variables

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

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