Metadata-Version: 2.4
Name: swarmd-sdk
Version: 0.3.2
Summary: Python SDK for SwarmD Agent Registry API
Author-email: SwarmD <support@swarmd.ai>
License: MIT
Project-URL: Homepage, https://swarmd.ai
Project-URL: Documentation, https://docs.swarmd.ai
Keywords: swarmd,agent,registry,api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fastapi>=0.110.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: freezegun>=1.4.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"

# swarmd-sdk

Python client for the [Swarmd](https://swarmd.ai) Agent Registry API, with
OAuth2 client-credentials authentication, thread-safe token caching and
automatic retries built in.

```bash
pip install swarmd-sdk
```

Requires Python 3.9+.

## Quick start

```python
from uuid import UUID
from swarmd_sdk import SwarmDClient

with SwarmDClient(
    agent_id="your-agent-id",
    client_secret="your-client-secret",
) as client:
    for agent in client.get_agent_subscriptions(UUID("123e4567-e89b-12d3-a456-426614174000")):
        print(f"{agent.name}: {agent.agent_card_url}")
```

`SwarmDClient.from_env()` builds the same client from the environment instead:

```env
SWARMD_AGENT_ID=your-agent-id
SWARMD_CLIENT_SECRET=your-client-secret

# Needed only to receive lifecycle callbacks on /admin/webhook
# (subscription / agent / tenant state changes). Issued alongside the
# client secret at registration. Without it your agent still works, but
# won't refresh itself on platform events.
SWARMD_WEBHOOK_SECRET=your-webhook-secret

# Optional
# SWARMD_BASE_URL=https://api.swarmd.ai
# SWARMD_TOKEN_URL=https://auth.swarmd.ai/realms/swarmd/protocol/openid-connect/token
# SWARMD_TIMEOUT=30
# SWARMD_MAX_RETRIES=3
```

## What's in the box

| | |
|---|---|
| `SwarmDClient`, `SwarmDConfig` | registry client and its configuration |
| `SwarmDRuntime`, `create_admin_app` | agent runtime and its admin/webhook app |
| `AgentDirectory` | discovery over the agents you are subscribed to |
| `McpClient` and friends | MCP servers vended through the platform |
| `OAuth2TokenManager` | token acquisition and refresh, used by the client |
| `CorrelationIdMiddleware`, `correlation_id_var` | request correlation across agents |
| `verify_webhook` | signature verification for lifecycle callbacks |

Errors are typed: `AuthenticationError`, `TokenRefreshError` and `APIError`
(which carries `status_code` and `response_body`), all deriving from
`SwarmDSDKError`.

The package ships type information (`py.typed`), so it type-checks under mypy
and pyright without stubs.

## Framework integrations

- [`swarmd-google-adk`](https://pypi.org/project/swarmd-google-adk/) — Google Agent Development Kit
- [`swarmd-langchain`](https://pypi.org/project/swarmd-langchain/) — LangChain

## Documentation and support

Full documentation is at [docs.swarmd.ai](https://docs.swarmd.ai). For help,
email <support@swarmd.ai>.

MIT licensed.
