Agentrelay

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!

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')

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 }

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")

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

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

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"

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