Agent Relay Python SDK

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

pip install agent-relay-sdk

Communicate

pip install "agent-relay-sdk[communicate]"

The SDK ships per-platform wheels with the broker binary embedded. pip install is the network boundary — no downloads happen at import or 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+

  • A supported platform (the wheel ships a prebuilt agent-relay-broker):

    Platform Wheel tag
    macOS Apple Silicon macosx_11_0_arm64
    macOS Intel macosx_10_12_x86_64
    Linux x86_64 manylinux_2_17_x86_64.manylinux2014_x86_64
    Linux aarch64 manylinux_2_17_aarch64.manylinux2014_aarch64

    Linux binaries are built statically against musl, so they install on glibc and musl distros (Debian, Ubuntu, RHEL, Alpine, …). Other platforms (Windows, FreeBSD, linux-armv7) are unsupported — pip install will fail with "no matching distribution found".

    To override the bundled binary (e.g. for local development against a custom broker build), set BROKER_BINARY_PATH or AGENT_RELAY_BIN to an absolute path.

Development

For an editable install (pip install -e packages/sdk-py), build the broker locally and copy it into the wheel tree:

cargo build --release --bin agent-relay-broker
packages/sdk-py/scripts/sync-broker-dev.sh

The destination (src/agent_relay/bin/) is gitignored. Alternatively, set BROKER_BINARY_PATH=$(pwd)/target/release/agent-relay-broker in your shell.

Choose a Mode

Orchestrate

Use AgentRelay when you want Python to spawn agents, wait for readiness, route messages, and shut everything down.

import asyncio
from agent_relay import AgentRelay, Models

async def main():
    relay = AgentRelay(channels=["dev"])
    relay.on_message_received = lambda msg: print(f"[{msg.from_name}]: {msg.text}")

    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 suggestions",
    )

    await asyncio.gather(
        relay.wait_for_agent_ready("Reviewer"),
        relay.wait_for_agent_ready("Builder"),
    )
    await relay.shutdown()

asyncio.run(main())

Communicate

Use Relay + on_relay() when your framework already owns the runtime and you only want Relaycast messaging.

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 Orchestrate entry point. Pass channels to subscribe to message channels.

relay = AgentRelay(channels=["dev", "planning"])

Spawning Agents

Use runtime-specific spawners:

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"],
    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']}"),
)

await worker.release(
    "done",
    on_start=lambda ctx: print(f"releasing {ctx['name']}"),
    on_success=lambda ctx: print(f"released {ctx['name']}"),
)

Relay

The Communicate-mode client. Configure it directly or via RELAY_WORKSPACE, RELAY_API_KEY, and RELAY_BASE_URL.

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()

human = relay.system()
await human.send_message(
    to="Agent1",
    text="Please start the analysis",
    mode="wait",   # or "steer"
)

on_relay()

Wrap a framework-owned agent or options object and keep the runtime you already use.

from agent_relay import Relay, on_relay

relay = Relay("Researcher")
wrapped = on_relay(framework_agent_or_options, relay)

