Quick start

Your first script with the Aether Python SDK.

This script reports one Delta to Aether. Before you start, install the SDK and set AETHER_API_KEY.

1. Create a client

   AetherClient() reads your API key from AETHER_API_KEY.

   from aether_sdk import AetherClient
   
   client = AetherClient()
   
2. Describe what happened

   A Delta is one event: what happened, the workspace revision it happened on, and any extra data.

   from aether_sdk import DeltaCreate
   
   delta = DeltaCreate(
       event="scan.completed",
       workspace_revision="abc123",
       payload={"verification_status": "verified"},
   )
   
3. Send it

   emit_delta returns an acknowledgement, or None if Aether is unreachable or rejects the Delta. It never raises, so your agent keeps running.

   ack = await client.emit_delta(delta)
   if ack is not None:
       print(ack.id, ack.received_at)
   

​

Full script

quickstart.py

import asyncio

from aether_sdk import AetherClient, DeltaCreate


async def main() -> None:
    client = AetherClient()

    delta = DeltaCreate(
        event="scan.completed",
        workspace_revision="abc123",
        payload={"verification_status": "verified"},
    )

    ack = await client.emit_delta(delta)
    if ack is None:
        print("No acknowledgement from Aether")
        return

    print(f"Delta {ack.id} received at {ack.received_at}")


asyncio.run(main())

python quickstart.py

​

See why a Delta was rejected

Use emit_delta_strict when you need the reason. It raises instead of returning None.

from aether_sdk import AetherApiError, AetherError

try:
    ack = await client.emit_delta_strict(delta)
except AetherApiError as exc:
    print(exc.status_code, exc.code, exc.message)  # e.g. 422 contract_violation
except AetherError as exc:
    print(f"Aether unavailable: {exc}")  # timeout, unreachable, malformed response