agent-relay 3.2.2 → 3.2.4

package/packages/sdk-py/README.md

@@ -1,20 +1,35 @@
 # Agent Relay Python SDK
 
-Python SDK for real-time agent-to-agent communication. Spawn AI agents, send messages, and coordinate multi-agent workflows with a simple async API.
+Python SDK for two workflows:
+
+- `Orchestrate` mode spawns and manages AI agents from Python.
+- `Communicate` mode puts an existing agent framework on Relaycast with `Relay` + `on_relay()`.
 
 ## Installation
 
+### Orchestrate
+
 ```bash
 pip install agent-relay-sdk
 ```
 
-The SDK automatically downloads the broker binary on first use.
+### Communicate
+
+```bash
+pip install "agent-relay-sdk[communicate]"
+```
+
+The SDK automatically downloads the broker binary on first use. Communicate mode also needs the framework package you want to wrap, such as `claude-agent-sdk`, `google-adk`, `agno`, `swarms`, or `crewai`.
 
 ## Requirements
 
 - Python 3.10+
 
-## Quick Start
+## Choose a Mode
+
+### Orchestrate
+
+Use `AgentRelay` when you want Python to spawn agents, wait for readiness, route messages, and shut everything down.
 
 ```python
 import asyncio
@@ -22,45 +37,56 @@ from agent_relay import AgentRelay, Models
 
 async def main():
     relay = AgentRelay(channels=["dev"])
-
-    # Event hooks
     relay.on_message_received = lambda msg: print(f"[{msg.from_name}]: {msg.text}")
-    relay.on_agent_ready = lambda agent: print(f"  {agent.name} ready")
-    relay.on_agent_exited = lambda agent: print(f"  {agent.name} exited")
 
-    # Spawn agents
     await relay.claude.spawn(
         name="Reviewer",
         model=Models.Claude.OPUS,
         channels=["dev"],
         task="Review the PR and suggest improvements",
     )
-
     await relay.codex.spawn(
         name="Builder",
         model=Models.Codex.GPT_5_3_CODEX,
         channels=["dev"],
-        task="Implement the suggested improvements",
+        task="Implement the suggestions",
     )
 
-    # Wait for both agents to be ready
     await asyncio.gather(
         relay.wait_for_agent_ready("Reviewer"),
         relay.wait_for_agent_ready("Builder"),
     )
-
-    # Let agents collaborate, then shut down
-    await asyncio.sleep(600)
     await relay.shutdown()
 
 asyncio.run(main())
 ```
 
+### Communicate
+
+Use `Relay` + `on_relay()` when your framework already owns the runtime and you only want Relaycast messaging.
+
+```python
+relay = Relay("Researcher")
+agent = FrameworkAgent(...)
+agent = on_relay(agent, relay)
+```
+
+Supported Python adapters:
+
+- OpenAI Agents
+- Claude Agent SDK
+- Google ADK
+- Agno
+- Swarms
+- CrewAI
+
+The wrapped agent gets Relay tools for direct messages, channel posts, inbox reads, and agent discovery. Framework-specific receive hooks are added automatically.
+
 ## API
 
 ### AgentRelay
 
-The main entry point. Pass `channels` to subscribe to message channels.
+The main Orchestrate entry point. Pass `channels` to subscribe to message channels.
 
 ```python
 relay = AgentRelay(channels=["dev", "planning"])
@@ -78,7 +104,6 @@ await relay.gemini.spawn(name="Agent3", model=Models.Gemini.GEMINI_2_5_PRO, chan
 worker = await relay.claude.spawn(
     name="HookedWorker",
     channels=["dev"],
-    # Lifecycle hooks can be sync or async callables.
     on_start=lambda ctx: print(f"spawning {ctx['name']}"),
     on_success=lambda ctx: print(f"spawned {ctx['name']} ({ctx['runtime']})"),
     on_error=lambda ctx: print(f"failed to spawn {ctx['name']}: {ctx['error']}"),
@@ -91,22 +116,39 @@ await worker.release(
 )
 ```
 
