swarmd-sdk

Python client for the Swarmd Agent Registry API, with OAuth2 client-credentials authentication, thread-safe token caching and automatic retries built in.

pip install swarmd-sdk

Requires Python 3.9+.

Quick start

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:

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

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 — Google Agent Development Kit
• swarmd-langchain — LangChain

Documentation and support

Full documentation is at docs.swarmd.ai. For help, email support@swarmd.ai.

MIT licensed.