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

<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
```

## Quickstart

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

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

<Tabs>
  <Tab title="Executions">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Files">
    ```python theme={null}
    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")
    ```
  </Tab>

  <Tab title="Profiles">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

## Notes

* 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=...)`.

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