# Agent Loop Messaging

> agent-loop を使ったエージェント間の非同期メッセージングスキル。「別エージェントにタスクを委譲して」「worker にメッセージを送って」「エージェント間でやり取りして」「agent-loop msg を使って」「inbox にメッセージを投函して」などで発動する。複数の agent-loop インスタンスを連携させたい場合に優先して選択する。

- Skill: `ynitto/agent-loop-messaging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ynitto/agent-loop-messaging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/agent-loop-messaging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/agent-loop-messaging

---


# agent-loop-messaging — エージェント間非同期メッセージング

agent-loop の **`msg` サブコマンド** と **InboxWatcher** を使い、複数の agent-loop エージェントが非同期にメッセージを交換する。

---

## 前提条件

- `agent-loop` がインストールされ PATH に存在すること（`agent-loop --version` で確認）
- 送信先エージェントが `agent-loop` を `agent_name` 設定付きで起動済みであること
- ファイルベースなので **同一ホスト上** の通信に限定（リモートは今後対応予定）

---

## アーキテクチャ

```
送信側エージェント          受信側エージェント
┌──────────────────┐       ┌─────────────────────────────┐
│ agent-loop msg    │       │ agent-loop (daemon)           │
│ --to worker1     │       │   agent_name: worker1        │
│ "タスク内容"      │ ──▶  │   InboxWatcher               │
│                  │       │     ↓ ポーリング (5秒ごと)   │
└──────────────────┘       │     ↓ メッセージ受信         │
                           │   kiro-cli (prompt)          │
                           └─────────────────────────────┘