Event Hooks

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

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

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (12.1.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for khaliqgant from gravatar.com khaliqgant

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

agno claude-sdk communicate crewai dev google-adk node openai-agents

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

agent_relay_sdk-11.5.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (6.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agent_relay_sdk-11.5.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl (7.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agent_relay_sdk-11.5.5-py3-none-macosx_11_0_arm64.whl (5.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

agent_relay_sdk-11.5.5-py3-none-macosx_10_12_x86_64.whl (6.4 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file agent_relay_sdk-11.5.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.5.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 f9cfc2f09f086f58f5130731384fe10d9a1f9f215502bfaa1aa73a4796a956a0
MD5 f0bc83106d984d367179377b387f7b26
BLAKE2b-256 f530fc0a636bcab142553c4640430bd50c29ba3b489a76949a85f1640d4b786e

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.5.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl:

Publisher: publish.yml on AgentWorkforce/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_relay_sdk-11.5.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.5.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 03994cac53ac5cca6ffc7ab8a89d0a8a609de91eb3972b8a460df318c5b61617
MD5 8287bdea9f86a90b2c7df9a9e0f02c92
BLAKE2b-256 a16137ca1ecf4c4fa0b285049fa9a33747ac5493c353ba2471244072d8927362

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.5.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl:

Publisher: publish.yml on AgentWorkforce/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_relay_sdk-11.5.5-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.5.5-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 495d8c6a92b161b1ca194328590b7f3dff891d43a6ebfdc8229713a96bf149e0
MD5 3d8a485990bc40778f5aacfb81a19865
BLAKE2b-256 326e244972a98790ea2bb5f640c6ed723db371440f7a5b5cbef534c34bdec118

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.5.5-py3-none-macosx_11_0_arm64.whl:

Publisher: publish.yml on AgentWorkforce/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_relay_sdk-11.5.5-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.5.5-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 86cbbe5dc4eec3aa21febca32852850e7f2ed1984e4870480b075a943b248daf
MD5 0d4c1704077f083084a1404d0799f95b
BLAKE2b-256 bd3d6d6c475a6d9a61f3ea4398d8789ecf5a98b639e755cc8eeba97b7b4801c7

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.5.5-py3-none-macosx_10_12_x86_64.whl:

Publisher: publish.yml on AgentWorkforce/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

12.1.0

4 files

12.0.0

4 files

11.10.4

4 files

11.10.3

4 files

11.10.2

4 files

11.10.1

4 files

11.9.0

4 files

11.8.7

4 files

11.8.6

4 files

11.8.5

4 files

11.8.4

4 files

11.8.3

4 files

11.8.2

4 files

11.8.1

4 files

11.8.0

4 files

11.7.2

4 files

11.7.1

4 files

11.7.0

4 files

11.6.10

4 files

11.6.9

4 files

11.6.7

4 files

11.6.6

4 files

11.6.5

4 files

11.6.4

4 files

11.6.3

4 files

11.6.2

4 files

11.6.1

4 files

11.6.0

4 files

11.5.6

4 files

This release

11.5.5 This release

4 files

11.5.4

4 files

11.5.3

4 files

11.5.2

4 files

11.5.1

4 files

11.5.0

4 files

11.4.3

4 files

11.4.2

4 files

11.4.1

4 files

11.4.0

4 files

11.3.1

4 files

11.3.0

4 files

11.2.0

4 files

11.1.1

4 files

11.1.0

4 files

11.0.2

4 files

11.0.1

4 files

11.0.0

4 files

10.6.7

4 files

10.6.6

4 files

10.6.5

4 files

10.6.4

4 files

10.6.3

4 files

10.6.2

4 files

10.6.1

4 files

10.6.0

4 files

10.5.0

4 files

10.4.0

4 files

10.3.0

4 files

10.2.0

4 files

10.1.0

4 files

10.0.0

4 files

9.2.4

4 files

9.2.3

4 files

9.2.2

4 files

9.2.1

4 files

9.2.0

4 files

9.1.10

4 files

9.1.9

4 files

9.1.8

4 files

9.1.7

4 files

9.1.6

4 files

9.1.5

4 files

9.1.4

4 files

9.1.3

4 files

9.1.2

4 files

9.1.1

4 files

9.1.0

4 files

9.0.2

4 files

9.0.1

4 files

9.0.0

4 files

8.9.2

4 files

8.9.1

4 files

8.9.0

4 files

8.8.5

4 files

8.8.4

4 files

8.8.3

4 files

8.8.2

4 files

8.8.1

4 files

8.8.0

4 files

8.7.2

4 files

8.7.1

4 files

8.7.0

4 files

8.6.0

4 files

8.5.0

4 files

8.4.0

4 files

8.3.7

4 files

8.3.6

4 files

8.3.5

4 files

8.3.4

4 files

8.3.3

4 files

8.3.2

4 files

8.3.1

4 files

8.3.0

4 files

8.2.0

4 files

8.1.2

4 files

8.1.1

4 files

8.1.0

4 files

8.0.5

4 files

8.0.4

4 files

8.0.3

4 files

8.0.2

4 files

8.0.1

4 files

8.0.0

4 files

7.1.1

4 files

7.1.0

4 files

7.0.1

4 files

7.0.0

4 files

6.3.6

4 files

6.3.5

4 files

6.3.4

4 files

6.3.3

4 files

6.3.2

4 files

6.3.1

4 files

6.3.0

4 files

6.2.8

4 files

6.2.7

4 files

6.2.6

4 files

6.2.5

4 files

6.2.4

4 files

6.2.3

4 files

6.2.2

4 files

6.2.1

4 files

6.2.0

4 files

6.0.22

4 files

6.0.21

4 files

6.0.20

4 files

6.0.19

4 files

6.0.18

4 files

6.0.17

4 files

6.0.16

4 files

6.0.15

4 files

6.0.14

4 files

6.0.13

4 files

6.0.12

4 files

6.0.11

4 files

6.0.10

4 files

6.0.9

4 files

6.0.8

4 files

6.0.7

4 files

6.0.6

4 files

6.0.5

4 files

6.0.4

4 files

6.0.3

4 files

6.0.2

4 files

6.0.1

4 files

6.0.0

4 files

5.0.0

4 files

4.0.40

2 files

4.0.39

2 files

4.0.38

2 files

4.0.37

2 files

4.0.36

2 files

4.0.35

2 files

4.0.34

2 files

4.0.33

2 files

4.0.32

2 files

4.0.31

2 files

4.0.30

2 files

4.0.29

2 files

4.0.28

2 files

4.0.27

2 files

4.0.26

2 files

4.0.25

2 files

4.0.24

2 files

4.0.23

2 files

4.0.22

2 files

4.0.21

2 files

4.0.20

2 files

4.0.19

2 files

4.0.18

2 files

4.0.17

2 files

4.0.16

2 files

4.0.15

2 files

4.0.14

2 files

4.0.13

2 files

4.0.12

2 files

4.0.11

2 files

4.0.10

2 files

4.0.9

2 files

4.0.8

2 files

4.0.7

2 files

4.0.6

2 files

4.0.5

2 files

4.0.4

2 files

4.0.3

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

3.2.22

2 files

3.2.21

2 files

3.2.20

2 files

3.2.19

2 files

3.2.18

2 files

3.2.17

2 files

3.2.16

2 files

3.2.15

2 files

3.2.14

2 files

3.2.13

2 files

3.2.12

2 files

3.2.11

2 files

3.2.10

2 files

3.2.9

2 files

3.2.8

2 files

3.2.7

2 files

3.2.6

2 files

3.2.5

2 files

3.2.4

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.23

2 files

3.1.22

2 files

3.1.21

2 files

3.1.20

2 files

3.1.19

2 files

3.1.18

2 files

3.1.17

2 files

3.1.16

2 files

3.1.15

2 files

3.1.14

2 files

3.1.13

2 files

3.1.12

2 files

3.1.11

2 files

3.1.10

2 files

3.1.9

2 files

3.1.8

2 files

3.1.7

2 files

3.1.6

2 files

3.1.5

2 files

3.1.4

2 files

3.1.3

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

1 file

3.0.2

2 files

2.4.7

2 files

2.4.6

2 files

2.4.5

2 files

2.4.4

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.16

2 files

2.3.15

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page