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,r1_r,s/r1_r.json,,
```

Or

```
📨 AgentRelay Protocol Message

Please use AgentRelay skill to handle:
- Message Type: REQ
- Event ID: r1_r  
- File Pointer: s/r1_r.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**
```bash
python3 {baseDir}/run_relay.py receive "REQ,r1_r,s/r1_r.json,,"
```

Example output:
```json
{
  "type": "REQ",
  "event_id": "r1_r",
  "content": {"task": "write_poem", "sender_color": "red"},
  "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**
```bash
python3 {baseDir}/run_relay.py complete r1_r "Task completed" "agent:red:red"
```

**Step 4: Send CMP Confirmation**
```bash
# generate CMP message (done automatically by run_relay.py complete)
# Output: CMP,r1_r,,,ABC123
# Then send via sessions_send
sessions_send(target='agent:red:red', message='CMP,r1_r,,,ABC123')
```

---

## 📚 Commands

### `receive <csv_message>`

Parse AgentRelay CSV message and read shared file content.

**Parameters**:
- `csv_message`: CSV format message (without `AgentRelay:` prefix)

**Example**:
```bash
python3 {baseDir}/run_relay.py receive "REQ,r1_r,s/r1_r.json,,"
```

**Output** (JSON):
```json
{
  "type": "REQ",
  "event_id": "r1_r",
  "ptr": "s/r1_r.json",
  "content": {...},
  "secret": "ABC123"
}
```

---

### `update <event_i...

# AgentRelay 📨

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

---

## 🎯 Core Value

When your agents need to send messages **larger than 30 characters**, `sessions_send` tends to timeout. AgentRelay provides the solution:

| Traditional Approach | AgentRelay Approach |
|---------------------|---------------------|
| ❌ Send large text directly → ⏰ Timeout | ✅ Write to file + send short pointer → Success |
| ❌ No verification if received | ✅ Secret Code mechanism ensures delivery |
| ❌ No audit trail | ✅ Complete transaction logs (4 entries/event) |

---

## 🚀 Quick Start

### 1️⃣ Install

```bash
clawhub install agentrelay
```

### 2️⃣ Send Message

```python
from agentrelay import AgentRelayTool

# Prepare data
content = {"task": "write_poem", "theme": "spring"}

# Write to shared file and get CSV message
result = AgentRelayTool.send("yellow", "REQ", "hop1", content)

# Send to target agent
sessions_send(
    target='agent:yellow:yellow',
    message=f"AgentRelay: {result['csv_message']}"
)
```

### 3️⃣ Receive Message

```bash
# Use unified script to parse
python3 scripts/run_relay.py receive "REQ,hop1,s/hop1.json,,"
```

Output:
```json
{
  "type": "REQ",
  "event_id": "hop1",
  "content": {"task": "write_poem", ...},
  "secret": "ABC123"
}
```

### 4️⃣ Complete Task and Reply

```bash
python3 scripts/run_relay.py complete hop1 "Task completed" "agent:red:red"
```

Output:
```
✅ Updated hop1
✅ CMP: CMP,hop1,,,ABC123
```

---

## 🔄 Complete Flow

```
Sender                          Receiver
  |                              |
  |-- 1. REQ (with file ptr) --->|
  |                              |-- receive()
  |                              |-- 📍 LOG #1: REQ/RECEIVED
  |                              |-- 📍 LOG #2: ACK/ACKNOWLEDGED
  |                              |
  |<-- 2. ACK (implicit confirm)-|  
  |                              |
  |...