> ## 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.

# 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.

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

## Install

```bash theme={null}
pip install --upgrade asteroid-odyssey
```

Or with uv:

```bash theme={null}
uv pip install asteroid-odyssey
```

## Client Configuration

```python theme={null}
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](/integrate/call-a-workflow). This page covers what is specific to the SDK.

## API Classes

Import these from `asteroid_odyssey.api.*`:

| Class | Import | Purpose |
| - | - | - |
| `WorkflowsApi` | `asteroid_odyssey.api.workflows_api` | Create, list and execute 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 login profiles |
| `VaultApi` | `asteroid_odyssey.api.vault_api` | Manage secrets, templates, and secret requests |
| `AgentProfilePoolsApi` | `asteroid_odyssey.api.agent_profile_pools_api` | Manage profile groups |
| `WorkflowVersionsApi` | `asteroid_odyssey.api.workflow_versions_api` | Create, validate, publish and execute workflow versions |

Models live under `asteroid_odyssey.models.*`.

## Common Patterns

<CardGroup cols={2}>
  <Card title="Execute and poll" icon="play" href="/integrate/call-a-workflow" horizontal>
    The full run loop, including the statuses that wait for a person
  </Card>

  <Card title="Every execute field" icon="sliders" href="/integrate/call-a-workflow" horizontal>
    Inputs, profiles, files, metadata, and version pinning
  </Card>

  <Card title="Files" icon="file" href="/concepts/filesystem" horizontal>
    Stage files before an execution and download what the workflow produced
  </Card>

  <Card title="Profiles" icon="id-card" href="/concepts/profiles" horizontal>
    Secrets, Email Inbox, and profile groups
  </Card>
</CardGroup>

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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="code" href="/sdks/typescript">
    See the TypeScript SDK guide
  </Card>

  <Card title="API" icon="book" href="/api-reference/overview">
    Browse the API landing page and common workflows
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.