Tutorial: Build an Agent

from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives import serialization
import json

# Generate a key pair
private_key = ec.generate_private_key(ec.SECP256R1())

# Save the private key (keep this secret!)
pem = private_key.private_bytes(
    serialization.Encoding.PEM,
    serialization.PrivateFormat.PKCS8,
    serialization.NoEncryption(),
)
with open("agent-private.pem", "wb") as f:
    f.write(pem)

# The PEM string is what you pass to the SDK
pem_str = pem.decode()
print("Private key saved to agent-private.pem")

# Generate private key
openssl ecparam -genkey -name prime256v1 -noout -out agent-private.pem

# Extract public key (for your identity document)
openssl ec -in agent-private.pem -pubout -out agent-public.pem

pip install ath-sdk cryptography

from ath import ATHGatewayClient

# Load your private key
with open("agent-private.pem") as f:
    pem = f.read()

with ATHGatewayClient(
    url="https://your-gateway.com",
    agent_id="https://your-agent.com/.well-known/agent.json",
    private_key=pem,
    key_id="default",
) as client:

    # 1. DISCOVER
    discovery = client.discover()
    for p in discovery.supported_providers:
        print(f"  {p.provider_id}: {p.available_scopes}")

    # 2. REGISTER — SDK signs attestation JWT automatically
    reg = client.register(
        developer={"name": "My Company", "id": "my-company"},
        providers=[{"provider_id": "my-provider", "scopes": ["read", "write"]}],
        purpose="AI shopping assistant",
    )
    print(f"Agent status: {reg.agent_status}")

    # 3. AUTHORIZE — get URL for user consent
    auth = client.authorize("my-provider", ["read", "write"])
    print(f"Send user to: {auth.authorization_url}")
    print(f"Session ID: {auth.ath_session_id}")

    # ⏳ WAIT for user to approve in browser (10 min timeout)

    # 4. TOKEN
    token = client.exchange_token("auth-code", auth.ath_session_id)
    print(f"Granted scopes: {token.effective_scopes}")

    # 5. USE THE API
    products = client.proxy("my-provider", "GET", "/products")
    print(f"Products: {products}")

    client.proxy("my-provider", "POST", "/cart/add", {
        "productId": "prod-123", "quantity": 2,
    })

    # 6. REVOKE
    client.revoke()

    # Save credentials for next session (avoids re-registration)
    client.save_credentials("my-agent-creds.json")

npm install -g athx

# Configure (one-time)
athx config init
athx config set-gateway my-gw https://your-gateway.com
athx config set agent-id https://your-agent.com/.well-known/agent.json
athx config set key-path ./agent-private.pem  # your ES256 private key

GATEWAY="my-gw"

# 1. DISCOVER
athx discover -g $GATEWAY

# 2. REGISTER
athx register -g $GATEWAY --provider my-provider --scopes "read,write"

# 3. AUTHORIZE — prints a URL for the user to visit
athx authorize -g $GATEWAY --provider my-provider --scopes "read,write"
# Output:
#   Session: ath_sess_abc123
#   Please visit: https://...
# → Open that URL in your browser, log in, click Approve

# 4. TOKEN — after the user approved
athx token -g $GATEWAY --code AUTH_CODE --session ath_sess_abc123

# 5. USE THE API
athx proxy my-provider GET /products -g $GATEWAY
athx proxy my-provider POST /cart/add -g $GATEWAY \
  --body '{"productId":"prod-123","quantity":2}'

# 6. REVOKE
athx revoke -g $GATEWAY --provider my-provider