Python SDK

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

Use the asteroid-odyssey Python SDK to execute workflows, 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

Client Configuration

import os

from asteroid_odyssey import ApiClient, Configuration

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

with ApiClient(config) as api_client:
    ...

The end-to-end example — execute, poll to a terminal status, read the result — lives on Deploy a workflow. This page covers what is specific to the SDK.

API Classes

Import these from asteroid_odyssey.api.*:

Class	Import	Purpose
AgentsApi	asteroid_odyssey.api.agents_api	Execute workflows, list workflows
ExecutionApi	asteroid_odyssey.api.execution_api	Get, list, poll, message executions
FilesApi	asteroid_odyssey.api.files_api	Upload/download execution files; read, patch and publish a workflow’s file tree
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

Execute and poll

The full run loop, including the statuses that wait for a person

Every execute field

Inputs, profiles, files, metadata, and version pinning

Files

Stage files before an execution and download what the workflow produced

Profiles

Credentials, cookies, proxies, and pools

Send a message to a running workflow, and read its timeline:

activities = execution_api.execution_activities_get(
    execution_id=execution_id,
    limit=20,
    order="desc",
)
for activity in activities:
    print(activity.payload)

execution_api.execution_user_messages_add(
    execution_id=execution_id,
    agents_execution_user_messages_add_text_body={"message": "Please use the latest file only."},
)

Notes

• Model attributes are snake_case even though the JSON is camelCase. The API field executionResult reads as execution.execution_result in Python.
• 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