# Asteroid Odyssey
The official Python SDK for interacting with the Asteroid Agents API.
## Installation
```bash
pip install asteroid-odyssey
```
## Usage
Please head to our documentation at https://docs.asteroid.ai/sdk/python
## License
The Asteroid Odyssey SDK is available under the MIT License.
### Tests
Execute `pytest` to run the tests.
## Getting Started
The SDK provides a high-level `AsteroidClient` class that makes it easy to interact with the Asteroid Agents API:
```python
from asteroid_odyssey import AsteroidClient
# Create a client with your API key
client = AsteroidClient('your-api-key')
# Execute an agent
execution_id = client.execute_agent('my-agent-id', {'input': 'some dynamic value'})
# Wait for the execution to complete and get the result
result = client.wait_for_execution_result(execution_id)
print(result)
# Or check status manually
status = client.get_execution_status(execution_id)
print(f"Status: {status.status}")
# Upload files to an execution
hello_content = "Hello World!".encode()
response = client.upload_execution_files(execution_id, [hello_content])
print(f"Uploaded files: {response.file_ids}")
# Get browser session recording (for completed executions)
recording_url = client.get_browser_session_recording(execution_id)
print(f"Recording available at: {recording_url}")
```
### Context Manager Usage
The client can also be used as a context manager:
```python
from asteroid_odyssey import AsteroidClient
with AsteroidClient('your-api-key') as client:
execution_id = client.execute_agent('my-agent-id', {'input': 'test'})
result = client.wait_for_execution_result(execution_id)
print(result)
```
### Convenience Functions
The SDK also provides convenience functions:
```python
from asteroid_odyssey import create_client, execute_agent, wait_for_execution_result
client = create_client('your-api-key')
execution_id = execute_agent(client, 'my-agent-id', {'input': 'test'})
result = wait_for_execution_result(client, execution_id)
```
## API Reference
### AsteroidClient
The main client class provides the following methods:
- `execute_agent(agent_id, agent_profile_id (optional), execution_data(optional))` - Execute an agent and return execution ID
- `get_execution_status(execution_id)` - Get current execution status
- `get_execution_result(execution_id)` - Get final execution result
- `wait_for_execution_result(execution_id, interval=1.0, timeout=3600.0)` - Wait for completion
- `upload_execution_files(execution_id, files, default_filename="file.txt")` - Upload files
- `get_browser_session_recording(execution_id)` - Get browser recording URL
### Low-Level API Access
If you need direct access to the generated OpenAPI client, you can still use it:
```python
import openapi_client
from openapi_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to https://odyssey.asteroid.ai/api/v1
configuration = openapi_client.Configuration(
host = "https://odyssey.asteroid.ai/api/v1"
)
# Enter a context with an instance of the API client
with openapi_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = openapi_client.APIApi(api_client)
try:
# Get the OpenAPI schema
api_instance.get_open_api()
except ApiException as e:
print("Exception when calling APIApi->get_open_api: %s\n" % e)
```
| Class | Method | Return Type Representation | Description |
| ---------------- | ------------------------------- | -------------------------- | -------------------------------------------------------- |
| `AsteroidClient` | `execute_agent` | `str` (execution ID) | Executes an agent and returns its execution ID. |
| `AsteroidClient` | `get_execution_status` | `dict-like object` | Gets the current status of an execution. |
| `AsteroidClient` | `get_execution_result` | `dict` (execution result) | Retrieves the result data of a completed execution. |
| `AsteroidClient` | `get_browser_session_recording` | `str` (URL) | Returns the session recording URL of an execution. |
| `AsteroidClient` | `upload_execution_files` | `dict-like object` | Uploads files to an execution and returns file metadata. |
<a id="documentation-for-authorization"></a>
## Documentation For Authorization
To generate an API key, go to our [platform](https://platform.asteroid.ai) and in your profile section, click on API Keys. You can now create and manage your API keys.
Authentication schemes defined for the API:
<a id="ApiKeyAuth"></a>
### ApiKeyAuth
- **Type**: API key
- **API key parameter name**: X-Asteroid-Agents-Api-Key
- **Location**: HTTP header
## Development quickâstart
```bash
# clone
git clone https://github.com/<org>/asteroid-odyssey-py.git
cd asteroid-odyssey-py
# create / activate a virtualenv (example using venv)
python -m venv .venv
source .venv/bin/activate
# install project in *editable* mode + dev tools
pip install -U pip
pip install -e .[dev] # or: pip install -e .
# run the generated SDK tests
pytest
```
## Regenerating the SDK
To update the SDK, regenerate the code by running
```bash
./regen-sdk.sh
```
If the OpenAPI spec changes:
```bash
./regen-sdk.sh # regenerate client & docs
pip install -e . # refresh editable install (safe to rerun)
pytest # all tests should still pass
```
After generation, ensure `pyproject.toml` is configured correctly and that files are modified correctly. Check for new files and if they are needed.
Raw data
{
"_id": null,
"home_page": null,
"name": "asteroid-odyssey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "OpenAPI, OpenAPI-Generator, Asteroid Agents API, browser automation, AI agents",
"author": null,
"author_email": "David Mlcoch <founders@asteroid.com>",
"download_url": "https://files.pythonhosted.org/packages/f3/93/ec1e6edc476a11d98c70087f27b429e0e7146404d4e272ce9ffcb6d66e80/asteroid_odyssey-1.0.2.tar.gz",
"platform": null,
"description": "# Asteroid Odyssey\n\nThe official Python SDK for interacting with the Asteroid Agents API.\n\n## Installation\n\n```bash\npip install asteroid-odyssey\n```\n\n## Usage\n\nPlease head to our documentation at https://docs.asteroid.ai/sdk/python\n\n## License\n\nThe Asteroid Odyssey SDK is available under the MIT License.\n\n### Tests\n\nExecute `pytest` to run the tests.\n\n## Getting Started\n\nThe SDK provides a high-level `AsteroidClient` class that makes it easy to interact with the Asteroid Agents API:\n\n```python\nfrom asteroid_odyssey import AsteroidClient\n\n# Create a client with your API key\nclient = AsteroidClient('your-api-key')\n\n# Execute an agent\nexecution_id = client.execute_agent('my-agent-id', {'input': 'some dynamic value'})\n\n# Wait for the execution to complete and get the result\nresult = client.wait_for_execution_result(execution_id)\nprint(result)\n\n# Or check status manually\nstatus = client.get_execution_status(execution_id)\nprint(f\"Status: {status.status}\")\n\n# Upload files to an execution\nhello_content = \"Hello World!\".encode()\nresponse = client.upload_execution_files(execution_id, [hello_content])\nprint(f\"Uploaded files: {response.file_ids}\")\n\n# Get browser session recording (for completed executions)\nrecording_url = client.get_browser_session_recording(execution_id)\nprint(f\"Recording available at: {recording_url}\")\n```\n\n### Context Manager Usage\n\nThe client can also be used as a context manager:\n\n```python\nfrom asteroid_odyssey import AsteroidClient\n\nwith AsteroidClient('your-api-key') as client:\n execution_id = client.execute_agent('my-agent-id', {'input': 'test'})\n result = client.wait_for_execution_result(execution_id)\n print(result)\n```\n\n### Convenience Functions\n\nThe SDK also provides convenience functions:\n\n```python\nfrom asteroid_odyssey import create_client, execute_agent, wait_for_execution_result\n\nclient = create_client('your-api-key')\nexecution_id = execute_agent(client, 'my-agent-id', {'input': 'test'})\nresult = wait_for_execution_result(client, execution_id)\n```\n\n## API Reference\n\n### AsteroidClient\n\nThe main client class provides the following methods:\n\n- `execute_agent(agent_id, agent_profile_id (optional), execution_data(optional))` - Execute an agent and return execution ID\n- `get_execution_status(execution_id)` - Get current execution status\n- `get_execution_result(execution_id)` - Get final execution result\n- `wait_for_execution_result(execution_id, interval=1.0, timeout=3600.0)` - Wait for completion\n- `upload_execution_files(execution_id, files, default_filename=\"file.txt\")` - Upload files\n- `get_browser_session_recording(execution_id)` - Get browser recording URL\n\n### Low-Level API Access\n\nIf you need direct access to the generated OpenAPI client, you can still use it:\n\n```python\nimport openapi_client\nfrom openapi_client.rest import ApiException\nfrom pprint import pprint\n\n# Defining the host is optional and defaults to https://odyssey.asteroid.ai/api/v1\nconfiguration = openapi_client.Configuration(\n host = \"https://odyssey.asteroid.ai/api/v1\"\n)\n\n# Enter a context with an instance of the API client\nwith openapi_client.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = openapi_client.APIApi(api_client)\n\n try:\n # Get the OpenAPI schema\n api_instance.get_open_api()\n except ApiException as e:\n print(\"Exception when calling APIApi->get_open_api: %s\\n\" % e)\n```\n\n| Class | Method | Return Type Representation | Description |\n| ---------------- | ------------------------------- | -------------------------- | -------------------------------------------------------- |\n| `AsteroidClient` | `execute_agent` | `str` (execution ID) | Executes an agent and returns its execution ID. |\n| `AsteroidClient` | `get_execution_status` | `dict-like object` | Gets the current status of an execution. |\n| `AsteroidClient` | `get_execution_result` | `dict` (execution result) | Retrieves the result data of a completed execution. |\n| `AsteroidClient` | `get_browser_session_recording` | `str` (URL) | Returns the session recording URL of an execution. |\n| `AsteroidClient` | `upload_execution_files` | `dict-like object` | Uploads files to an execution and returns file metadata. |\n\n\n\n\n<a id=\"documentation-for-authorization\"></a>\n## Documentation For Authorization\n\nTo generate an API key, go to our [platform](https://platform.asteroid.ai) and in your profile section, click on API Keys. You can now create and manage your API keys.\n\nAuthentication schemes defined for the API:\n<a id=\"ApiKeyAuth\"></a>\n### ApiKeyAuth\n\n- **Type**: API key\n- **API key parameter name**: X-Asteroid-Agents-Api-Key\n- **Location**: HTTP header\n\n\n## Development quick\u2011start\n```bash \n# clone\ngit clone https://github.com/<org>/asteroid-odyssey-py.git\ncd asteroid-odyssey-py\n\n# create / activate a virtualenv (example using venv)\npython -m venv .venv\nsource .venv/bin/activate\n\n# install project in *editable* mode + dev tools\npip install -U pip\npip install -e .[dev] # or: pip install -e .\n\n# run the generated SDK tests\npytest\n```\n\n## Regenerating the SDK\n\nTo update the SDK, regenerate the code by running\n\n```bash\n ./regen-sdk.sh\n ```\n\n If the OpenAPI spec changes:\n ```bash \n./regen-sdk.sh # regenerate client & docs\npip install -e . # refresh editable install (safe to rerun)\npytest # all tests should still pass\n```\n\nAfter generation, ensure `pyproject.toml` is configured correctly and that files are modified correctly. Check for new files and if they are needed.\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python SDK for browser automation using Asteroid platform.",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://docs.asteroid.ai",
"Homepage": "https://asteroid.ai",
"Repository": "https://github.com/asteroid/asteroid-odyssey-py"
},
"split_keywords": [
"openapi",
" openapi-generator",
" asteroid agents api",
" browser automation",
" ai agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "26b3b293f9b76e2c0798a09debd70c4a02505d511d3e2e715fde3fc1538aaa02",
"md5": "75c76f0ec35c3ccd611fe5fdfef37139",
"sha256": "dcb52bebe810c58a26e530742a5f7b49979d64327d10b5ba3d4a723d63f5b66b"
},
"downloads": -1,
"filename": "asteroid_odyssey-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75c76f0ec35c3ccd611fe5fdfef37139",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 47349,
"upload_time": "2025-07-21T12:42:47",
"upload_time_iso_8601": "2025-07-21T12:42:47.008407Z",
"url": "https://files.pythonhosted.org/packages/26/b3/b293f9b76e2c0798a09debd70c4a02505d511d3e2e715fde3fc1538aaa02/asteroid_odyssey-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f393ec1e6edc476a11d98c70087f27b429e0e7146404d4e272ce9ffcb6d66e80",
"md5": "a8b72dd51c0535472fd2a4ceeff525ba",
"sha256": "d0d67a361d2a7c8b7d78e052ddf82db43de3f16ef4718fc75c670fba5cd66dd7"
},
"downloads": -1,
"filename": "asteroid_odyssey-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a8b72dd51c0535472fd2a4ceeff525ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32969,
"upload_time": "2025-07-21T12:42:48",
"upload_time_iso_8601": "2025-07-21T12:42:48.589243Z",
"url": "https://files.pythonhosted.org/packages/f3/93/ec1e6edc476a11d98c70087f27b429e0e7146404d4e272ce9ffcb6d66e80/asteroid_odyssey-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 12:42:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asteroid",
"github_project": "asteroid-odyssey-py",
"github_not_found": true,
"lcname": "asteroid-odyssey"
}
JSON
