Skip to main content
1

Installation

pip install --upgrade asteroid-odyssey
2

Create your Python file (run_agent.py)

from asteroid_odyssey import AsteroidClient

# Create client and execute agent
client = AsteroidClient('your-api-key')

execution_id = client.execute_agent(
    agent_id='your-agent-id',
    execution_data={'input': 'your data'}
)

# Wait for result
result = client.wait_for_execution_result(execution_id)
print(result)
3

Run the agent

Replace your API key, your agent_id, and update the execution_data with your agent’s variables (or remove if no variables), then run:
python run_agent.py
Agent Creation: Agents can only be created through the Asteroid Platform web interface. The API is designed for executing existing agents, not creating them.

​
Method Reference

  • Quick Reference
  • Detailed Signatures
  • Standalone Functions
MethodPurposeReturns
execute_agent()Start agent executionexecution_id
wait_for_execution_result()Wait for completionresult
get_execution_status()Check current statusstatus_info
get_execution_result()Get final resultresult
upload_execution_files()Upload filesupload_response
get_browser_session_recording()Get recording URLurl
get_last_n_execution_activities()Get last N activitieslist
add_message_to_execution()Add message to executionNone
wait_for_agent_interaction()Wait for interaction or completionAgentInteractionResult
get_agents()Get a paginated list of agentslist
get_agent_profiles()Get list of agent profileslist
get_agent_profile()Get agent profile by IDprofile
create_agent_profile()Create new agent profileprofile
update_agent_profile()Update existing agent profileprofile
delete_agent_profile()Delete agent profilestring

Python Examples

Comprehensive examples including file uploads, error handling, and real-world workflows

API Reference

Complete API documentation with all available endpoints

​
Core Methods

Execute an agent with the provided parameters.Parameters:
  • agent_id: The ID of the agent to execute
  • execution_data: The execution parameters
  • agent_profile_id: Optional ID of the agent profile
Returns: The execution IDRaises:
  • Exception: If the execution request fails
execution_id = client.execute_agent('my-agent-id', {'input': 'some dynamic value'}, 'agent-profile-id')
Get the current status for an execution.Parameters:
  • execution_id: The execution identifier
Returns: The execution status detailsRaises:
  • Exception: If the status request fails
status = client.get_execution_status(execution_id)
print(status.status)
Get the final result of an execution.Parameters:
  • execution_id: The execution identifier
Returns: The result object of the executionRaises:
  • Exception: If the result request fails or execution failed
result = client.get_execution_result(execution_id)
print(result)
Wait for an execution to reach a terminal state and return the result. Continuously polls the execution status until it’s either “completed”, “cancelled”, or “failed”.Parameters:
  • execution_id: The execution identifier
  • interval: Polling interval in seconds (default is 1.0)
  • timeout: Maximum wait time in seconds (default is 3600 - 1 hour)
Returns: The execution result if completedRaises:
  • Exception: If the execution ends as “cancelled” or “failed”, or times out
result = client.wait_for_execution_result(execution_id, interval=2.0)
Upload files to an execution.Parameters:
  • execution_id: The execution identifier
  • files: List of files to upload. Each file can be:
  • default_filename: Default filename to use when file is provided as bytes
Returns: The upload response containing message and file IDsRaises:
  • Exception: If the upload request fails
# Upload with file content (file should be in your current working directory)
with open('hello.txt', 'r') as f:
file_content = f.read()
response = client.upload_execution_files(execution_id, [file_content.encode()])
print(f"Uploaded files: {response.file_ids}")
# Upload with filename and content
files = [('hello.txt', file_content.encode())]
response = client.upload_execution_files(execution_id, files)
# Or create content directly
hello_content = "Hello World!".encode()
response = client.upload_execution_files(execution_id, [hello_content])
Get the browser session recording URL for a completed execution.Parameters:
  • execution_id: The execution identifier
Returns: The URL of the browser session recordingRaises:
  • Exception: If the recording request fails
recording_url = client.get_browser_session_recording(execution_id)
print(f"Recording available at: {recording_url}")
Get the last N execution activities for a given execution ID, sorted by their timestamp in descending order.Parameters:
  • execution_id: The execution identifier
  • n: The number of activities to return
Returns: A list of execution activitiesRaises:
  • Exception: If the execution activities request fails
