Metadata-Version: 2.4
Name: opal-agent-sdk
Version: 0.1.1
Summary: Async Python SDK for invoking Opal agents over PAT-authenticated REST and socket.io.
Author-email: Optimizely <opal-team@optimizely.com>
License: MIT
Project-URL: Homepage, https://github.com/optimizely/opal-app
Project-URL: Documentation, https://github.com/optimizely/opal-app/blob/main/docs/tech-spec/agent-framework/agent-sdk/python-sdk.md
Project-URL: Source, https://github.com/optimizely/opal-app/tree/main/sdks/agent-sdk/python
Keywords: opal,agent,sdk,ai,llm,async
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: python-socketio[asyncio_client]>=5.10
Requires-Dist: pydantic>=2.6
Provides-Extra: cli
Requires-Dist: typer>=0.12; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: typer>=0.12; extra == "dev"
Dynamic: license-file

# opal-agent-sdk (Python)

Async Python SDK for invoking Opal agents from external programs over a PAT.

**Tech spec:** [`docs/tech-spec/agent-framework/agent-sdk/python-sdk.md`](../../../docs/tech-spec/agent-framework/agent-sdk/python-sdk.md) in this repo.

## Install

```bash
pip install opal-agent-sdk            # core
pip install "opal-agent-sdk[cli]"     # adds the `opal` CLI
```

Python 3.10+. Async-only.

## Quickstart

```python
import asyncio
import os
from opal_agent_sdk import OpalClient, PATAuth

async def main() -> None:
    async with OpalClient(auth=PATAuth(os.environ["OPAL_PAT"])) as client:
        result = await client.agents.specialized.run(
            agent_id="customer-service-bot",
            parameters={"query": "Where is order #1234?"},
        )
        print(result.output_text)

asyncio.run(main())
```

See [`examples/`](./examples) for more (one runnable snippet per spec Appendix A entry).

## Status

v0.1 — under active development on branch `opal_app_agent_sdk`. Wire contract pinned to Hypatia's `SdkEventEnvelope` + space-element responses via fixtures in [`tests/contract/`](./tests/contract).

## Development

```bash
make install        # uv pip install -e ".[dev,cli]"
make test           # pytest
make lint           # ruff check
make format         # ruff format
make typecheck      # mypy --strict
make check          # all of the above
```
