SDK_REFERENCE.md

Relay Communicate SDK — Real API Reference

Installation

pip install agent-relay-sdk[communicate]
# Or from local: pip install -e /tmp/relay-565/packages/sdk-py[communicate]

Core Usage

import asyncio
import os
from agent_relay.communicate import Relay
from agent_relay.communicate.types import RelayConfig, Message

config = RelayConfig(
    workspace=os.environ.get('RELAY_WORKSPACE', 'demo'),
    api_key=os.environ.get('RELAY_API_KEY', 'demo-key'),
    base_url='https://api.relaycast.dev',
)

# Create a relay instance for an agent
relay = Relay('my-agent-name', config)

# Connect (registers agent with Relaycast)
await relay.connect()

# Send a DM to another agent
msg_id = await relay.send('other-agent', 'hello!')

# Post to a channel
msg_id = await relay.post('general', 'broadcast message')

# Reply to a message
msg_id = await relay.reply(original_msg_id, 'my reply')

# Check inbox (returns list of Message objects)
messages = await relay.inbox()

# Register a callback for real-time messages
def on_message(msg: Message):
    print(f"From {msg.sender}: {msg.text}")
    
relay.on_message(on_message)

# List other agents
agents = await relay.agents()

# Disconnect when done
await relay.close()

# Or use as context manager
async with Relay('my-agent', config) as relay:
    await relay.send('other', 'hello')

Message Object

@dataclass(frozen=True)
class Message:
    sender: str
    text: str
    channel: str | None = None      # None = DM
    thread_id: str | None = None
    timestamp: float | None = None
    message_id: str | None = None

Framework Adapter Pattern (on_relay decorator)

from agent_relay.communicate import on_relay

# Wraps any framework agent to receive relay messages as tool calls
@on_relay(name='my-agent', config=config)
def my_agent_function(message: str) -> str:
    # Process message, return response
    return f"Processed: {message}"

Key Points

• All agents register with Relaycast via HTTP, communicate via WebSocket + HTTP
• DMs are point-to-point, channels are broadcast
• The SDK handles reconnection, retry, and cleanup automatically
• Each agent needs a unique name within the workspace
• RELAY_API_KEY is the workspace key (rk_live_...), each agent gets its own token on registration