Interact with Asteroid Agents using TypeScript
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.
Install Dependencies
Install the required packages:
Create Your File
Create a new file called example.ts
and add this code:
Run Your Code
Run the example using ts-node:
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.
Operation | Code | Returns |
---|---|---|
Create Client | AsteroidClient('api_key') | Client |
Execute Agent | executeAgent(client, agentId, { dynamic_data: data, agent_profile_id: 'YOUR_AGENT_PROFILE_ID' }) | Promise<string> (execution ID) |
Wait for Result | waitForExecutionResult(client, executionId) | Promise<Record<string, unknown>> |
Check Status | getExecutionStatus(client, executionId) | Promise<ExecutionStatusResponse> |
Get Result | getExecutionResult(client, executionId) | Promise<Record<string, unknown>> |
Advanced examples, error handling patterns, and real-world use cases
How to create and manage your API keys
Create an API client with authentication.
Parameters:
apiKey
(string): Your API key for authenticationoptions
(optional): Configuration object
baseUrl
(string, optional): Custom API base URL. Defaults to https://odyssey.asteroid.ai/api/v1
Returns: A configured API client
Execute an agent with prompt variables.
Parameters:
client
: The configured API clientagentId
(string): The ID of the agent to executeexecutionData
(object): Prompt variables for your agentReturns: Promise<string>
- The execution ID
Throws: Error
if the execution fails to start
Wait for an agent execution to complete and return the result.
Parameters:
client
: The configured API clientexecutionId
(string): The execution IDinterval
(number, optional): Polling interval in milliseconds. Default: 1000mstimeout
(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
Check the current status of an execution.
Parameters:
client
: The configured API clientexecutionId
(string): The execution IDReturns: Promise<ExecutionStatusResponse>
with:
status
: Current execution statusreason
: Optional reason for failure/cancellationGet the result of a completed execution.
Parameters:
client
: The configured API clientexecutionId
(string): The execution IDReturns: Promise<Record<string, unknown>>
- The result object
Throws: Error
if there’s an error retrieving the result
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:
process.env.ASTEROID_API_KEY
)Issue | Solution |
---|---|
Authentication errors | Verify your API key is correct and active |
Agent not found | Ensure the agent ID exists and you have access |
Execution timeout | Increase timeout or check agent performance |
Missing prompt variables | Match 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.