agentrelay

---

name: agentrelay description: Reliable agent-to-agent communication protocol for transferring large payloads via shared files with pointer references and secret code verification. Triggered by explicit 'AgentRelay:' prefix in messages. license: MIT metadata: {"openclaw":{"triggerPatterns":["AgentRelay:","Please use AgentRelay skill to handle","Use AgentRelay"],"emoji":"📨"}}

---

AgentRelay 📨

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

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 [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 [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

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