activities = client.get_last_n_execution_activities(execution_id, 5)
Add a message to an execution.Parameters:
  • execution_id: The execution identifier
  • message: The message to add
Raises:
  • Exception: If the message addition fails
add_message_to_execution(client, "execution_id", "Hello, world!")
Wait for an agent interaction request or terminal state.This method polls an existing execution until it either:
  1. Requests human input (paused_by_agent state)
  2. Reaches a terminal state (completed, failed, cancelled)
  3. Times out
Parameters:
  • execution_id: The execution identifier for an already started execution
  • poll_interval: How often to check for updates in seconds (default: 2.0)
  • timeout: Maximum wait time in seconds (default: 3600 - 1 hour)
Returns: AgentInteractionResult containing:
  • is_terminal: True if execution finished (completed/failed/cancelled)
  • status: Current execution status string
  • agent_message: Agent’s message if requesting interaction (None if terminal)
  • execution_result: Final result if terminal state (None if requesting interaction)
Raises:
  • ValueError: If interval or timeout parameters are invalid
  • TimeoutError: If the execution times out
  • AsteroidAPIError: If API calls fail
# Start an execution first
execution_id = client.execute_agent('agent-id', {'input': 'test'})

# Wait for interaction or completion
result = client.wait_for_agent_interaction(execution_id)

if result.is_terminal:
    print(f"Execution finished with status: {result.status}")
    if result.execution_result:
        print(f"Result: {result.execution_result.outcome}")
else:
    print(f"Agent requesting input: {result.agent_message}")
    # Send response
    user_message = input(Your message: )
    client.add_message_to_execution(execution_id, user_message) 
    # Wait again
    result = client.wait_for_agent_interaction(execution_id)

​
Agent Profiles

Get a list of agent profiles for a specific organization.Parameters:
  • organization_id: The organization identifier (required)
Returns: A list of agent profilesRaises:
  • Exception: If the agent profiles request fails
profiles = client.get_agent_profiles("org-123")
Get an agent profile by ID.Parameters:
  • profile_id: The ID of the agent profile
Returns: The agent profileRaises:
  • Exception: If the agent profile request fails
profile = client.get_agent_profile("profile_id")
Create an agent profile with automatic credential encryption.Parameters:
  • request: The request object
Returns: The agent profileRaises:
  • Exception: If the agent profile creation fails
request = CreateAgentProfileRequest(
name="My Agent Profile",
description="This is my agent profile",
organization_id="org-123",
proxy_cc=CountryCode.US,
proxy_type=ProxyType.RESIDENTIAL,
captcha_solver_active=True,
sticky_ip=True,
credentials=[Credential(name="user", data="password")],
cookies=[
    Cookie(
        name="Session Cookie",
        key="session_id",
        value="abc123",
        domain="example.com",
        secure=True,
        http_only=True,
        same_site="Lax",
        created_at="2025-01-01T00:00:00Z"
    )
]
)
profile = client.create_agent_profile(request)
Update an agent profile with automatic credential encryption.Parameters:
  • profile_id: The ID of the agent profile
  • request: The request object
Returns: The agent profileRaises:
  • Exception: If the agent profile update fails
request = UpdateAgentProfileRequest(
name="My Agent Profile",
description="This is my agent profile",
credentials_to_add=[Credential(name="api_key", data="secret")],
cookies_to_add=[
    Cookie(
        name="Auth Token",
        key="auth_token",
        value="new-token",
        domain="example.com",
        secure=True,
        http_only=True,
        same_site="Strict",
        created_at="2025-01-01T00:00:00Z"
    )
],
cookies_to_delete=["cookie-id-to-remove"]
)
profile = client.update_agent_profile("profile_id", request)
Delete an agent profile.Parameters:
  • profile_id: The ID of the agent profile
Returns: Confirmation message from the serverRaises:
  • Exception: If the agent profile deletion fails
response = client.delete_agent_profile("profile_id")
Get the public key for encrypting credentials.Returns: PEM-formatted RSA public key stringRaises:
  • Exception: If the public key request fails
public_key = client.get_credentials_public_key()
Format an agent profile for nice display.Parameters:
  • profile: No description available
Format a list of agent profiles for nice display.Parameters:
  • profiles: No description available
⌘I