agent-relay 3.0.2 → 3.1.0

package/packages/sdk-py/README.md

@@ -1,141 +1,128 @@
 # Agent Relay Python SDK
 
-Python SDK for defining and running Agent Relay workflows with the same schema and
-builder capabilities as the TypeScript workflow 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.
 
-The SDK builds workflow config and executes it through:
+## Installation
 
 ```bash
-agent-relay run <workflow.yaml>
+pip install agent-relay-sdk
 ```
 
-## Install
+The SDK automatically downloads the broker binary on first use.
 
-```bash
-pip install agent-relay
-```
+## Requirements
 
-## Builder API
+- Python 3.10+
+
+## Quick Start
 
 ```python
-from agent_relay import workflow, VerificationCheck
-
-result = (
-    workflow("ship-feature")
-    .description("Plan, build, and verify a feature")
-    .pattern("dag")
-    .max_concurrency(3)
-    .timeout(60 * 60 * 1000)
-    .channel("feature-channel")
-    .idle_nudge(nudge_after_ms=120_000, escalate_after_ms=120_000, max_nudges=1)
-    .trajectories(enabled=True, reflect_on_converge=True)
-    .agent("planner", cli="claude", role="Planning lead")
-    .agent(
-        "builder",
-        cli="codex",
-        role="Implementation engineer",
-        interactive=False,
-        idle_threshold_secs=45,
-        retries=1,
+import asyncio
+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",
     )
-    .step("plan", agent="planner", task="Create a detailed plan")
-    .step(
-        "build",
-        agent="builder",
-        task="Implement the approved plan",
-        depends_on=["plan"],
-        verification=VerificationCheck(type="output_contains", value="DONE"),
+
+    await relay.codex.spawn(
+        name="Builder",
+        model=Models.Codex.GPT_5_3_CODEX,
+        channels=["dev"],
+        task="Implement the suggested improvements",
     )
-    .run()
-)
-```
 
-## Workflow Templates
+    # Wait for both agents to be ready
+    await asyncio.gather(
+        relay.wait_for_agent_ready("Reviewer"),
+        relay.wait_for_agent_ready("Builder"),
+    )
 
-Built-in template helpers are provided for common patterns:
+    # Let agents collaborate, then shut down
+    await asyncio.sleep(600)
+    await relay.shutdown()
 
-- `fan_out(...)`
-- `pipeline(...)`
-- `dag(...)`
+asyncio.run(main())
+```
 
-```python
-from agent_relay import fan_out
-
-builder = fan_out(
-    "parallel-analysis",
-    tasks=[
-        "Analyze backend modules and summarize risks",
-        "Analyze frontend modules and summarize risks",
-    ],
-    synthesis_task="Synthesize both analyses into one prioritized action plan",
-)
+## API
 
-config = builder.to_config()
-```
+### AgentRelay
+
+The main entry point. Pass `channels` to subscribe to message channels.
 
 ```python
-from agent_relay import pipeline, PipelineStage
-
-builder = pipeline(
-    "release-pipeline",
-    stages=[
-        PipelineStage(name="plan", task="Create release plan"),
-        PipelineStage(name="implement", task="Implement planned changes"),
-        PipelineStage(name="verify", task="Validate and produce release notes"),
-    ],
-)
+relay = AgentRelay(channels=["dev", "planning"])
 ```
 
-## Event Callbacks
+### Spawning Agents
 
-Execution callbacks receive typed workflow events parsed from CLI workflow logs.
+Use runtime-specific spawners:
 
 ```python
-from agent_relay import run_yaml, RunOptions
-
-def on_event(event):
-    print(event.type, event)
+await relay.claude.spawn(name="Agent1", model=Models.Claude.SONNET, channels=["dev"], task="...")
+await relay.codex.spawn(name="Agent2", model=Models.Codex.GPT_5_3_CODEX, channels=["dev"], task="...")
+await relay.gemini.spawn(name="Agent3", model=Models.Gemini.GEMINI_2_5_PRO, channels=["dev"], task="...")
+
+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']}"),
+)
 
