agent-relay 3.2.2 → 3.2.4

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

@@ -0,0 +1,294 @@
+"""A2A (Agent-to-Agent) protocol data model types."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class A2APart:
+    """A single part of an A2A message (text, file, or structured data)."""
+
+    text: str | None = None
+    file: dict[str, Any] | None = None  # FileContent — phase 2
+    data: dict[str, Any] | None = None  # Structured data — phase 2
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {}
+        if self.text is not None:
+            d["text"] = self.text
+        if self.file is not None:
+            d["file"] = self.file
+        if self.data is not None:
+            d["data"] = self.data
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2APart:
+        return cls(
+            text=d.get("text"),
+            file=d.get("file"),
+            data=d.get("data"),
+        )
+
+
+@dataclass
+class A2AMessage:
+    """An A2A protocol message."""
+
+    role: str  # "user" | "agent"
+    parts: list[A2APart]
+    messageId: str | None = None
+    contextId: str | None = None
+    taskId: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.messageId is None:
+            self.messageId = str(uuid.uuid4())
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "role": self.role,
+            "parts": [p.to_dict() for p in self.parts],
+        }
+        if self.messageId is not None:
+            d["messageId"] = self.messageId
+        if self.contextId is not None:
+            d["contextId"] = self.contextId
+        if self.taskId is not None:
+            d["taskId"] = self.taskId
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2AMessage:
+        parts = [A2APart.from_dict(p) for p in d.get("parts", [])]
+        return cls(
+            role=d["role"],
+            parts=parts,
+            messageId=d.get("messageId"),
+            contextId=d.get("contextId"),
+            taskId=d.get("taskId"),
+        )
+
+    def get_text(self) -> str:
+        """Extract concatenated text from all text parts."""
+        return " ".join(p.text for p in self.parts if p.text)
+
+
+@dataclass
+class A2ATaskStatus:
+    """Status of an A2A task."""
+
+    state: str  # "submitted" | "working" | "completed" | "failed" | "canceled"
+    message: A2AMessage | None = None
+    timestamp: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.timestamp is None:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"state": self.state}
+        if self.message is not None:
+            d["message"] = self.message.to_dict()
+        if self.timestamp is not None:
+            d["timestamp"] = self.timestamp
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2ATaskStatus:
+        msg = None
+        if "message" in d and d["message"] is not None:
+            msg = A2AMessage.from_dict(d["message"])
+        return cls(
+            state=d["state"],
+            message=msg,
+            timestamp=d.get("timestamp"),
+        )
+
+
+VALID_TASK_STATES = {"submitted", "working", "completed", "failed", "canceled"}
+
+
+@dataclass
+class A2ATask:
+    """An A2A protocol task."""
+
+    id: str
+    contextId: str | None = None
+    status: A2ATaskStatus = field(
+        default_factory=lambda: A2ATaskStatus(state="submitted")
+    )
+    messages: list[A2AMessage] = field(default_factory=list)
+    artifacts: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "contextId": self.contextId,
+            "status": self.status.to_dict(),
+            "messages": [m.to_dict() for m in self.messages],
+            "artifacts": self.artifacts,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2ATask:
+        status = A2ATaskStatus.from_dict(d["status"]) if "status" in d else A2ATaskStatus(state="submitted")
+        messages = [A2AMessage.from_dict(m) for m in d.get("messages", [])]
+        return cls(
+            id=d["id"],
+            contextId=d.get("contextId"),
+            status=status,
+            messages=messages,
+            artifacts=d.get("artifacts", []),
+        )
+
+
+@dataclass
+class A2ASkill:
+    """A skill advertised by an A2A agent."""
+
+    id: str
+    name: str
+    description: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "name": self.name, "description": self.description}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2ASkill:
+        return cls(id=d["id"], name=d["name"], description=d["description"])
+
+
+@dataclass
+class A2AAgentCard:
+    """An A2A Agent Card describing an agent's capabilities and endpoint."""
+
+    name: str
+    description: str
+    url: str
+    version: str = "1.0.0"
+    capabilities: dict[str, Any] = field(
+        default_factory=lambda: {"streaming": True, "pushNotifications": False}
+    )
+    skills: list[A2ASkill] = field(default_factory=list)
+    defaultInputModes: list[str] = field(default_factory=lambda: ["text"])
+    defaultOutputModes: list[str] = field(default_factory=lambda: ["text"])
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "url": self.url,
+            "version": self.version,
+            "capabilities": self.capabilities,
+            "skills": [s.to_dict() for s in self.skills],
+            "defaultInputModes": self.defaultInputModes,
+            "defaultOutputModes": self.defaultOutputModes,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> A2AAgentCard:
+        skills = [A2ASkill.from_dict(s) for s in d.get("skills", [])]
+        return cls(
+            name=d["name"],
+            description=d["description"],
+            url=d["url"],
+            version=d.get("version", "1.0.0"),
+            capabilities=d.get("capabilities", {"streaming": True, "pushNotifications": False}),
+            skills=skills,
+            defaultInputModes=d.get("defaultInputModes", ["text"]),
+            defaultOutputModes=d.get("defaultOutputModes", ["text"]),
+        )
+
+
+@dataclass
+class A2AConfig:
+    """Configuration for A2A transport."""
+
+    # Server mode
+    server_port: int = 5000
+    server_host: str = "0.0.0.0"
+
+    # Client mode
+    target_url: str | None = None
+
+    # Agent Card registry (known A2A agent URLs)
+    registry: list[str] = field(default_factory=list)
+
+    # Auth
+    auth_scheme: str | None = None  # "bearer", "api_key", etc.
+    auth_token: str | None = None
+
+    # Agent metadata
+    agent_description: str | None = None
+    skills: list[A2ASkill] = field(default_factory=list)
+
+
+def make_jsonrpc_request(method: str, params: dict[str, Any], id: str | int | None = None) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 request envelope."""
+    req: dict[str, Any] = {
+        "jsonrpc": "2.0",
+        "method": method,
+        "params": params,
+    }
+    if id is not None:
+        req["id"] = id
+    else:
+        req["id"] = str(uuid.uuid4())
+    return req
+
+
+def make_jsonrpc_response(result: Any, id: str | int) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 success response."""
+    return {
+        "jsonrpc": "2.0",
+        "result": result,
+        "id": id,
+    }
+
+
+def make_jsonrpc_error(code: int, message: str, id: str | int | None) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 error response."""
+    return {
+        "jsonrpc": "2.0",
+        "error": {"code": code, "message": message},
+        "id": id,
+    }
+
+
+# Standard JSON-RPC error codes
+JSONRPC_PARSE_ERROR = -32700
+JSONRPC_INVALID_REQUEST = -32600
+JSONRPC_METHOD_NOT_FOUND = -32601
+JSONRPC_INVALID_PARAMS = -32602
+JSONRPC_INTERNAL_ERROR = -32603
+
+# A2A-specific error codes
+A2A_TASK_NOT_FOUND = -32001
+A2A_TASK_NOT_CANCELABLE = -32002
+
+
+__all__ = [
+    "A2AAgentCard",
+    "A2AConfig",
+    "A2AMessage",
+    "A2APart",
+    "A2ASkill",
+    "A2ATask",
+    "A2ATaskStatus",
+    "A2A_TASK_NOT_CANCELABLE",
+    "A2A_TASK_NOT_FOUND",
+    "JSONRPC_INTERNAL_ERROR",
+    "JSONRPC_INVALID_PARAMS",
+    "JSONRPC_INVALID_REQUEST",
+    "JSONRPC_METHOD_NOT_FOUND",
+    "JSONRPC_PARSE_ERROR",
+    "VALID_TASK_STATES",
+    "make_jsonrpc_error",
+    "make_jsonrpc_request",
+    "make_jsonrpc_response",
+]

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

@@ -0,0 +1,10 @@
+"""Framework-specific adapters for on_relay()."""
+
+_has_pi = False
+try:
+    from .pi import on_relay as on_pi_relay
+    _has_pi = True
+except ImportError:
+    pass
+
+__all__ = [*(["on_pi_relay"] if _has_pi else [])]

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

@@ -0,0 +1,74 @@
+"""Agno 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 Agno Agent to connect it to the relay."""
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(getattr(agent, "name", "Agent"))
+    
+    # 1. Add tools
+    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. 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/claude_sdk.py

@@ -0,0 +1,78 @@
+"""Claude Agent SDK adapter for on_relay()."""
+
+from __future__ import annotations
+import inspect
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+
+def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
+    """Wrap Claude Agent SDK query options to connect them to the relay."""
+    try:
+        from claude_agent_sdk.types import HookResult
+    except ImportError as exc:
+        raise ImportError(
+            "on_relay() for Claude Agent SDK requires the 'claude-agent-sdk' package. "
+            "Install it with: pip install claude-agent-sdk"
+        ) from exc
+
+    agent_name = name or getattr(options, "name", "Agent")
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(agent_name)
+
+    hooks = getattr(options, "hooks", None)
+    if hooks is None:
+        hooks = SimpleNamespace(post_tool_use=None, stop=None)
+        options.hooks = hooks
+
+    # 1. Inject Relaycast MCP server
+    mcp_config = {"name": "relaycast", "command": "agent-relay", "args": ["mcp"]}
+    if hasattr(options, "mcp_servers"):
+        options.mcp_servers.append(mcp_config)
+    else:
+        options.mcp_servers = [mcp_config]
+
+    # 2. Helper to format inbox messages
+    async def _drain_to_system_message() -> str | None:
+        messages = await relay.inbox()
+        if not messages: return None
+        content = "\n\nNew messages from other agents:\n"
+        for m in messages:
+            content += f"  Relay message from {m.sender}: {m.text}\n"
+        return content
+
+    # 3. Hook wrappers
+    orig_post = getattr(hooks, "post_tool_use", None)
+    orig_stop = getattr(hooks, "stop", None)
+
+    async def post_tool_use_hook(*args, **kwargs):
+        res = None
+        if orig_post:
+            res = orig_post(*args, **kwargs)
+            if inspect.isawaitable(res):
+                res = await res
+        msg = await _drain_to_system_message()
+        if not msg:
+            return res
+        combined = (res.system_message + msg) if (res and res.system_message) else msg
+        return HookResult(system_message=combined)
+
+    async def stop_hook(*args, **kwargs):
+        res = None
+        if orig_stop:
+            res = orig_stop(*args, **kwargs)
+            if inspect.isawaitable(res):
+                res = await res
+        msg = await _drain_to_system_message()
+        if not msg:
+            return res
+        combined = (res.system_message + msg) if (res and res.system_message) else msg
+        return HookResult(system_message=combined, should_continue=True)
+
+    options.hooks.post_tool_use = post_tool_use_hook
+    options.hooks.stop = stop_hook
+    return options

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

@@ -0,0 +1,143 @@
+"""CrewAI adapter for on_relay()."""
+
+from __future__ import annotations
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+
+def _message_key(message: Any) -> tuple[str | None, str, str]:
+    return (getattr(message, "message_id", None), message.sender, message.text)
+
+
+def _format_backstory(messages: list[Any], base_backstory: str) -> str:
+    if not messages:
+        return base_backstory
+
+    content = "\n\nNew messages from other agents:\n"
+    for message in messages:
+        content += f"  {message.sender}: {message.text}\n"
+    return f"{content}\n{base_backstory}" if base_backstory else content
+
+
+class _RelayBackstory:
+    def __init__(self, relay: "Relay", base_backstory: str, buffer: list[Any]) -> None:
+        self._relay = relay
+        self._base_backstory = base_backstory
+        self._buffer = buffer
+
+    def _drain_buffer(self) -> list[Any]:
+        messages = list(self._buffer)
+        self._buffer.clear()
+        return messages
+
+    def _dedupe(self, messages: list[Any]) -> list[Any]:
+        seen: set[tuple[str | None, str, str]] = set()
+        unique: list[Any] = []
+        for message in messages:
+            key = _message_key(message)
+            if key in seen:
+                continue
+            seen.add(key)
+            unique.append(message)
+        return unique
+
+    def _resolve_sync(self) -> str:
+        messages = self._drain_buffer()
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is None:
+            messages.extend(self._relay.inbox_sync())
+        else:
+            # Running inside an event loop — use a thread to avoid blocking
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                polled = pool.submit(asyncio.run, self._relay.inbox()).result()
+                messages.extend(polled)
+        return _format_backstory(self._dedupe(messages), self._base_backstory)
+
+    async def _resolve_async(self) -> str:
+        messages = self._drain_buffer()
+        messages.extend(await self._relay.inbox())
+        return _format_backstory(self._dedupe(messages), self._base_backstory)
+
+    def __call__(self) -> str:
+        return self._resolve_sync()
+
+    def __await__(self) -> Any:
+        return self._resolve_async().__await__()
+
+    def __contains__(self, item: str) -> bool:
+        return item in self._resolve_sync()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str):
+            return self._resolve_sync() == other
+        return NotImplemented
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._resolve_sync(), name)
+
+    def __repr__(self) -> str:
+        return repr(self._resolve_sync())
+
+    def __str__(self) -> str:
+        return self._resolve_sync()
+
+
+def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
+    """Wrap CrewAI Agent to connect it to the relay."""
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(getattr(agent, "name", "Agent"))
+    try:
+        from crewai.tools import tool
+    except ImportError:
+        raise ImportError(
+            "on_relay() for CrewAI requires the 'crewai' package. "
+            "Install it with: pip install crewai"
+        )
+
+    @tool
+    async def relay_send(to: str, text: str) -> str:
+        """Send a private message to another agent."""
+        await relay.send(to, text)
+        return "Message sent"
+
+    @tool
+    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])
+
+    @tool
+    async def relay_post(channel: str, text: str) -> str:
+        """Post a message to a shared channel."""
+        await relay.post(channel, text)
+        return "Message posted"
+
+    @tool
+    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])
+
+    backstory_buffer: list[Any] = []
+
+    def _buffer_message(message: Any) -> None:
+        backstory_buffer.append(message)
+
+    unsubscribe = relay.on_message(_buffer_message)
+    agent.backstory = _RelayBackstory(relay, agent.backstory or "", backstory_buffer)
+    agent._relay_unsubscribe = unsubscribe  # type: ignore[attr-defined]
+
+    return agent

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

@@ -0,0 +1,69 @@
+"""Google ADK adapter for on_relay()."""
+
+from __future__ import annotations
+import inspect
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core import Relay
+
+def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
+    """Wrap Google ADK Agent to connect it to the relay."""
+    if relay is None:
+        from ..core import Relay
+        relay = Relay(getattr(agent, "name", "Agent"))
+    
+    # 1. Add tools for sending
+    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. Inject before_model_callback for receiving
+    orig_callback = getattr(agent, "before_model_callback", None)
+
+    async def relay_callback(llm_request: Any) -> Any:
+        orig_result = None
+        if orig_callback:
+            orig_result = orig_callback(llm_request)
+            if inspect.isawaitable(orig_result):
+                orig_result = await orig_result
+
+        # Always inject relay messages, even if the original callback returned a result
+        messages = await relay.inbox()
+        if messages:
+            from google.genai.types import Content, Part
+
+            if getattr(llm_request, "contents", None) is None:
+                llm_request.contents = []
+
+            for message in messages:
+                llm_request.contents.append(
+                    Content(
+                        role="user",
+                        parts=[Part(text=f"[Relay] {message.sender}: {message.text}")],
+                    )
+                )
+
+        return orig_result
+
+    agent.before_model_callback = relay_callback
+    return agent