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.6.1-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.6.1-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.6.1-py3-none-macosx_11_0_arm64.whl (5.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

agent_relay_sdk-11.6.1-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.6.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for agent_relay_sdk-11.6.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 382b3077cf51612a90edd4cdd3ca635ea8babc41fa3f7e915b3dba3a76ed95f5
MD5 b2c6cac5e53d58bf04e0e3ac03290997
BLAKE2b-256 82859a0a9e2b5fce8341585e9bd90d749f638d477f3400ccb3a48aa39bb56727

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.6.1-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 76e264a402fbf719b587d9bde07ca9d19a1187d5dfc8754f2a8aabd71920df6d
MD5 21d6cf675632274b05829b391d58e77c
BLAKE2b-256 aac31bfa2e1728b17785abde0a8476ab8cc169b1dba6db519101796b091c0bba

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.6.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4894c05c9560322e88f5de534434fb8245c08233a021345abc3fb8bf45b50a60
MD5 e157a883c0dbdbfd9d085e6205689837
BLAKE2b-256 2b7e99549930ae5b3e4f39d52a7c904c096be636f16a892260de35e4a71d55b2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.6.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0bafc69a7149d05f6d88622fcfb0df0bda7edb636c913dc764ae75d9a5fdf7b8
MD5 a27603288b66d276979e59671382437c
BLAKE2b-256 47732ae3bc5888065ffc4f01bf22d7f7fa154f2056f16c5aa4943aba0a57f4e8

See more details on using hashes here.

Provenance

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

This release

11.6.1 This release

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