agent-relay 3.2.2 → 3.2.4

package/packages/sdk-py/src/agent_relay/communicate/adapters/openai_agents.py

@@ -0,0 +1,86 @@
+"""OpenAI Agents adapter for on_relay()."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+
+def _format_instructions_with_inbox(messages: list[Any], base_instructions: str) -> str:
+    content = "\n\nNew messages from other agents:\n"
+    for message in messages:
+        content += f"  {message.sender}: {message.text}\n"
+    return f"{content}\n{base_instructions}" if base_instructions else content
+
+
+def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
+    """Wrap OpenAI Agent to connect it to the relay."""
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(getattr(agent, "name", "Agent"))
+    try:
+        from agents import function_tool
+    except ImportError:
+        raise ImportError(
+            "on_relay() for OpenAI Agents requires the 'openai-agents' package. "
+            "Install it with: pip install openai-agents"
+        )
+
+    async def relay_send(to: str, text: str) -> str:
+        """Send a private message to another agent."""
+        await relay.send(to, text)
+        return "Message sent"
+
+    async def relay_inbox() -> str:
+        """Check for new messages in the inbox."""
+        messages = await relay.inbox()
+        if not messages: return "No new messages"
+        return "\n".join([f"From {m.sender}: {m.text}" for m in messages])
+
+    async def relay_post(channel: str, text: str) -> str:
+        """Post a message to a shared channel."""
+        await relay.post(channel, text)
+        return "Message posted"
+
+    async def relay_agents() -> str:
+        """List all agents currently on the relay."""
+        agents = await relay.agents()
+        return ", ".join(agents)
+
+    agent.tools.extend([
+        function_tool(relay_send),
+        function_tool(relay_inbox),
+        function_tool(relay_post),
+        function_tool(relay_agents)
+    ])
+
+    # 2. Wrap instructions with a local buffer so we don't starve relay_inbox tool
+    orig_instructions = agent.instructions
+    pending_messages: list[Any] = []
+
+    relay.on_message(lambda msg: pending_messages.append(msg))
+
+    async def instructions_wrapper(*args: Any, **kwargs: Any) -> str:
+        if callable(orig_instructions):
+            if inspect.iscoroutinefunction(orig_instructions):
+                base = await orig_instructions(*args, **kwargs)
+            else:
+                base = orig_instructions(*args, **kwargs)
+                if inspect.isawaitable(base):
+                    base = await base
+        else:
+            base = orig_instructions
+
+        base = base or ""
+        if not pending_messages:
+            return base
+
+        messages = list(pending_messages)
+        pending_messages.clear()
+        return _format_instructions_with_inbox(messages, base)
+
+    agent.instructions = instructions_wrapper
+    return agent

package/packages/sdk-py/src/agent_relay/communicate/adapters/pi.py

@@ -0,0 +1,175 @@
+"""Pi RPC adapter for on_relay().
+
+Spawns Pi (a TypeScript coding agent) as a subprocess in RPC mode and bridges
+relay communication over its stdin/stdout JSONL protocol.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import threading
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+RELAY_TOOL_PREAMBLE = (
+    "You have access to the following relay tools for multi-agent communication:\n"
+    "- relay_send(to, text): Send a direct message to another relay agent.\n"
+    "- relay_inbox(): Drain and inspect newly received relay messages.\n"
+    "- relay_post(channel, text): Post a message to a relay channel.\n"
+    "- relay_agents(): List currently online relay agents.\n"
+)
+
+
+class PiRpcSession:
+    """Manages a Pi subprocess in RPC mode with relay integration."""
+
+    def __init__(
+        self,
+        proc: subprocess.Popen[str],
+        relay: "Relay",
+    ) -> None:
+        self._proc = proc
+        self._relay = relay
+        self._is_streaming = False
+        self._unsubscribe: Callable[[], None] | None = None
+        self._reader_thread: threading.Thread | None = None
+        self._event_callbacks: list[Callable[[dict[str, Any]], None]] = []
+        self._closed = False
+
+    @property
+    def is_streaming(self) -> bool:
+        return self._is_streaming
+
+    def send_command(self, command: dict[str, Any]) -> None:
+        """Send a JSONL command to Pi's stdin."""
+        if self._proc.stdin is None:
+            return
+        line = json.dumps(command) + "\n"
+        self._proc.stdin.write(line)
+        self._proc.stdin.flush()
+
+    def prompt(self, message: str, streaming_behavior: str | None = None) -> None:
+        cmd: dict[str, Any] = {"type": "prompt", "message": message}
+        if streaming_behavior:
+            cmd["streamingBehavior"] = streaming_behavior
+        self.send_command(cmd)
+
+    def steer(self, message: str) -> None:
+        self.send_command({"type": "prompt", "message": message, "streamingBehavior": "steer"})
+
+    def follow_up(self, message: str) -> None:
+        self.send_command({"type": "prompt", "message": message, "streamingBehavior": "followUp"})
+
+    def abort(self) -> None:
+        self.send_command({"type": "abort"})
+
+    def on_event(self, callback: Callable[[dict[str, Any]], None]) -> Callable[[], None]:
+        self._event_callbacks.append(callback)
+
+        def unsubscribe() -> None:
+            try:
+                self._event_callbacks.remove(callback)
+            except ValueError:
+                pass
+
+        return unsubscribe
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._unsubscribe:
+            self._unsubscribe()
+            self._unsubscribe = None
+        if self._proc and self._proc.poll() is None:
+            self._proc.terminate()
+            try:
+                self._proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+
+
+def _format_relay_message(message: Any) -> str:
+    location = f" [#{message.channel}]" if getattr(message, "channel", None) else ""
+    return f"Relay message from {message.sender}{location}: {message.text}"
+
+
+def _start_reader(session: PiRpcSession) -> None:
+    def _read_stdout() -> None:
+        proc = session._proc
+        if proc.stdout is None:
+            return
+        for line in proc.stdout:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            event_type = event.get("type", "")
+            if event_type in ("agent_start", "turn_start"):
+                session._is_streaming = True
+            elif event_type in ("agent_end", "turn_end"):
+                session._is_streaming = False
+            for cb in list(session._event_callbacks):
+                cb(event)
+
+    thread = threading.Thread(target=_read_stdout, daemon=True)
+    thread.start()
+    session._reader_thread = thread
+
+
+def on_relay(
+    name: str,
+    config: dict[str, Any] | None = None,
+    relay: "Relay | None" = None,
+) -> PiRpcSession:
+    """Spawn Pi in RPC mode and bridge relay communication.
+
+    Args:
+        name: Agent name for relay registration.
+        config: Optional dict with ``model``, ``provider``, or extra Pi CLI flags.
+        relay: Optional pre-configured Relay instance.
+
+    Returns:
+        A :class:`PiRpcSession` managing the subprocess and relay bridge.
+    """
+    if config is None:
+        config = {}
+    if relay is None:
+        from ..core import Relay
+
+        relay = Relay(name)
+
+    cmd = ["pi", "--mode", "rpc", "--no-session"]
+    if "model" in config:
+        cmd.extend(["--model", config["model"]])
+    if "provider" in config:
+        cmd.extend(["--provider", config["provider"]])
+
+    proc = subprocess.Popen(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    session = PiRpcSession(proc, relay)
+
+    def handle_relay_message(message: Any) -> None:
+        formatted = _format_relay_message(message)
+        if session.is_streaming:
+            session.steer(formatted)
+        else:
+            session.follow_up(formatted)
+
+    session._unsubscribe = relay.on_message(handle_relay_message)
+
+    _start_reader(session)
+
+    return session

package/packages/sdk-py/src/agent_relay/communicate/adapters/swarms.py

@@ -0,0 +1,44 @@
+"""Swarms adapter for on_relay()."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
+    """Wrap Swarms Agent to connect it to the relay."""
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(getattr(agent, "name", "Agent"))
+    
+    # 1. Add tools (as callables)
+    async def relay_send(to: str, text: str) -> str:
+        """Send a private message to another agent."""
+        await relay.send(to, text)
+        return "Message sent"
+
+    async def relay_inbox() -> str:
+        """Check for new messages in the inbox."""
+        messages = await relay.inbox()
+        if not messages: return "No new messages"
+        return "\n".join([f"From {m.sender}: {m.text}" for m in messages])
+
+    async def relay_post(channel: str, text: str) -> str:
+        """Post a message to a shared channel."""
+        await relay.post(channel, text)
+        return "Message posted"
+
+    async def relay_agents() -> str:
+        """List all agents currently on the relay."""
+        agents = await relay.agents()
+        return ", ".join(agents)
+
+    agent.tools.extend([relay_send, relay_inbox, relay_post, relay_agents])
+
+    # 2. Receiving: bridge relay on_message to agent.receive_message
+    def _handle_relay_message(message: Any) -> None:
+        agent.receive_message(message.sender, message.text)
+
+    relay.on_message(_handle_relay_message)
+    return agent

package/packages/sdk-py/src/agent_relay/communicate/core.py

@@ -0,0 +1,293 @@
+"""High-level Relay facade for communicate mode."""
+
+from __future__ import annotations
+
+import atexit
+import asyncio
+import threading
+import warnings
+from inspect import isawaitable
+from typing import Any, Callable
+
+from .transport import RelayTransport
+from .types import Message, MessageCallback, RelayConfig, RelayConfigError, RelayAuthError
+
+MAX_PENDING_MESSAGES = 10_000
+
+
+class Relay:
+    """Relay client with buffered inbox access and callback subscriptions."""
+
+    def __init__(self, agent_name: str, config: RelayConfig | None = None) -> None:
+        self.agent_name = agent_name
+        self.config = config if config is not None else RelayConfig.resolve()
+        self.transport = RelayTransport(agent_name, self.config)
+
+        self._pending: list[Message] = []
+        self._callbacks: list[MessageCallback] = []
+        self._state_lock = threading.Lock()
+        self._connect_task: asyncio.Task[None] | None = None
+        self._connect_future: asyncio.Future[None] | None = None
+        self._connected = False
+        self._ws_connected = False
+        self._poll_task: asyncio.Task[None] | None = None
+
+        self.transport.on_ws_message(self._handle_transport_message)
+
+        if self.config.auto_cleanup:
+            atexit.register(self.close_sync)
+
+    async def send(self, to: str, text: str) -> None:
+        await self._ensure_connected()
+        await self.transport.send_dm(to, text)
+
+    async def post(self, channel: str, text: str) -> None:
+        await self._ensure_connected()
+        await self.transport.post_message(channel, text)
+
+    async def reply(self, message_id: str, text: str) -> None:
+        await self._ensure_connected()
+        await self.transport.reply(message_id, text)
+
+    async def inbox(self) -> list[Message]:
+        await self._ensure_connected()
+        if not self._ws_connected:
+            polled = await self.transport.check_inbox()
+            for msg in polled:
+                await self._handle_transport_message(msg)
+        with self._state_lock:
+            messages = list(self._pending)
+            self._pending.clear()
+        return messages
+
+    async def peek(self) -> list[Message]:
+        """Return buffered messages without draining them."""
+        await self._ensure_connected()
+        if not self._ws_connected:
+            polled = await self.transport.check_inbox()
+            for msg in polled:
+                await self._handle_transport_message(msg)
+        with self._state_lock:
+            return list(self._pending)
+
+    def on_message(self, callback: MessageCallback) -> Callable[[], None]:
+        with self._state_lock:
+            self._callbacks.append(callback)
+
+        self._schedule_connect()
+
+        def unsubscribe() -> None:
+            with self._state_lock:
+                try:
+                    self._callbacks.remove(callback)
+                except ValueError:
+                    pass
+
+        return unsubscribe
+
+
+    async def join(self, channel: str) -> None:
+        await self._ensure_connected()
+        await self.transport.join_channel(channel)
+
+    async def agents(self) -> list[str]:
+        await self._ensure_connected()
+        return await self.transport.list_agents()
+
+    async def close(self) -> None:
+        connect_task = self._connect_task
+        self._connect_task = None
+
+        if connect_task is not None and not connect_task.done():
+            connect_task.cancel()
+            try:
+                await connect_task
+            except asyncio.CancelledError:
+                pass
+
+        poll_task = self._poll_task
+        self._poll_task = None
+        if poll_task is not None and not poll_task.done():
+            poll_task.cancel()
+            try:
+                await poll_task
+            except asyncio.CancelledError:
+                pass
+
+        await self.transport.disconnect()
+        self._connected = False
+        self._ws_connected = False
+
+    def send_sync(self, to: str, text: str) -> None:
+        return self._run_sync(self.send(to, text))
+
+    def post_sync(self, channel: str, text: str) -> None:
+        return self._run_sync(self.post(channel, text))
+
+    def inbox_sync(self) -> list[Message]:
+        return self._run_sync(self.inbox())
+
+    def agents_sync(self) -> list[str]:
+        return self._run_sync(self.agents())
+
+    def close_sync(self) -> None:
+        return self._run_sync(self.close())
+
+    async def __aenter__(self) -> "Relay":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+    async def _ensure_connected(self) -> None:
+        if self._connected:
+            return
+
+        # Deduplicate concurrent callers — reuse in-flight connect
+        if self._connect_future is not None and not self._connect_future.done():
+            await self._connect_future
+            return
+
+        current_task = asyncio.current_task()
+        connect_task = self._connect_task
+        if connect_task is not None and connect_task is not current_task and not connect_task.done():
+            await connect_task
+            return
+
+        loop = asyncio.get_running_loop()
+        self._connect_future = loop.create_future()
+        try:
+            try:
+                await self.transport.connect()
+                self._ws_connected = True
+            except Exception:
+                # WebSocket failed — register agent via HTTP and fall back to polling
+                await self.transport.register_agent()
+                self._ws_connected = False
+                self._start_poll_loop()
+
+            from contextlib import suppress
+            for ch in self.config.channels:
+                with suppress(Exception):
+                    await self.transport.join_channel(ch)
+
+            self._connected = True
+            self._connect_future.set_result(None)
+            self._connect_future = None
+        except Exception as exc:
+            # Ensure future is always resolved so waiters don't hang
+            if not self._connect_future.done():
+                self._connect_future.set_exception(exc)
+            self._connect_future = None
+            raise
+
+    def _schedule_connect(self) -> None:
+        if self._connected:
+            return
+
+        if self._connect_task is not None and not self._connect_task.done():
+            return
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            self._run_sync(self._ensure_connected())
+            return
+
+        task = loop.create_task(self._ensure_connected())
+        self._connect_task = task
+        task.add_done_callback(self._clear_connect_task)
+
+    def _clear_connect_task(self, task: asyncio.Task[None]) -> None:
+        if self._connect_task is task:
+            self._connect_task = None
+
+    def _start_poll_loop(self) -> None:
+        if self._poll_task is not None and not self._poll_task.done():
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        self._poll_task = loop.create_task(self._poll_loop())
+
+    async def _poll_loop(self) -> None:
+        interval = self.config.poll_interval_ms / 1000.0
+        while self._connected and not self._ws_connected:
+            try:
+                messages = await self.transport.check_inbox()
+                for msg in messages:
+                    await self._handle_transport_message(msg)
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                pass
+            await asyncio.sleep(interval)
+
+    async def _handle_transport_message(self, message: Message) -> None:
+        with self._state_lock:
+            callbacks = list(self._callbacks)
+            # Always buffer the message (spec: "both" case — callbacks AND inbox)
+            if len(self._pending) >= MAX_PENDING_MESSAGES:
+                self._pending.pop(0)
+                warnings.warn(
+                    "Relay pending buffer exceeded 10,000 messages; dropping oldest message.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            self._pending.append(message)
+
+        for callback in callbacks:
+            result = callback(message)
+            if isawaitable(result):
+                await result
+
+    @staticmethod
+    def _run_sync(awaitable: Any) -> Any:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(awaitable)
+        # Running inside an active event loop — execute in a separate thread
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, awaitable).result()
+
+
+def on_relay(agent: Any, relay: Relay | None = None) -> Any:
+    """Auto-detect and apply the correct relay adapter for the given agent."""
+    if relay is None:
+        # Resolve a default relay if none provided
+        relay = Relay(getattr(agent, "name", "Agent"))
+
+    cls_module = type(agent).__module__
+    if cls_module.startswith("claude_agent_sdk"):
+        agent_name = getattr(agent, "name", "Agent")
+        from .adapters.claude_sdk import on_relay as _adapt
+        return _adapt(agent_name, agent, relay)
+    if cls_module.startswith("agents"):
+        from .adapters.openai_agents import on_relay as _adapt
+        return _adapt(agent, relay)
+    if cls_module.startswith("google.adk"):
+        from .adapters.google_adk import on_relay as _adapt
+        return _adapt(agent, relay)
+    if cls_module.startswith("agno"):
+        from .adapters.agno import on_relay as _adapt
+        return _adapt(agent, relay)
+    if cls_module.startswith("swarms"):
+        from .adapters.swarms import on_relay as _adapt
+        return _adapt(agent, relay)
+    if cls_module.startswith("crewai"):
+        from .adapters.crewai import on_relay as _adapt
+        return _adapt(agent, relay)
+
+    raise TypeError(
+        f"on_relay() doesn't recognize {type(agent).__name__} from {cls_module}. "
+        "Supported frameworks: Claude Agent SDK, OpenAI Agents, Google ADK, Agno, Swarms, CrewAI (Python). "
+        "For Claude Agent SDK, you can also import directly: "
+        "from agent_relay.communicate.adapters.claude_sdk import on_relay"
+    )
+
+
+__all__ = ["Relay", "on_relay"]