---
name: a2a-inbox-handler
description: A2A消息自动响应机制 — webhook接收 + inotify实时监听 + cron兜底轮询
version: 1.0
tags: [a2a, inbox, webhook, inotify, cron]
---

# A2A Inbox Handler

HAgent201 自动响应其他Agent通过A2A Gateway发来的消息。

## 架构

```
方案一：Gateway /route → 本地 Webhook :8788 → ~/.hermes/a2a/inbox/ → inotify watcher → hermes chat
方案二：cron scanner (5min) 轮询主动拉取 Gateway GET /inbox/{agent_id}/messages → hermes chat → PATCH 标记已读
```

## 文件结构

```
~/.hermes/a2a/
├── webhook_receiver.py   # HTTP服务，POST /a2a/inbox 接收消息
├── inbox_watcher.py      # inotify实时监听，新消息触发hermes chat
├── inbox_scanner.py      # cron兜底，扫描inbox处理漏网消息
├── a2a_handler.sh        # 统一管理脚本 (start/stop/status/test/restart)
├── inbox/                # 待处理消息
├── processed/            # 已处理消息
└── logs/                 # webhook.log, watcher.log, scanner.log
```

## 管理

```bash
# 启动/停止
~/.hermes/a2a/a2a_handler.sh start
~/.hermes/a2a/a2a_handler.sh stop
~/.hermes/a2a/a2a_handler.sh restart
~/.hermes/a2a/a2a_handler.sh status

# 测试
~/.hermes/a2a/a2a_handler.sh test

# 手动扫描
python3 ~/.hermes/a2a/inbox_scanner.py
```

## 开机自启

systemd service: `a2a-handler.service` (enabled)

## Cron兜底

cronjob ID: cf0afc951a01, 每5分钟执行 `inbox_scanner.py`

## 端口

- Webhook: 8788 (POST /a2a/inbox, GET /health)

## 消息格式

Webhook接收的JSON：
```json
{
  "source_agent_id": "custom_xxx",
  "payload": {"message": "...", "action": "chat"}
}
```

处理后移至 `processed/` 目录。

## 注意

- Gateway 目前没有原生inbox端点，/route是即发即弃
- 如果要实现Gateway → Webhook转发，需在Gateway端配置消息路由
- inbox_watcher依赖 pyinotify（已安装到hermes-agent venv）