# Send Agentrelay to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "agentrelay",
    "name": "Agentrelay",
    "source": "tencent",
    "type": "skill",
    "category": "通讯协作",
    "sourceUrl": "https://clawhub.ai/extraterrest/agentrelay",
    "canonicalUrl": "https://clawhub.ai/extraterrest/agentrelay",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/agentrelay",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agentrelay",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "RELEASE_NOTES.md",
      "SKILL.md",
      "SKILL.py",
      "__init__.py",
      "clawhub.json"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "agentrelay",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-29T03:21:38.907Z",
      "expiresAt": "2026-05-06T03:21:38.907Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agentrelay",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agentrelay",
        "contentDisposition": "attachment; filename=\"agentrelay-1.1.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "agentrelay"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/agentrelay"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/agentrelay",
    "downloadUrl": "https://openagent3.xyz/downloads/agentrelay",
    "agentUrl": "https://openagent3.xyz/skills/agentrelay/agent",
    "manifestUrl": "https://openagent3.xyz/skills/agentrelay/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/agentrelay/agent.md"
  }
}
```
## Documentation

### 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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: extraterrest
- Version: 1.1.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-29T03:21:38.907Z
- Expires at: 2026-05-06T03:21:38.907Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/agentrelay)
- [Send to Agent page](https://openagent3.xyz/skills/agentrelay/agent)
- [JSON manifest](https://openagent3.xyz/skills/agentrelay/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/agentrelay/agent.md)
- [Download page](https://openagent3.xyz/downloads/agentrelay)