Documentation Index
Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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)
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 |
asteroid_odyssey.models.*.
Common Patterns
Executions
Files
Profiles
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)
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
files_api.execution_context_files_upload(
execution_id=execution_id,
files=[open("./invoice.pdf", "rb")],
)
files = files_api.execution_context_files_get(execution_id=execution_id)
for file in files:
print(f"{file.file_name}: {file.file_size} bytes")
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_country_code="us",
proxy_type="residential",
captcha_solver_active=False,
sticky_ip=False,
credentials=[],
cookies=[],
),
)
print(created.id)
- Use
inputs for execution variables — dynamic_data is deprecated.
execution_activities_get returns a list of AgentsExecutionActivity objects directly.agent_profiles_list requires organization_id.- The SDK’s default base URL is
https://odyssey.asteroid.ai/agents/v2. Override via Configuration(host=...).
TypeScript SDK
See the TypeScript SDK guide
API
Browse the API landing page and common workflows
