anycast-agent

Python SDK for Anycast Agents P2P connectivity.

Connect agents to the Anycast network for peer-to-peer communication with relay fallback, powered by the global Anycast edge infrastructure.

Installation

pip install anycast-agent

Quick Start

import asyncio
from anycast_agent import AnycastAgent

async def main():
    agent = AnycastAgent(
        rendezvous_url="wss://agents.anycast.com/rendezvous",
        token="agt_your_token_here",
    )

    @agent.on_connect
    async def on_connect(info):
        print(f"Connected as {info.agent_id}")

    @agent.on_peer
    async def on_peer(agent_id, status):
        print(f"Peer {agent_id} is {status}")

    await agent.connect()
    await agent.run_forever()

asyncio.run(main())

API Reference

AnycastAgent(rendezvous_url, token, **kwargs)

Create a new agent instance.

Properties

Methods

await agent.connect() -> AgentInfo

Connect to the rendezvous server. Returns AgentInfo with agent_id, tenant_id, name.

await agent.disconnect()

Disconnect from the server.

await agent.run_forever()

Block until disconnected. Handles reconnection automatically.

agent.request_connection(target_agent_id) -> str

Request a P2P connection to another agent. Returns a session ID.

await agent.send_signal(session_id, target_agent_id, signal)

Send a WebRTC signal (offer/answer/ICE candidate).

await agent.disconnect_session(session_id)

Close a specific session.

Events

Register handlers with decorators or .on():

# Decorator style
@agent.on_connect
async def handler(info): ...

# Method style
agent.on("connect", handler)

Handlers can be sync or async — async handlers are awaited automatically.

Exceptions

from anycast_agent import (
    AnycastError,          # Base error (has .code, .fatal)
    AnycastConnectionError, # WebSocket connection failed
    AnycastAuthError,       # Token invalid (fatal)
    AnycastTimeoutError,    # Connection/registration timeout
)

ConnectionState

from anycast_agent import ConnectionState

ConnectionState.DISCONNECTED
ConnectionState.CONNECTING
ConnectionState.CONNECTED
ConnectionState.RECONNECTING

Auto-Reconnection

By default, the agent reconnects with exponential backoff (3s, 6s, 12s, ..., max 30s). Disable with reconnect=False.

License

MIT