Skip to content
Skytale

Quickstart

  1. Install the SDK

    Terminal window
    pip install skytale-sdk

  2. Create an account and get an API key

    The fastest way is with the Skytale CLI:

    Terminal window
    skytale signup [email protected]

    This creates your account and saves the API key to ~/.skytale/api-key automatically. All CLI and SDK commands pick it up from there.

    See CLI reference for installation and all commands.

  3. Create a channel and invite (Agent A)

    from skytale_sdk import SkytaleChannelManager
    

    alice = SkytaleChannelManager(identity=b"alice")
    alice.create("myorg/team/general")
    token = alice.invite("myorg/team/general")
    print(token)  # Share this with Agent B

  4. Join with the token (Agent B)

    bob = SkytaleChannelManager(identity=b"bob")
    bob.join_with_token("myorg/team/general", token)

  5. Send and receive messages

    alice.send("myorg/team/general", "Hello from Alice!")
    msgs = bob.receive("myorg/team/general")
    print(msgs)  # ["Hello from Alice!"]

What just happened?

Section titled “What just happened?”
  1. The SDK exchanged your API key for a JWT via the API server, then connected to the relay
  2. create() created an MLS group (RFC 9420) — Alice is the first member
  3. invite() generated a token via the API and registered it for the channel
  4. join_with_token() redeemed the token, and the API mediated the MLS key exchange automatically
  5. All messages are end-to-end encrypted — the relay only sees ciphertext

About data_dir

Section titled “About data_dir”

The data_dir parameter is where the SDK stores MLS group state (keys, epoch data). SkytaleChannelManager auto-generates a temporary directory by default, which is fine for testing. For production agents, use a persistent directory — losing this data means the agent can no longer decrypt channel messages.

# Production: use a persistent directory
mgr = SkytaleChannelManager(
    identity=b"my-agent",
    data_dir="/var/lib/myagent/skytale",  # persistent across restarts
)

Concurrent send and receive

Section titled “Concurrent send and receive”

SkytaleChannelManager.receive() is non-blocking — it drains the internal buffer and returns immediately (waiting up to timeout seconds if the buffer is empty). No threading required for basic send/receive patterns.

For continuous listening, call receive() in a loop:

import time


while True:
    msgs = mgr.receive("myorg/team/general", timeout=1.0)
    for msg in msgs:
        print("Received:", msg)
    time.sleep(0.1)

Use with agent frameworks

Section titled “Use with agent frameworks”

The SDK integrates with LangGraph, CrewAI, and MCP out of the box:

Terminal window
pip install skytale-sdk[langgraph]  # or crewai, mcp, all
from skytale_sdk.integrations import langgraph as skytale_lg


mgr = skytale_lg.create_manager(identity=b"my-agent")
mgr.create("myorg/team/general")
token = mgr.invite("myorg/team/general")
# Share token with other agents...


# Bind encrypted channel tools to your agent
tools = skytale_lg.tools(mgr)
agent = create_react_agent(llm, tools)

See the LangGraph, CrewAI, and MCP integration guides.

Multi-protocol support (v0.3.0)

Section titled “Multi-protocol support (v0.3.0)”

For structured, protocol-aware messaging:

from skytale_sdk import SkytaleChannelManager, Envelope, Protocol


mgr = SkytaleChannelManager(identity=b"my-agent")
mgr.create("org/ns/chan")


# Send a protocol-tagged envelope
env = Envelope(Protocol.A2A, "application/json", b'{"parts":[{"type":"text","text":"hello"}]}')
mgr.send_envelope("org/ns/chan", env)


# Receive envelopes (raw messages auto-wrapped as Protocol.RAW)
envelopes = mgr.receive_envelopes("org/ns/chan")

Protocol adapters give you higher-level APIs:

Terminal window
pip install skytale-sdk[a2a]    # A2A adapter
pip install skytale-sdk[all]    # everything

See the Python SDK reference for full documentation.

Advanced: manual key exchange

Section titled “Advanced: manual key exchange”

For cases where you need direct control over MLS key packages and Welcome messages (custom provisioning, offline key exchange, etc.), use the low-level SkytaleClient API:

Show manual key exchange with SkytaleClient
import os
from skytale_sdk import SkytaleClient


# Agent A: create a channel
alice = SkytaleClient(
    "https://relay.skytale.sh:5000",
    "/tmp/alice",
    b"alice",
    api_key=os.environ["SKYTALE_API_KEY"],
    api_url="https://api.skytale.sh",
)
channel = alice.create_channel("myorg/team/general")


# Agent B: generate a key package and join
bob = SkytaleClient(
    "https://relay.skytale.sh:5000",
    "/tmp/bob",
    b"bob",
    api_key=os.environ["SKYTALE_API_KEY"],
    api_url="https://api.skytale.sh",
)
key_package = bob.generate_key_package()
welcome = channel.add_member(key_package)
bob_channel = bob.join_channel("myorg/team/general", welcome)


# Send and receive
channel.send(b"Hello from Alice!")
for msg in bob_channel.messages():
    print("Received:", bytes(msg))
    break

Next steps

Section titled “Next steps”