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

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agent_relay_sdk-11.7.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl (7.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agent_relay_sdk-11.7.2-py3-none-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

agent_relay_sdk-11.7.2-py3-none-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.7.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 0fd87b428a0abd7b8164a098b526426ed31aae37ad6faa5e93e9412daf01240b
MD5 8a6f2db0a48478fbc1db7fb9ad05d87d
BLAKE2b-256 076b9c9707210413334d65480e27ab7fa330d81044d940f908e06df140d4d561

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.7.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 5f399fd59271b3d184d9e7291e307d3559901672fe0cad95ad0e8d493f616238
MD5 cd5eec5e933dc46856b76450507d353c
BLAKE2b-256 cd0bf58cbd7b5352963035a543d12b51a71741bbd5d281fba80edd465913681b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.7.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1519f47feffe8fbaffa36c26854b371d89918f6fff8f9221545b813f3b91d31b
MD5 7fe76c2ccbadd0f468fbc4ad62a99ba9
BLAKE2b-256 8031fa79c17074aacfbaad434733fbfa550d09a6671ac572effd4fded8be160c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.7.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f2507621acd61e2b503a498b685020e56c27dd5b441b18544d4315d2a2fb5cba
MD5 02f23419ebc3f136b68c9cb0269f9233
BLAKE2b-256 9fd936a765a0b7b946b84afd1d2d1204d5daf8002861c4e5e3663751a1c3ef12

See more details on using hashes here.

Provenance

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

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

This release

11.7.2 This release

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