-result = run_yaml(
-    "workflows/release.yaml",
-    RunOptions(workflow="release", on_event=on_event),
+await worker.release(
+    "done",
+    on_start=lambda ctx: print(f"releasing {ctx['name']}"),
+    on_success=lambda ctx: print(f"released {ctx['name']}"),
 )
 ```
 
-Supported event types:
+### Sending Messages
 
-- `run:started`
-- `run:completed`
-- `run:failed`
-- `run:cancelled`
-- `step:started`
-- `step:completed`
-- `step:failed`
-- `step:skipped`
-- `step:retrying`
-- `step:nudged`
-- `step:force-released`
+```python
+human = relay.system()
+await human.send_message(to="Agent1", text="Please start the analysis")
+```
 
-## YAML Workflow Execution
+### Event Hooks
 
 ```python
-from agent_relay import run_yaml, RunOptions
-
-result = run_yaml(
-    "workflows/daytona-migration.yaml",
-    RunOptions(
-        workflow="main",
-        trajectories=False,  # override YAML trajectory config at runtime
-        vars={"target": "staging"},
-    ),
-)
+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
 ```
 
-## Requirements
+### Models
 
-- Python 3.10+
-- `agent-relay` CLI installed (`npm install -g agent-relay`)
+```python
+Models.Claude.OPUS
+Models.Claude.SONNET
+Models.Claude.HAIKU
+
+Models.Codex.GPT_5_2_CODEX
+Models.Codex.GPT_5_3_CODEX
+
+Models.Gemini.GEMINI_2_5_PRO
+Models.Gemini.GEMINI_2_5_FLASH
+```
 
 ## License
 
-Apache-2.0 -- Copyright 2025-2026 Agent Workforce Incorporated
+Apache-2.0

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

@@ -1,21 +1,18 @@
-"""Agent Relay Python SDK."""
+"""Agent Relay Python SDK — re-exports from src/agent_relay/.
 
-from .models import (
-    CLIs,
-    CLIVersions,
-    CLI_REGISTRY,
-    DEFAULT_MODELS,
-    Models,
-    ModelOptions,
-    SwarmPatterns,
-)
+This directory exists for backward compatibility with codegen scripts.
+The real package source lives in src/agent_relay/.
+"""
 
-__all__ = [
-    "CLIs",
-    "CLIVersions",
-    "CLI_REGISTRY",
-    "DEFAULT_MODELS",
-    "Models",
-    "ModelOptions",
-    "SwarmPatterns",
-]
+import importlib.util as _util
+import sys as _sys
+from pathlib import Path as _Path
+
+# Load the real package from src/agent_relay/ and replace this module
+_src_init = _Path(__file__).resolve().parent.parent / "src" / "agent_relay" / "__init__.py"
+_spec = _util.spec_from_file_location("agent_relay", str(_src_init),
+                                       submodule_search_locations=[str(_src_init.parent)])
+assert _spec is not None and _spec.loader is not None, f"Could not load {_src_init}"
+_real = _util.module_from_spec(_spec)
+_sys.modules[__name__] = _real
+_spec.loader.exec_module(_real)

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.0.2"
+version = "3.1.0"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"
@@ -21,3 +21,7 @@ dev = [
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/agent_relay"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"

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

@@ -1,4 +1,20 @@
-"""Agent Relay Python SDK — workflow builder and runner."""
+"""Agent Relay Python SDK — direct spawn/message API and workflow builder."""
+
+# ── Primary API: Direct spawn/message (matches TypeScript SDK) ────────────────
+
+from .relay import AgentRelay, Agent, AgentSpawner, HumanHandle, Message, SpawnOptions
+from .models import Models
+from .client import AgentRelayClient, AgentRelayProtocolError, AgentRelayProcessError
+from .protocol import (
+    PROTOCOL_VERSION,
+    AgentRuntime,
+    AgentSpec,
+    BrokerEvent,
+    ProtocolEnvelope,
+    RestartPolicy as ProtocolRestartPolicy,
+)
+
+# ── Secondary API: Workflow builder (backward compatibility) ──────────────────
 
 from .builder import workflow, WorkflowBuilder, run_yaml
 from .templates import (
@@ -52,6 +68,24 @@ from .types import (
 )
 
 __all__ = [
+    # Primary API
+    "AgentRelay",
+    "Agent",
+    "AgentSpawner",
+    "HumanHandle",
+    "Message",
+    "SpawnOptions",
+    "Models",
+    "AgentRelayClient",
+    "AgentRelayProtocolError",
+    "AgentRelayProcessError",
+    "PROTOCOL_VERSION",
+    "AgentRuntime",
+    "AgentSpec",
+    "BrokerEvent",
+    "ProtocolEnvelope",
+    "ProtocolRestartPolicy",
+    # Workflow builder (backward compat)
     "workflow",
     "WorkflowBuilder",
     "run_yaml",