using-agent-relay

在实时协调多个 AI 代理时使用 - 通过 tmux 包装器(延迟低于 5 毫秒)或基于文件的团队收件箱提供代理间消息传递,用于异步工作流程。

📖 中文导读:在实时协调多个 AI 代理时使用 - 通过 tmux 包装器(延迟低于 5 毫秒)或基于文件的团队收件箱提供代理间消息传递,用于异步工作流程。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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]: ...
  • 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.