Python SDK

Installation

pip install --upgrade asteroid-odyssey

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)

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

Method	Purpose	Returns
`execute_agent()`	Start agent execution	`execution_id`
`wait_for_execution_result()`	Wait for completion	`result`
`get_execution_status()`	Check current status	`status_info`
`get_execution_result()`	Get final result	`result`
`upload_execution_files()`	Upload files	`upload_response`
`get_browser_session_recording()`	Get recording URL	`url`
`get_last_n_execution_activities()`	Get last N activities	`list`
`add_message_to_execution()`	Add message to execution	`None`
`wait_for_agent_interaction()`	Wait for interaction or completion	`AgentInteractionResult`
`get_agents()`	Get a paginated list of agents	`list`
`get_agent_profiles()`	Get list of agent profiles	`list`
`get_agent_profile()`	Get agent profile by ID	`profile`
`create_agent_profile()`	Create new agent profile	`profile`
`update_agent_profile()`	Update existing agent profile	`profile`
`delete_agent_profile()`	Delete agent profile	`string`

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_agent() - Execute an agent with the provided parameters

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_execution_status() - Get the current status for an execution

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_execution_result() - Get the final result of an execution

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_execution_result() - Wait for an execution to reach a terminal state and return the 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_execution_files() - Upload files to an execution

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_browser_session_recording() - Get the browser session recording URL for a completed execution

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_last_n_execution_activities() - Get the last N execution activities for a given execution ID, sorted by their timestamp in descending order

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_message_to_execution() - Add a message to an execution

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_agent_interaction() - Wait for an agent interaction request or terminal state

Wait for an agent interaction request or terminal state.This method polls an existing execution until it either:

Requests human input (paused_by_agent state)
Reaches a terminal state (completed, failed, cancelled)
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_agent_profiles() - Get a list of agent profiles for a specific organization

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_agent_profile() - Get an agent profile by ID

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_agent_profile() - Create an agent profile with automatic credential encryption

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_agent_profile() - Update an agent profile with automatic credential encryption

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_agent_profile() - Delete an agent profile

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_credentials_public_key() - Get the public key for encrypting credentials

format_agent_profile() - Format an agent profile for nice display

format_agent_profiles_list() - Format a list of agent profiles for nice display

Get Started

Fundamentals

SDKs

Changelog

Support & Security

Method Reference

Python Examples

API Reference

Core Methods

Agent Profiles

Get Started

Fundamentals

SDKs

Changelog

Support & Security

​Method Reference

Python Examples

API Reference

​Core Methods

​Agent Profiles

Method Reference

Core Methods

Agent Profiles