Architecture

Skytale has three main components: the SDK, the API server, and the relay.

Components

SDK (`skytale-sdk`)

The Python package your agents import. It handles:

MLS group creation and management (RFC 9420)
Message encryption and decryption
QUIC transport to the relay
API key to JWT exchange (automatic)
Protocol-tagged envelopes (A2A, MCP, SLIM)
Cross-protocol bridge and translation

Framework integrations are built on top of the SDK:

LangGraph — @tool-decorated functions (pip install skytale-sdk[langgraph])
CrewAI — BaseTool subclasses (pip install skytale-sdk[crewai])
MCP — FastMCP server for any MCP client (pip install skytale-sdk[mcp])

Protocol adapters (v0.3.0) add multi-protocol support:

A2A — maps Google A2A contexts/messages to channels (pip install skytale-sdk[a2a])
MCP Transport — MCP JSON-RPC over encrypted channels
SLIM — explicit publish/subscribe adapter for bridge compatibility

All integrations and adapters use SkytaleChannelManager, which wraps SkytaleClient with background message buffering for non-blocking tool calls.

API server

An HTTP API (Axum + Postgres) that manages:

Account creation and management
API key generation and revocation
JWT token issuance for relay authentication
Usage metering

Relay (`skytale-relay`)

A QUIC-based message relay that handles:

Routing encrypted messages between agents
gRPC edge interface for full SLIM compatibility
MLS commit ordering (GroupProposal, GroupAdd, GroupRemove)
Message archiving with per-channel sequence numbers
No access to message plaintext (zero-knowledge)

gRPC services

The relay exposes three gRPC services on its gRPC port (default 5000):

Service	Purpose
`DataPlaneService`	SLIM bidirectional streaming — Subscribe, Unsubscribe, Publish
`grpc.health.v1.Health`	Standard health check for load balancers and probes
gRPC Server Reflection	Schema discovery — SLIM agents introspect the API at runtime

SLIM message types

The relay handles all SLIM session message types:

Type	Behavior
Msg	Archived with sequence number, relayed to channel subscribers
GroupProposal / GroupAdd / GroupRemove	MLS commit ordered, archived, relayed with ack/nack
GroupWelcome	Relayed directly to channel subscribers
JoinRequest / JoinReply	Relayed through to channel subscribers (not interpreted)
LeaveRequest / LeaveReply	Relayed through to channel subscribers (not interpreted)
DiscoveryRequest / DiscoveryReply	Relayed through to channel subscribers (not interpreted)
GroupClose	Relayed through to channel subscribers (not interpreted)
Ping	Responded to immediately with Pong

Relay-through messages let SLIM agents coordinate MLS group membership peer-to-peer. The relay forwards the full SLIM envelope without interpreting the payload.

Data flow

Agent A (SDK)                          Agent B (SDK)
     |                                       |
     |  1. Encrypt with MLS                  |
     |  2. Send via QUIC or gRPC             |
     |                                       |
     +-------->  Relay (ciphertext)  ------->+
                    |                        |
                    | Route only,            | 3. Decrypt with MLS
                    | never decrypt          |

SLIM compatibility

SLIM agents communicate via gRPC. The relay exposes a gRPC edge interface (DataPlaneService) that accepts SLIM protobuf messages over bidirectional streams. From a SLIM agent’s perspective, the relay is a standard gRPC service — discoverable via reflection, monitorable via health checks.

TLS

The gRPC endpoint supports optional TLS. When grpc_tls_cert and grpc_tls_key are set in the relay config, the gRPC server terminates TLS. This is required for SLIM agents connecting over the public internet.

Authentication flow

Agent starts with an API key (sk_live_...)
SDK calls POST /v1/tokens on the API server
API server returns a JWT (HS256, issuer skytale-api)
SDK attaches the JWT as a Bearer token on the gRPC stream
Relay validates the JWT and allows channel operations
JWT expires — SDK automatically re-exchanges for a new one

Multi-protocol architecture (v0.3.0)

The MLS encryption layer is protocol-agnostic — the relay routes opaque ciphertext by channel ID. Protocol adapters in the SDK serialize protocol-specific messages into Envelope objects, which are MLS-encrypted and sent through channels.

Agent (A2A) ──> A2A Adapter ──> Envelope ──> MLS encrypt ──> Relay
Agent (MCP) ──> MCP Transport ─> Envelope ──> MLS encrypt ──> Relay
Agent (SLIM) ─> SLIM Adapter ──> Envelope ──> MLS encrypt ──> Relay

The ProtocolBridge translates between protocols client-side:

A2A Agent ──> [A2A Adapter] ──> Channel A ──> [Bridge] ──> Channel B ──> [MCP Transport] ──> MCP Client

All translation happens inside the SDK process after decryption. The relay never changes — it routes ciphertext.