a2al (Python)

Python client for A2AL — decentralized agent networking. Spawns a local a2ald daemon as a sidecar and exposes a typed REST helper covering the full API surface: identity, publish, discover, resolve, fetch, and multiplexed persistent tunnels.

Full API: doc/api-reference.md

Installation

pip install a2al

Pre-built a2ald binaries are bundled inside platform wheels:

On unsupported platforms, install a2ald manually and set A2ALD_PATH to the executable path.

Quick Start

from a2al import Daemon, Client

with Daemon() as d:
    c = Client(d.api_base, token=d.api_token)

    # 1 — Check daemon health
    print(c.health())

    # 2 — Send an HTTP request to a remote agent (encrypted QUIC, no local port needed)
    result = c.fetch(
        remote_aid,
        method="GET",
        path="/.well-known/agent.json",
    )
    # result = {"status": 200, "headers": {...}, "body": "<base64>", "truncated": False}

    # 3 — Open a persistent tunnel (multiple concurrent TCP connections)
    tunnel = c.tunnel_open(remote_aid)
    local_addr = tunnel["listen"]   # e.g. "127.0.0.1:58320"
    tunnel_id  = tunnel["id"]       # e.g. "tun_abc123"

    # ... connect your application to local_addr ...

    c.tunnel_close(tunnel_id)

Client API

Daemon Context Manager

Daemon() starts a2ald as a subprocess and stops it when the with block exits.

from a2al import Daemon, Client

# Default: auto-locate a2ald binary, random API port, temp data dir
with Daemon() as d:
    c = Client(d.api_base, token=d.api_token)
    ...

# Custom binary path and extra daemon flags
with Daemon(
    a2ald_exe="/usr/local/bin/a2ald",
    extra_args=["--data-dir", "/var/lib/a2al", "--fallback-host", "1.2.3.4"],
) as d:
    c = Client(d.api_base, token=d.api_token)
    ...

Environment Variables

Requirements

• Python 3.10+
• No third-party dependencies (standard library only)

Links

• a2al.org — project site
• API reference
• tanglednet.org / tngld.net — Tangled Network
• GitHub

License

MPL-2.0