agentrelay

Reliable agent-to-agent communication protocol for transferring large payloads via shared files with pointer references and secret code verification. Trigger...

Reliable Agent-to-Agent Communication Protocol — Solves sessions_send timeout issues for large payloads using shared files + short message pointers.

🎯 When to Use This Skill

When you see messages like the following, immediately use this Skill to handle:

Please use AgentRelay skill to handle this message:
REQ,event_001,s/event_001.json,,

Or

📨 AgentRelay Protocol Message

Please use AgentRelay skill to handle:
- Message Type: REQ
- Event ID: event_001
- File Pointer: s/event_001.json

Key Trigger Phrases:

• "use AgentRelay skill to handle"
• "AgentRelay protocol message"
• "Use AgentRelay"

When you see these keywords, immediately execute the Commands below!

🚀 Quick Start

Standard Flow After Receiving AgentRelay Message

Step 1: Parse Message

python3 {baseDir}/run_relay.py receive "REQ,event_001,s/event_001.json,,"

Example output:

{
  "type": "REQ",
  "event_id": "event_001",
  "content": {
    "task": "write_poem",
    "sender_agent": "agent:sender:main",
    "receiver_agent": "agent:worker:main"
  },
  "secret": "ABC123"
}

Step 2: Understand Task and Execute

Check the content field to understand what needs to be done (e.g., write poem, analyze data, generate report).

Step 3: Update Result

python3 {baseDir}/run_relay.py complete event_001 "Task completed" "agent:sender:main"

Step 4: Send CMP Confirmation

# generate CMP message (done automatically by run_relay.py complete)
# Output: CMP,event_001,,,ABC123
# Then send via sessions_send
sessions_send(target='agent:sender:main', message='CMP,event_001,,,ABC123')

---

📚 Commands

receive <csv_message>

Parse AgentRelay CSV message and read shared file content. Accepts either bare CSV or a full message with the AgentRelay: prefix.

Parameters:

• csv_message: CSV format message (without AgentRelay: prefix)

Example:

python3 {baseDir}/run_relay.py receive "REQ,event_001,s/event_001.json,,"

Output (JSON):

{
  "type": "REQ",
  "event_id": "event_001",
  "ptr": "s/event_001.json",
  "content": {...},
  "secret": "ABC123"
}

---

update <event_id> <json_updates> [next_event_id]

Update shared file content.

Parameters:

• event_id: Event ID
• json_updates: JSON format updates (merged into payload.content)

Example:

python3 {baseDir}/run_relay.py update event_001 '{"status":"completed","result":"done"}'

Output:

{"status":"ok","file":"/path/to/event_001.json","ptr":"s/event_001.json"}

---

cmp <event_id> [secret]

Generate CMP confirmation message.

Parameters:

• event_id: Event ID
• secret: Secret Code read from file

Example:

python3 {baseDir}/run_relay.py cmp event_001 ABC123

Output:

{
  "status": "ok",
  "cmp_message": "CMP,event_001,,,ABC123",
  "instruction": "Call sessions_send with message='CMP,event_001,,,ABC123'"
}

---

verify <cmp_message>

Verify that a received CMP message matches the secret stored in the event file.

Example:

python3 {baseDir}/run_relay.py verify "CMP,event_001,,,ABC123"

Output:

{
  "status": "ok",
  "event_id": "event_001",
  "verified": true
}

---

🔄 Complete Communication Flow

Sender Agent

# 1. Prepare data
content = {
    "task": "write_poem",
    "sender_agent": "agent:sender:main",
    "receiver_agent": "agent:worker:main"
}

# 2. Write to shared file
from agentrelay import agentrelay_send
result = agentrelay_send("agent:worker:main", "REQ", "event_001", content)

# 3. Send message with prefix
message = f"AgentRelay: {result['csv_message']}"
sessions_send(target='agent:worker:main', message=message)

Receiver Agent

# 1. Receive message: AgentRelay: REQ,event_001,s/event_001.json,,

# 2. Parse message
python3 {baseDir}/run_relay.py receive "REQ,event_001,s/event_001.json,,"
# → Get content and secret

# 3. Understand task, call LLM to execute
# (This is your LLM capability)

# 4. Update result
python3 {baseDir}/run_relay.py update event_001 '{"status":"completed"}'

# 5. Send CMP
CMP_OUTPUT=$(python3 {baseDir}/run_relay.py cmp event_001 SECRET)
CMP_MSG=$(echo "$CMP_OUTPUT" | jq -r '.cmp_message')
sessions_send(target='agent:sender:main', message="$CMP_MSG")

---

📊 Message Format Details

CSV Format

TYPE,ID,PTR,,DATA

Field Descriptions:

• TYPE: Message type (REQ | CMP)
• ID: Event ID (unique identifier)
• PTR: File pointer (e.g., s/event_id.json)
• RESERVED: Reserved field (leave empty)
• DATA: Additional data (Secret Code for CMP)

Examples:

REQ,event_001,s/event_001.json,,  # Request
CMP,event_001,,,ABC123            # Completion confirmation

Full Message (with prefix)

AgentRelay: REQ,event_001,s/event_001.json,,

Why need prefix?

• ✅ Clearly identifies this as AgentRelay protocol message
• ✅ LLM immediately knows to call AgentRelay Skill when seeing it
• ✅ Avoids confusion with other messages

---

🛡️ Security Mechanisms

1. Secret Code Verification

• Sender generates 6-character random code (e.g., ABC123)
• Secret is written to file
• Receiver must return the same Secret when sending CMP
• Sender verifies Secret matches, ensuring receiver actually read the file

2. Burn-on-read (Optional)

When burn_on_read=true is set in meta or payload.content, the file is automatically deleted after reading to protect sensitive data.

📁 Data Storage

• Shared Files: ~/.openclaw/data/agentrelay/storage/*.json
• Transaction Logs: ~/.openclaw/data/agentrelay/logs/transactions_*.jsonl
• Registry: ~/.openclaw/data/agentrelay/registry.json

---

🧪 Testing and Examples

Smoke Test

python3 {baseDir}/smoke_test.py

Pytest Regression Suite

pytest {baseDir}/test_agentrelay.py

Cleanup Expired Events

python3 {baseDir}/cleanup_relay.py

Verify a CMP

python3 {baseDir}/run_relay.py verify "CMP,r1_r,,,ABC123"

---

❓ FAQ

Q: Why use AgentRelay instead of direct sessions_send?

A: sessions_send tends to timeout when transmitting messages larger than 30 characters. AgentRelay uses shared files + short pointers (less than 30 characters) to transmit arbitrarily large data.

Q: What is Secret Code for?

A: Secret Code is a 6-character random code used to verify the receiver actually read the file. Receiver must return the correct Secret in CMP, and sender can verify it with verify.

Q: How long are files retained?

A: Files are retained for 24 hours by default. You can adjust this with ttl_hours, enable burn_on_read to delete immediately after reading, and run cleanup_relay.py to sweep expired files and old registry entries.

---

📖 More Documentation

• README.md - Project overview
• RELEASE_NOTES.md - Release notes

---

Version: v1.1.0 Last Updated: 2026-02-28
Author: AgentRelay Team
Maintainer: AgentRelay Team