using-agent-relay
在实时协调多个 AI 代理时使用 - 通过 tmux 包装器(延迟低于 5 毫秒)或基于文件的团队收件箱提供代理间消息传递,用于异步工作流程。
name: using-agent-relay description: Use when coordinating multiple AI agents in real-time - provides inter-agent messaging via Rust PTY wrapper with file-based protocol and reliability features
Using Agent Relay
Real-time agent-to-agent messaging via file-based protocol.
Reliability Features
The relay system includes automatic reliability improvements:
Escalating retry - If you don't acknowledge a message, it will be re-sent with increasing urgency:
- First attempt:
Relay message from Alice [abc123]: ... - Second attempt:
[RETRY] Relay message from Alice [abc123]: ... - Third+ attempt:
[URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: ...
- First attempt:
Unread indicator - During long tasks, you'll see pending message counts:
📬 2 unread messages (from: Alice, Bob)
Always acknowledge messages to prevent retry escalation.
Sending Messages
Write a file to your outbox, then output the trigger:
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/msg << 'EOF'
TO: AgentName
Your message here.
EOF
Then output: ->relay-file:msg
Broadcast to All Agents
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/broadcast << 'EOF'
TO: *
Hello everyone!
EOF
Then: ->relay-file:broadcast
With Thread
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/reply << 'EOF'
TO: AgentName
THREAD: issue-123
Response in thread context.
EOF
Then: ->relay-file:reply
Message Format
TO: Target
THREAD: optional-thread
Message body (everything after blank line)
| TO Value | Behavior |
|---|---|
AgentName |
Direct message |
* |
Broadcast to all |
#channel |
Channel message |
Communication Protocol
ACK immediately - When you receive a task, acknowledge it before starting work:
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/ack << 'EOF'
TO: Sender
ACK: Brief description of task received
EOF
Then: ->relay-file:ack
Report completion - When done, send a completion message:
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/done << 'EOF'
TO: Sender
DONE: Brief summary of what was completed
EOF
Then: ->relay-file:done
Priority handling - If you see [RETRY] or [URGENT] tags, respond immediately.
Receiving Messages
Messages appear as:
Relay message from Alice [abc123]: Content here
Messages with retry escalation:
[RETRY] Relay message from Alice [abc123]: Did you receive my message?
[URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: Please respond!
Channel Routing (Important!)
Messages from #general (broadcast channel) include a [#general] indicator:
Relay message from Alice [abc123] [#general]: Hello everyone!
When you see [#general]: Reply to * (broadcast), NOT to the sender directly.
Spawning & Releasing Agents
Spawn a Worker
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/spawn << 'EOF'
KIND: spawn
NAME: WorkerName
CLI: claude
Task description here.
Can be multiple lines.
EOF
Then: ->relay-file:spawn
Release a Worker
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/release << 'EOF'
KIND: release
NAME: WorkerName
EOF
Then: ->relay-file:release
Headers Reference
| Header | Required | Description |
|---|---|---|
| TO | Yes (messages) | Target agent/channel |
| KIND | No | message (default), spawn, release |
| NAME | Yes (spawn/release) | Agent name |
| CLI | Yes (spawn) | CLI to use |
| THREAD | No | Thread identifier |
Status Updates
Send status updates to your lead, NOT broadcast:
# Correct - status to lead only
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/status << 'EOF'
TO: Lead
STATUS: Working on auth module
EOF
Then: ->relay-file:status
CLI Commands
agent-relay status # Check daemon status
agent-relay agents # List active agents
agent-relay agents:logs <name> # View agent output
agent-relay agents:kill <name> # Kill a spawned agent
agent-relay read <id> # Read truncated message
Synchronous Messaging (Planned)
For turn-based coordination where you need to wait for a response:
Blocking Messages with [await]
Add AWAIT header to block until response:
cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/turn << 'EOF'
TO: Worker
AWAIT: 60s
Your turn. Play a card.
EOF
Then: ->relay-file:turn
When you receive a message marked [awaiting], the sender is waiting for your response:
Relay message from Coordinator [abc123] [awaiting]: Your turn. Play a card.
Note: AWAIT header is coming in a future release. Currently all messages are fire-and-forget.
Troubleshooting
agent-relay status # Check daemon
agent-relay agents # List connected agents
ls -la /tmp/agent-relay.sock # Verify socket
ls -la /tmp/relay-outbox/ # Check outbox directories
Common Mistakes
| Mistake | Fix |
|---|---|
| Using bash to send messages | Write file to outbox, then output ->relay-file:ID |
| Messages not sending | Check agent-relay status and outbox directory exists |
| Incomplete message content | agent-relay read <id> for full text |
| Missing trigger | Must output ->relay-file:<filename> after writing file |
| Wrong outbox path | Use /tmp/relay-outbox/$AGENT_RELAY_NAME/ |
Legacy Format (Deprecated)
The inline ->relay:Target <<<message>>> format still works but file-based is preferred for reliability.