-### Sending Messages
+### Relay
+
+The Communicate-mode client. Configure it directly or via `RELAY_WORKSPACE`, `RELAY_API_KEY`, and `RELAY_BASE_URL`.
 
 ```python
-human = relay.system()
-await human.send_message(to="Agent1", text="Please start the analysis")
+from agent_relay import Relay
+
+relay = Relay("Researcher")
+await relay.send("Lead", "Status update")
+await relay.post("docs", "Wave 5.1 complete")
+messages = await relay.inbox()
+```
+
+### `on_relay()`
+
+Wrap a framework-owned agent or options object and keep the runtime you already use.
+
+```python
+from agent_relay import Relay, on_relay
+
+relay = Relay("Researcher")
+wrapped = on_relay(framework_agent_or_options, relay)
 ```
 
 ### Event Hooks
 
 ```python
-relay.on_message_received = lambda msg: ...   # New message
-relay.on_agent_ready = lambda agent: ...       # Agent connected
-relay.on_agent_exited = lambda agent: ...      # Agent exited
-relay.on_agent_spawned = lambda agent: ...     # Agent spawned
-relay.on_worker_output = lambda data: ...      # Agent output
-relay.on_agent_idle = lambda agent: ...        # Agent idle
+relay.on_message_received = lambda msg: ...       # New message
+relay.on_agent_ready = lambda agent: ...          # Agent connected
+relay.on_agent_exited = lambda agent: ...         # Agent exited
+relay.on_agent_spawned = lambda agent: ...        # Agent spawned
+relay.on_worker_output = lambda data: ...         # Agent output
+relay.on_agent_idle = lambda agent: ...           # Agent idle
 ```
 
 ### Models

package/packages/sdk-py/examples/communicate/agno_example.py

@@ -0,0 +1,8 @@
+from agent_relay import Relay, on_relay
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+
+relay = Relay("AgnoWorker")
+agent = Agent(model=OpenAIChat(id="gpt-5-mini"), instructions="Use relay tools when needed.")
+agent = on_relay(agent, relay)
+print(len(agent.tools))

package/packages/sdk-py/examples/communicate/claude_sdk_example.py

@@ -0,0 +1,6 @@
+from agent_relay import Relay, on_relay
+from claude_agent_sdk import ClaudeAgentOptions
+
+relay = Relay("ClaudeWorker")
+options = on_relay("ClaudeWorker", ClaudeAgentOptions(), relay)
+print(options.mcp_servers)

package/packages/sdk-py/examples/communicate/crewai_example.py

@@ -0,0 +1,7 @@
+from agent_relay import Relay, on_relay
+from crewai import Agent
+
+relay = Relay("CrewWorker")
+agent = Agent(role="Relay worker", goal="Coordinate with teammates", backstory="You check relay messages before acting.", llm="gpt-4o-mini")
+agent = on_relay(agent, relay)
+print(agent.backstory)

package/packages/sdk-py/examples/communicate/google_adk_example.py

@@ -0,0 +1,7 @@
+from agent_relay import Relay, on_relay
+from google.adk.agents import Agent
+
+relay = Relay("GoogleWorker")
+agent = Agent(name="GoogleWorker", model="gemini-2.0-flash", instruction="Use relay tools when needed.")
+agent = on_relay(agent, relay)
+print([tool.__name__ for tool in agent.tools])

package/packages/sdk-py/examples/communicate/openai_agents_example.py

@@ -0,0 +1,8 @@
+from agent_relay import Relay
+from agent_relay.communicate.adapters.openai_agents import on_relay
+from openai_agents import Agent
+
+relay = Relay("OpenAIWorker")
+agent = Agent(name="OpenAIWorker", instructions="Check relay_inbox before acting.")
+agent = on_relay(agent, relay)
+print(len(agent.tools))

package/packages/sdk-py/examples/communicate/swarms_example.py

@@ -0,0 +1,7 @@
+from agent_relay import Relay, on_relay
+from swarms import Agent
+
+relay = Relay("SwarmsWorker")
+agent = Agent(agent_name="SwarmsWorker", system_prompt="Use relay tools when needed.", model_name="gpt-4o-mini", max_loops=1)
+agent = on_relay(agent, relay)
+print(agent.run("Check relay_inbox, then say hello to the team."))

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.2"
+version = "3.2.4"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"
@@ -14,9 +14,20 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+communicate = [
+    "aiohttp>=3.9",
+]
+openai-agents = ["openai-agents>=0.1"]
+claude-sdk = ["claude-agent-sdk>=0.1"]
+google-adk = ["google-adk>=0.1"]
+agno = ["agno>=0.1"]
+swarms = ["swarms>=0.1"]
+crewai = ["crewai>=0.1"]
 dev = [
+    "aiohttp>=3.9",
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
 ]
 
 [tool.hatch.build.targets.wheel]

package/packages/sdk-py/src/agent_relay/__init__.py

@@ -3,6 +3,13 @@
 # ── Primary API: Direct spawn/message (matches TypeScript SDK) ────────────────
 
 from .relay import AgentRelay, Agent, AgentSpawner, HumanHandle, Message, SpawnOptions