```

メッセージはファイル (`~/.kiro/agents/<agent>/inbox/*.json`) で受け渡される。

---

## 基本ワークフロー

### Step 1: 受信側の設定（agent-loop.yaml）

受信するエージェントの `agent-loop.yaml` に `agent_name` を設定する。

```yaml
# agent-loop.yaml
agent_name: worker1           # このエージェントの識別名
inbox_poll_seconds: 5         # 受信ボックス確認間隔（秒）

kiro_options:
  trust_all_tools: true

prompts:
  # 定期プロンプトも通常通り設定可能
  - name: "定期ヘルスチェック"
    prompt: "現在のタスク状況を要約してください"
    interval_minutes: 60
    enabled: true
```

agent-loop を起動すると InboxWatcher が自動起動する：

```bash
agent-loop   # agent_name が設定されていれば InboxWatcher も起動
```

### Step 2: メッセージを送信する

```bash
# 基本的な送信
agent-loop msg --to worker1 "feature_x.py を実装してください"

# 送信元名と件名を付ける
agent-loop msg --to worker1 --from orchestrator --subject "実装依頼" "feature_x.py を実装してください"

# ファイルで詳細なタスクを渡す（ファイルパスを指定すると内容を読み込む）
agent-loop msg --to worker1 --from orchestrator task.md

# 会話 ID で複数メッセージをまとめる
agent-loop msg --to worker1 --correlation-id "conv-001" "Step 1: 設計してください"
agent-loop msg --to worker1 --correlation-id "conv-001" "Step 2: 実装してください"
```

### Step 3: 受信側での処理

InboxWatcher が受信したメッセージを以下のプロンプト形式で kiro-cli に送信する：

```
[エージェント orchestrator からのメッセージ]
件名: 実装依頼

feature_x.py を実装してください。
仕様: ...

---
返信する場合: agent-loop msg --to orchestrator --reply-to "<msg_id>" "返答内容"
```

### Step 4: 返信する

受信エージェントが kiro-cli から返信を送る場合：

```bash
# 受信プロンプトに含まれる返信コマンドをそのまま実行
agent-loop msg --to orchestrator --reply-to "<msg_id>" "実装が完了しました"
```

---

## サブコマンドリファレンス

### `agent-loop msg` — メッセージ送信

```
agent-loop msg --to AGENT [--from AGENT] [--subject TEXT] [--reply-to MSG_ID] [--correlation-id ID] BODY
```

| オプション | 短縮 | 説明 |
|-----------|------|------|
| `--to AGENT` | — | 宛先エージェント名（必須） |
| `--from AGENT` | — | 送信元エージェント名（省略可） |
| `--subject TEXT` | `-S` | 件名（短いタスク説明） |
| `--reply-to MSG_ID` | — | 返信元メッセージ ID |
| `--correlation-id ID` | — | 会話スレッド追跡 ID |
| `BODY` | — | 本文テキストまたはファイルパス |

**BODY にファイルパスを指定すると** そのファイルの内容が本文として送信される。

### `agent-loop agents` — エージェント一覧

```bash
agent-loop agents
```

```
  orchestrator  (inbox: 0 pending, 12 processed)
  worker1       (inbox: 2 pending, 8 processed)
```

---

## エージェント設計パターン

### パターン 1: オーケストレーター + ワーカー

```
orchestrator (agent-loop, agent_name: orchestrator)
  └─ msg → worker1: "feature A を実装して"
  └─ msg → worker2: "feature B をテストして"
  ← msg from worker1: "feature A 完了"
  ← msg from worker2: "テスト結果: 全件 PASS"
```

**orchestrator の agent-loop.yaml:**
```yaml
agent_name: orchestrator
prompts:
  - name: "タスク分配"
    prompt: |
      GitLab の未アサインイシューを確認し、
      worker1 または worker2 に agent-loop msg で委譲してください。
    interval_minutes: 30
    enabled: true
```

**worker1 の agent-loop.yaml:**
```yaml
agent_name: worker1
inbox_poll_seconds: 5
```

### パターン 2: パイプライン

```
agent-design → msg → agent-implement → msg → agent-review
```

各エージェントは受信したメッセージを処理して次のエージェントに転送する。

### パターン 3: イベントドリブン（hooks との組み合わせ）

hooks で外部イベントを検知し、別エージェントにメッセージを投函する：

```python
# ~/.kiro/hooks/gitlab-hook.py
def check() -> str | None:
    issues = get_new_issues()
    if not issues:
        return None
    issue = issues[0]
    # worker に委譲
    import subprocess
    subprocess.run([
        "agent-loop", "msg",
        "--to", "worker1",
        "--from", "orchestrator",
        "--subject", f"Issue #{issue['iid']}: {issue['title']}",
        issue["description"] or issue["title"],
    ])
    return None  # orchestrator 自身はスキップ
```

---

## トラブルシューティング

| 問題 | 原因 | 対処 |
|------|------|------|
| メッセージが処理されない | 受信側で `agent_name` 未設定 | `agent-loop.yaml` に `agent_name` を追加して再起動 |
| inbox に溜まったまま | kiro-cli が処理中（busy）| 完了を待つか、`agent-loop agents` で状態確認 |
| `agent-loop msg` コマンドが見つからない | agent-loop が古いバージョン | 最新版に更新（`msg` サブコマンド追加済み版） |
| 宛先エージェントのフォルダがない | 受信側が未起動 | 受信側で agent-loop を起動する（inbox ディレクトリは自動作成） |

### デバッグ

```bash
# 受信ボックスを直接確認
ls -la ~/.kiro/agents/worker1/inbox/
cat ~/.kiro/agents/worker1/inbox/<message>.json

# 処理済みメッセージの確認
ls ~/.kiro/agents/worker1/inbox/.processed/

# 全エージェントの状態確認
agent-loop agents
```

---

## メッセージ JSON 構造（参考）

```json
{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "from": "orchestrator",
  "to": "worker1",
  "created_at": 1716460000.0,
  "subject": "feature X の実装依頼",
  "body": "src/feature_x.py を実装してください。\n仕様: ...",
  "reply_to": "orchestrator",
  "correlation_id": "conv-2026-05-23-001",
  "cwd": "/home/user/projects/myapp"
}
```

---

## 実装の注意点

- **同一ホスト限定**: メッセージファイルは `~/.kiro/agents/` 以下に置かれるため、同一マシン上のみ動作
- **べき等性**: 同じメッセージが二重処理されないよう、処理後は `.processed/` に移動される
- **セマフォ対応**: `max_concurrent` が設定されている場合、inbox メッセージもセマフォを取得してから送信する
- **保留と再試行**: セッション未準備またはセマフォ上限の場合、ファイルを保持して次のポーリングで再試行する