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",
    # wait (default) queues for the next safe idle boundary and can remain
    # unread while the recipient is busy. steer requests immediate injection
    # and may interrupt active work. Send success confirms enqueue only.
    mode="wait",
)

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.10.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (6.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agent_relay_sdk-11.10.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl (7.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agent_relay_sdk-11.10.2-py3-none-macosx_11_0_arm64.whl (6.2 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

agent_relay_sdk-11.10.2-py3-none-macosx_10_12_x86_64.whl (6.7 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.10.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 6dedaa6f721caa649fe7fcd47363eca076b174299508273c4dc2c35ea9ab2ea3
MD5 85c0f48d2b9c3c6909a6e11f5b65c950
BLAKE2b-256 a7e40d929dc618fea9a39d617345c176d7346c50d8314365b629709190a7e166

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.10.2-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.10.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.10.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 788daffe6fe7f9cfe6c5917e76a90795bc3ae7445eefdf112f5f0514a42c729a
MD5 2c793725daa13d7c872e8a187e2bb1ba
BLAKE2b-256 1d9b4d8e00f303b6f3fdf01ec24449c556852ec543eb75064697d21a9629a75f

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.10.2-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.10.2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.10.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2eb1851fb870a4ef83abdabaceb5743c65f01a7a8712ad5772795b2d5eedde0f
MD5 ef991bdc8e320013f760cf7a5b402e56
BLAKE2b-256 2a4f22950c52979291296d981a59f2881077293b47646771c9f19091be6877e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.10.2-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.10.2-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.10.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 d56cdb210139203f9aff5173c3f74c6259231e2b073816f3a10ceb7915db4ac9
MD5 91217594cd6b6c71ddaed24a074defbb
BLAKE2b-256 12701494cb7ad6f5c8b75fcaa8ee21f2f2933b3923b4b71f8ab59d48f90dc44a

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_relay_sdk-11.10.2-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

This release

11.10.2 This release

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

11.5.5

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