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

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agent_relay_sdk-11.4.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl (7.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agent_relay_sdk-11.4.2-py3-none-macosx_11_0_arm64.whl (5.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

agent_relay_sdk-11.4.2-py3-none-macosx_10_12_x86_64.whl (6.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.4.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 0f3bba779b686b3935f3ea19c3e62f7d51e5ccb4ef1832682fe5b0e2d7d8b29c
MD5 18a219e16f6bf866f5c38a4e9526f095
BLAKE2b-256 a2f9b8214cf3c800c49c3577cd90c25378842330efe1f6a51968ba4b136a5782

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.4.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 b1805a2151f40e1e18d3fe73e59d64b7a577d0dae88f2462c316250522e11ec5
MD5 bd118118539c60d56716ca4184c6ae96
BLAKE2b-256 a331a4e9518126db947c3b9822634a191dd74474dcf5a65dfbbfcf1de0de8152

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.4.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4f259d057537fa3a025b2329379f50764538d5b84d5293d80e0955ea9d8d272d
MD5 bda68d1e3a4d932a23d9f9c829967e0a
BLAKE2b-256 0ea9580692c92dfd1b7c6f5ceeb75c1326f9d5cd4fd563a47e92644bd803dee7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_relay_sdk-11.4.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e8da87010a06652721e894481de5e03ac80b5556266b7fefa6ddfa94bb98f30c
MD5 0546b5db96510114fc12fc784f7245fb
BLAKE2b-256 3e142c0ac588f0c05cbcb7cd7d4b7d4176120f851a67bf9f97241524e46cad4e

See more details on using hashes here.

Provenance

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

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

This release

11.4.2 This release

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