+_has_communicate = False
+try:
+    from .communicate import Relay, RelayConfig, on_relay
+    _has_communicate = True
+except ImportError:
+    # communicate extras not installed (pip install agent-relay-sdk[communicate])
+    pass
 from .models import Models
 from .client import AgentRelayClient, AgentRelayProtocolError, AgentRelayProcessError
 from .protocol import (
@@ -76,6 +83,7 @@ __all__ = [
     "HumanHandle",
     "Message",
     "SpawnOptions",
+    *(["Relay", "RelayConfig", "on_relay"] if _has_communicate else []),
     "Models",
     "AgentRelayClient",
     "AgentRelayProtocolError",

package/packages/sdk-py/src/agent_relay/builder.py

@@ -243,36 +243,71 @@ class WorkflowBuilder:
         self,
         name: str,
         *,
-        agent: str,
-        task: str,
+        type: str | None = None,
+        # Agent step fields
+        agent: str | None = None,
+        task: str | None = None,
+        # Common fields
         depends_on: list[str] | None = None,
         verification: VerificationCheck | None = None,
         timeout_ms: int | None = None,
         retries: int | None = None,
+        # Deterministic step fields
+        command: str | None = None,
+        capture_output: bool | None = None,
+        fail_on_error: bool | None = None,
+        # Worktree step fields
+        branch: str | None = None,
+        base_branch: str | None = None,
+        path: str | None = None,
+        create_branch: bool | None = None,
     ) -> WorkflowBuilder:
         """Add a workflow step."""
-        opts = StepOptions(
-            agent=agent,
-            task=task,
-            depends_on=depends_on,
-            verification=verification,
-            timeout_ms=timeout_ms,
-            retries=retries,
-        )
-        step_def: dict[str, Any] = {
-            "name": name,
-            "agent": opts.agent,
-            "task": opts.task,
-        }
-
-        if opts.depends_on is not None:
-            step_def["dependsOn"] = opts.depends_on
-        if opts.verification is not None:
-            step_def["verification"] = opts.verification.to_dict()
-        if opts.timeout_ms is not None:
-            step_def["timeoutMs"] = opts.timeout_ms
-        if opts.retries is not None:
-            step_def["retries"] = opts.retries
+        if type == "deterministic":
+            if not command:
+                raise ValueError("deterministic steps must have a command")
+            if agent is not None or task is not None:
+                raise ValueError("deterministic steps must not have agent or task")
+            step_def: dict[str, Any] = {"name": name, "type": "deterministic", "command": command}
+            if capture_output is not None:
+                step_def["captureOutput"] = capture_output
+            if fail_on_error is not None:
+                step_def["failOnError"] = fail_on_error
+            if depends_on is not None:
+                step_def["dependsOn"] = depends_on
+            if verification is not None:
+                step_def["verification"] = verification.to_dict()
+            if timeout_ms is not None:
+                step_def["timeoutMs"] = timeout_ms
+        elif type == "worktree":
+            if agent is not None or task is not None:
+                raise ValueError("worktree steps must not have agent or task")
+            if not branch:
+                raise ValueError("worktree steps must have a branch")
+            step_def = {"name": name, "type": "worktree", "branch": branch}
+            if base_branch is not None:
+                step_def["baseBranch"] = base_branch
+            if path is not None:
+                step_def["path"] = path
+            if create_branch is not None:
+                step_def["createBranch"] = create_branch
+            if depends_on is not None:
+                step_def["dependsOn"] = depends_on
+            if timeout_ms is not None:
+                step_def["timeoutMs"] = timeout_ms
+        else:
+            # Agent step
+            if not agent or not task:
+                raise ValueError("Agent steps must have both agent and task")
+            step_def = {"name": name, "agent": agent, "task": task}
+            if depends_on is not None:
+                step_def["dependsOn"] = depends_on
+            if verification is not None:
+                step_def["verification"] = verification.to_dict()
+            if timeout_ms is not None:
+                step_def["timeoutMs"] = timeout_ms
+            if retries is not None:
+                step_def["retries"] = retries
 
         self._steps.append(step_def)
         return self
@@ -302,11 +337,15 @@ class WorkflowBuilder:
 
     def to_config(self) -> dict[str, Any]:
         """Build and return the config as a dictionary (RelayYamlConfig shape)."""
-        if not self._agents:
-            raise ValueError("Workflow must have at least one agent")
         if not self._steps:
             raise ValueError("Workflow must have at least one step")
 
+        has_agent_steps = any(
+            s.get("type") not in ("deterministic", "worktree") for s in self._steps
+        )
+        if has_agent_steps and not self._agents:
+            raise ValueError("Workflow must have at least one agent when using agent steps")
+
         swarm: dict[str, Any] = {"pattern": self._pattern}
         if self._max_concurrency is not None:
             swarm["maxConcurrency"] = self._max_concurrency

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

@@ -0,0 +1,6 @@
+"""Agent Relay Communicate Mode -- put any agent on the relay."""
+
+from .core import Relay, on_relay
+from .types import Message, RelayConfig
+
+__all__ = ["Relay", "Message", "RelayConfig", "on_relay"]

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

@@ -0,0 +1,138 @@
+"""Bridge that connects an external A2A agent into a Relay workspace."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import aiohttp
+
+from .a2a_types import A2AAgentCard, A2AConfig, A2AMessage, A2APart
+from .core import Relay
+from .types import Message, RelayConfig
+
+
+class A2ABridge:
+    """Bridges an external A2A agent into a Relay workspace.
+
+    - Registers a proxy agent on the Relay workspace
+    - When Relay messages arrive for the proxy, forwards them as A2A JSON-RPC
+      message/send calls to the external agent
+    - When A2A responses come back, forwards them as Relay DMs
+
+    Usage:
+        bridge = A2ABridge(
+            relay_config=RelayConfig(workspace="myworkspace", api_key="rk_..."),
+            a2a_agent_url="https://partner-billing-agent.example.com",
+            proxy_name="partner-billing",
+        )
+        await bridge.start()
+        # Now "partner-billing" appears as an agent in the Relay workspace
+    """
+
+    def __init__(
+        self,
+        relay_config: RelayConfig,
+        a2a_agent_url: str,
+        proxy_name: str,
+    ) -> None:
+        self.relay = Relay(proxy_name, relay_config)
+        self.a2a_agent_url = a2a_agent_url.rstrip("/")
+        self.proxy_name = proxy_name
+        self._session: aiohttp.ClientSession | None = None
+        self._agent_card: A2AAgentCard | None = None
+        self._started = False
+
+    async def start(self) -> None:
+        """Register proxy on Relay, listen for messages, forward to A2A agent."""
+        await self.relay.__aenter__()
+        self.relay.on_message(self._handle_relay_message)
+        self._started = True
+
+    async def stop(self) -> None:
+        """Disconnect from Relay and clean up."""
+        self._started = False
+        await self.relay.__aexit__(None, None, None)
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def discover_agent(self) -> A2AAgentCard:
+        """Fetch the external A2A agent's Agent Card."""
+        session = await self._ensure_session()
+        url = f"{self.a2a_agent_url}/.well-known/agent.json"
+        async with session.get(url) as resp:
+            data = await resp.json()
+        self._agent_card = A2AAgentCard(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            url=data.get("url", self.a2a_agent_url),
+            version=data.get("version", "1.0.0"),
+        )
+        return self._agent_card
+
+    async def send_a2a_message(self, text: str) -> str | None:
+        """Send a message/send JSON-RPC call to the external A2A agent.
+
+        Returns the response text if available.
+        """
+        session = await self._ensure_session()
+
+        a2a_msg = {
+            "role": "user",
+            "parts": [{"text": text}],
+            "messageId": str(uuid.uuid4()),
+        }
+
+        jsonrpc_request = {
+            "jsonrpc": "2.0",
+            "method": "message/send",
+            "params": {"message": a2a_msg},
+            "id": str(uuid.uuid4()),
+        }
+
+        target_url = self.a2a_agent_url
+        if self._agent_card and self._agent_card.url:
+            target_url = self._agent_card.url
+
+        async with session.post(target_url, json=jsonrpc_request) as resp:
+            data = await resp.json()
+
+        result = data.get("result", {})
+        # Extract response text from the task
+        status = result.get("status", {})
+        status_msg = status.get("message", {})
+        parts = status_msg.get("parts", [])
+        if parts:
+            return parts[0].get("text")
+
+        # Try from messages list
+        messages = result.get("messages", [])
+        for msg in reversed(messages):
+            if msg.get("role") == "agent":
+                msg_parts = msg.get("parts", [])
+                if msg_parts:
+                    return msg_parts[0].get("text")
+
+        return None
+
+    async def _handle_relay_message(self, msg: Message) -> None:
+        """Forward Relay message to A2A agent, then forward response back."""
+        response_text = await self.send_a2a_message(msg.text)
+        if response_text:
+            await self.relay.send(msg.sender, response_text)
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def __aenter__(self) -> "A2ABridge":
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.stop()
+
+
+__all__ = ["A2ABridge"]