agent-mail

エージェントメールシステム

複数のエージェントを連携させるための通信システムです。

概要

エージェントメールでは、次のことができます。

• エージェント間でメッセージを送受信する
• 競合を防ぐためにファイルを予約する
• エージェント間のセッションを追跡する
• スレッドベースの会話を行う

セッション管理

エージェントセッションを開始する

エージェントを登録して、受信トレイを取得します。

# Initialize session
curl -X POST http://localhost:3847/api/session/start \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "program": "claude-code",
    "model": "opus-4",
    "agent_name": "agent-1",
    "task_description": "Working on auth module"
  }'

エージェント一覧を表示する

curl http://localhost:3847/api/agents?project_path=/path/to/project

エージェント情報

curl http://localhost:3847/api/agents/agent-1?project_path=/path/to/project

メッセージ

メッセージを送信する

curl -X POST http://localhost:3847/api/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "sender_name": "agent-1",
    "to": ["agent-2"],
    "subject": "Auth module complete",
    "body_md": "## Summary\nAuth implementation is done.\n\n## Files changed\n- src/auth/*",
    "importance": "normal",
    "ack_required": false
  }'

受信トレイを確認する

curl "http://localhost:3847/api/mail/inbox?project_path=/path/to/project&agent_name=agent-1"

メッセージに返信する

curl -X POST http://localhost:3847/api/mail/reply \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "message_id": 123,
    "sender_name": "agent-2",
    "body_md": "Thanks! I'\''ll start on the API integration."
  }'

メッセージを確認済みにする

curl -X POST http://localhost:3847/api/mail/ack \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-2",
    "message_id": 123
  }'

メッセージを検索する

curl "http://localhost:3847/api/mail/search?project_path=/path/to/project&query=authentication"

ファイル予約

複数のエージェントがファイルを編集するときの競合を防ぎます。

ファイルを予約する

curl -X POST http://localhost:3847/api/files/reserve \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts", "src/config.ts"],
    "exclusive": true,
    "reason": "Implementing authentication",
    "ttl_seconds": 3600
  }'

予約状況を確認する

curl "http://localhost:3847/api/files/reservations?project_path=/path/to/project"

ファイルの予約を解除する

curl -X POST http://localhost:3847/api/files/release \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts"]
  }'

スレッド管理

スレッドの概要を取得する

curl "http://localhost:3847/api/mail/thread/THREAD_ID/summary?project_path=/path/to/project"

スレッド操作

メッセージに返信すると、スレッドが自動的に作成されます。

連携パターン

タスクの引き継ぎ

Agent 1 completes task:
1. Reserve output files
2. Complete work
3. Send message to Agent 2 with handoff details
4. Release file reservations

Agent 2 receives:
1. Get inbox
2. Reserve input files
3. Continue work
4. Acknowledge receipt

並行作業

Coordinator:
1. Reserve coordination files
2. Send tasks to agents
3. Wait for completion messages
4. Merge results

Workers:
1. Reserve assigned files
2. Complete task
3. Send completion message
4. Release files

レビュー依頼

Author:
1. Complete code
2. Send review request to reviewer agents
3. Wait for feedback

Reviewers:
1. Get inbox
2. Review code (read-only, no reservation needed)
3. Send feedback message

ヘルスチェック

curl http://localhost:3847/api/health

メッセージの重要度レベル

レベル	用途
low	参考情報、ステータス更新
normal	通常の連絡
high	早急な対応が必要
urgent	作業を妨げており、即時の対応が必要

ベストプラクティス

1. 編集前に予約する - 競合を防ぎます
2. わかりやすい件名を使う - 受信トレイを確認しやすくなります
3. 重要なメッセージは確認する - ack_required の場合は受信を確認します
4. 速やかに予約を解除する - 不必要に予約を保持しないでください
5. スレッドを使う - 関連するメッセージをまとめます
6. 定期的に受信トレイを確認する - メッセージを見逃さないようにします
7. 適切に引き継ぐ - 必要なコンテキストをすべて含めます