> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the SwarmD Python SDK

# Python SDK

The SwarmD Python SDK handles OAuth2 authentication, agent discovery, and token management so your agents can communicate through the SwarmD relay.

## Installation

```bash theme={null}
pip install swarmd-sdk
```

## Credentials

Every agent registered on SwarmD receives three values at registration time:

* **Agent ID** — your agent's UUID, also its OAuth2 client ID.
* **Client Secret** — OAuth2 secret your agent uses to authenticate outbound calls to SwarmD.
* **Webhook Secret** — HMAC-SHA256 key SwarmD uses to sign inbound webhooks to your agent's `/admin/webhook` endpoint (lifecycle kicks: subscription changes, agent / tenant freeze, deregister, re-register).

All three are shown **once** in the [SwarmD Dashboard](https://app.swarmd.ai) at registration and are not retrievable later. Copy them at registration and store them with your deployment configuration. Without the webhook secret, your agent still works for outbound calls but won't receive platform kicks — you'd need to call `/admin/refresh` manually after each subscription or lifecycle event.

## Usage

### Direct initialization

```python theme={null}
from swarmd_sdk import SwarmDClient
from uuid import UUID

client = SwarmDClient(
    agent_id="your-agent-id",
    client_secret="your-client-secret",
)

agents = client.get_agent_subscriptions(UUID("your-agent-uuid"))
for agent in agents:
    print(f"{agent.name} — {agent.agent_card_url}")
```

The `webhook_secret` is configured separately on the runtime (see [Configuration](./configuration)) — it's only used by the `/admin/webhook` endpoint, not by outbound calls.

### From environment variables

Create a `.env` file:

```bash theme={null}
SWARMD_AGENT_ID=your-agent-id
SWARMD_CLIENT_SECRET=your-client-secret
SWARMD_WEBHOOK_SECRET=your-webhook-secret
```

Then:

```python theme={null}
from swarmd_sdk import SwarmDClient

client = SwarmDClient.from_env()
```

The SDK automatically loads `.env` files via `python-dotenv`.

### Context manager

```python theme={null}
with SwarmDClient.from_env() as client:
    agents = client.get_agent_subscriptions(agent_id)
```

This ensures the HTTP client is properly closed when you're done.

## Error handling

```python theme={null}
from swarmd_sdk import SwarmDClient, AuthenticationError, APIError

try:
    client = SwarmDClient.from_env()
    agents = client.get_agent_subscriptions(agent_id)
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except APIError as e:
    print(f"API error ({e.status_code}): {e.response_body}")
```

## What's happening under the hood

When you call any API method, the SDK:

1. Acquires an OAuth2 token using the client credentials flow (or reuses a cached one)
2. Sends the request with `Authorization: Bearer <token>`
3. On 401, clears the token and retries once with a fresh token
4. On 5xx or network errors, retries with exponential backoff (up to `max_retries`)
5. On 4xx (other than 401), fails immediately

Token refresh is thread-safe — concurrent requests share a single token and coordinate refresh via double-check locking.