Python SDK

Use the Asteroid Python SDK to execute agents, monitor runs, and manage profiles

Use the asteroid-odyssey Python SDK to execute agents, monitor executions, work with files, and manage profiles from your application.

Most integrations start with AsteroidClient from the top-level asteroid_odyssey package. If you need lower-level endpoint access, generated clients are also available from the versioned subpackages.

Install

pip install --upgrade asteroid-odyssey

Or with uv:

uv pip install asteroid-odyssey

Quickstart

import os
from asteroid_odyssey import AsteroidClient

client = AsteroidClient(os.environ["ASTEROID_API_KEY"])

execution_id = client.execute_agent(
    agent_id="your-agent-id",
    execution_data={
        "customerName": "Jane Doe",
    },
)

result = client.wait_for_execution_result(execution_id)
print(result)

Run it with:

python run_agent.py

Top-Level Exports

The root package exports these high-level helpers:

Export	Purpose
AsteroidClient	Main high-level client
create_client	Factory helper that returns AsteroidClient
execute_agent	Execute an agent
get_execution_status	Fetch execution status
get_execution_result	Fetch the final execution result
wait_for_execution_result	Poll until completion
wait_for_agent_interaction	Wait for an execution to request user input
upload_execution_files	Upload files to an execution
get_browser_session_recording	Fetch the recording URL
get_agent_profiles / get_agent_profile	Read agent profiles
create_agent_profile / update_agent_profile / delete_agent_profile	Manage agent profiles
get_last_n_execution_activities	Fetch recent activities
add_message_to_execution	Send a user message to a running execution
get_credentials_public_key	Fetch the public key used for profile credential encryption

Generated Clients

The top-level package does not re-export generated classes like Configuration, ApiClient, AgentsApi, or ExecutionApi. If you need lower-level endpoint access, import them from the versioned subpackages:

import os
from asteroid_odyssey.agents_v2_gen import Configuration, ApiClient
from asteroid_odyssey.agents_v2_gen.api.agents_api import AgentsApi
from asteroid_odyssey.agents_v2_gen.models.agents_agent_execute_agent_request import (
    AgentsAgentExecuteAgentRequest,
)

config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

with ApiClient(config) as api_client:
    agents_api = AgentsApi(api_client)
    response = agents_api.agent_execute_post(
        agent_id="your-agent-id",
        agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
            dynamic_data={"customerName": "Jane Doe"},
        ),
    )
    print(response.execution_id)

Common Patterns

Executions

import os
from asteroid_odyssey import AsteroidClient

client = AsteroidClient(os.environ["ASTEROID_API_KEY"])

execution_id = client.execute_agent(
    agent_id="your-agent-id",
    execution_data={"task": "Summarize the attached invoice"},
)

activities = client.get_last_n_execution_activities(execution_id, 20)
client.add_message_to_execution(execution_id, "Please use the latest file only.")

status = client.get_execution_status(execution_id)
print(status.status)
for activity in activities:
    print(activity.payload)

Files

import os
from asteroid_odyssey import AsteroidClient

client = AsteroidClient(os.environ["ASTEROID_API_KEY"])

execution_id = client.execute_agent(
    agent_id="your-agent-id",
    execution_data={"task": "Read the uploaded invoice"},
)

client.upload_execution_files(execution_id, ["./invoice.pdf"])

files = client.get_execution_files(execution_id)
for file in files:
    print(f"{file.file_name}: {file.file_size} bytes")
    client.download_execution_file(file, "./downloads/")

Profiles

import os
from asteroid_odyssey import AsteroidClient
from asteroid_odyssey.agents_v1_gen import (
    CountryCode,
    CreateAgentProfileRequest,
    ProxyType,
)

client = AsteroidClient(os.environ["ASTEROID_API_KEY"])

profiles = client.get_agent_profiles("your-org-id")
print([profile.name for profile in profiles])

request = CreateAgentProfileRequest(
    name="Shared Billing Profile",
    description="Reusable browser profile for billing workflows",
    organization_id="your-org-id",
    proxy_cc=CountryCode.US,
    proxy_type=ProxyType.RESIDENTIAL,
    captcha_solver_active=False,
    sticky_ip=False,
    credentials=[],
    cookies=[],
)

created = client.create_agent_profile(request)
print(created.id)

Notes

• The high-level Python client focuses on the helper layer exported from asteroid_odyssey.
• Generated v2 request models use dynamic_data, not inputs.
• The top-level helpers do not currently expose profile pool operations. Use the profile pool endpoint pages under /api-reference/endpoints/agent-profile-pools/ when you need those workflows.

Related Resources

TypeScript SDK

See the TypeScript SDK guide

API

Browse the API landing page and common workflows