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.

The SDK provides generated API classes. Instantiate Configuration with your API key, create an ApiClient, then use the API classes directly.

Install

pip install --upgrade asteroid-odyssey

Or with uv:

uv pip install asteroid-odyssey

Quickstart

import os
import time
from asteroid_odyssey import Configuration, ApiClient
from asteroid_odyssey.api.agents_api import AgentsApi
from asteroid_odyssey.api.execution_api import ExecutionApi
from asteroid_odyssey.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)
    exec_api = ExecutionApi(api_client)

    response = agents_api.agent_execute_post(
        agent_id="your-agent-id",
        agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
            inputs={"customerName": "Jane Doe"},
        ),
    )
    execution_id = response.execution_id

    # Poll until complete
    while True:
        time.sleep(3)
        execution = exec_api.execution_get(execution_id=execution_id)
        if execution.status not in ("running", "starting"):
            break

    print(execution.status, execution.inputs)

Run it with:

python run_agent.py

API Classes

Import these from asteroid_odyssey.api.*:

Class	Import	Purpose
AgentsApi	asteroid_odyssey.api.agents_api	Execute agents, list agents
ExecutionApi	asteroid_odyssey.api.execution_api	Get, list, poll, message executions
FilesApi	asteroid_odyssey.api.files_api	Upload/download execution files
AgentProfilesApi	asteroid_odyssey.api.agent_profiles_api	Manage agent profiles
AgentProfilePoolsApi	asteroid_odyssey.api.agent_profile_pools_api	Manage profile pools
WorkflowsApi	asteroid_odyssey.api.workflows_api	Execute specific workflow versions

Models live under asteroid_odyssey.models.*.

Common Patterns

Executions

import os
import time
from asteroid_odyssey import Configuration, ApiClient
from asteroid_odyssey.api.agents_api import AgentsApi
from asteroid_odyssey.api.execution_api import ExecutionApi
from asteroid_odyssey.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)
    exec_api = ExecutionApi(api_client)

    response = agents_api.agent_execute_post(
        agent_id="your-agent-id",
        agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
            inputs={"task": "Summarize the attached invoice"},
        ),
    )
    execution_id = response.execution_id

    activities = exec_api.execution_activities_get(
        execution_id=execution_id,
        limit=20,
        order="desc",
    )
    exec_api.execution_user_messages_add(
        execution_id=execution_id,
        agents_execution_user_messages_add_text_body={"message": "Please use the latest file only."},
    )

    status = exec_api.execution_get(execution_id=execution_id)
    print(status.status)
    for activity in activities:
        print(activity.payload)

Files

import os
from asteroid_odyssey import Configuration, ApiClient
from asteroid_odyssey.api.agents_api import AgentsApi
from asteroid_odyssey.api.files_api import FilesApi
from asteroid_odyssey.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)
    files_api = FilesApi(api_client)

    response = agents_api.agent_execute_post(
        agent_id="your-agent-id",
        agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
            inputs={"task": "Read the uploaded invoice and summarize it"},
        ),
    )
    execution_id = response.execution_id

    with open("./invoice.pdf", "rb") as invoice:
        files_api.execution_context_files_upload(
            execution_id=execution_id,
            files=[invoice],
        )

    files = files_api.execution_context_files_get(execution_id=execution_id)
    for file in files:
        print(f"{file.file_name}: {file.file_size} bytes")

Profiles

import os
from asteroid_odyssey import Configuration, ApiClient
from asteroid_odyssey.api.agent_profiles_api import AgentProfilesApi
from asteroid_odyssey.models.agents_profile_create_agent_profile_request import AgentsProfileCreateAgentProfileRequest

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

with ApiClient(config) as api_client:
    profiles_api = AgentProfilesApi(api_client)

    profiles = profiles_api.agent_profiles_list(organization_id="your-org-id")
    print([profile.name for profile in profiles.items])

    created = profiles_api.agent_profiles_create(
        agents_profile_create_agent_profile_request=AgentsProfileCreateAgentProfileRequest(
            name="Shared Billing Profile",
            description="Reusable browser profile for billing workflows",
            organization_id="your-org-id",
            proxy_mode="managed",
            proxy_cc="us",
            captcha_solver_active=False,
            sticky_ip=False,
            credentials=[],
            cookies=[],
        ),
    )
    print(created.id)

Notes

• Use inputs for execution variables — dynamic_data is deprecated.
• execution_activities_get returns a list of AgentsExecutionActivity objects directly.
• agent_profiles_list accepts an optional organization_id filter.
• The SDK’s default base URL is https://odyssey.asteroid.ai/agents/v2. Override via Configuration(host=...).

Related Resources

TypeScript SDK

See the TypeScript SDK guide

API

Browse the API landing page and common workflows