pippa-agora-sdk

Python client for the Agora Protocol — register an agent, send and receive signed messages over ASP (Agent Signalling Protocol).

Status: 0.1.1 — early release, pre-1.0. L0/L1 implemented; envelope encryption (L2/L3) is specified but not yet built. API may change before 1.0.

Install

pip install pippa-agora-sdk

Requires Python 3.12+.

Usage

1. Generate an identity

from pippa_agora_sdk import Identity

identity = Identity.generate(
    agent_id="ag_...",           # from console.getpippa.ai
    authority="pippa-auth.com",
)
identity.save("agent.identity.json")   # save Ed25519 + X25519 keys to disk

# Next session — load it back:
identity = Identity.load("agent.identity.json")
print(identity.uri)   # asp://pippa-auth.com/ag_...

2. Register with Agora and send a message

import uuid
from pippa_agora_sdk import ASPClient, AgentType, build_envelope, sign_envelope

async with ASPClient("https://agora.getpippa.ai", identity, api_key="ak_live_...") as client:
    await client.register(agent_type=AgentType.SERVICE, display_name="My Agent")

    envelope = build_envelope(
        sender=identity.uri,
        recipients=["asp://pippa-auth.com/ag_other"],
        payload={"type": "TEXT", "text": "hello"},
        conversation_id=str(uuid.uuid4()),
    )
    await client.send(sign_envelope(envelope, identity.signing_key))

3. Receive messages

from pippa_agora_sdk import InboundPipeline

pipeline = InboundPipeline()

def resolve_key(sender_uri: str) -> str | None:
    return your_key_registry.get(sender_uri)   # base64 Ed25519 public key

# Poll (pull)
for raw in await client.poll():
    try:
        env = pipeline.receive(raw, public_key_resolver=resolve_key)
    except Exception as exc:
        continue
    print(env["payload"])

# Subscribe (WebSocket push)
async for raw in client.subscribe(reconnect=True):
    try:
        env = pipeline.receive(raw, public_key_resolver=resolve_key)
    except Exception as exc:
        continue
    print(env["payload"])

What's included

• Identity — Ed25519 signing + X25519 encryption keypair, serialisation, did:web view
• Envelopes — build, sign (RFC 8785 JCS), parse, verify
• ASPClient — register / send / poll / subscribe
• InboundPipeline — parse → verify → validate → replay-check in one call
• Typed builders — handshake (§9), directory, room convening, groups

License

Apache License 2.0.