Add cross-border-ecommerce/a2a-gateway-messaging

2026-07-10 16:12:05 +08:00
parent f8996395ed
commit 7d274df107
1 changed files with 91 additions and 0 deletions
@@ -0,0 +1,91 @@
+---
+name: a2a-gateway-messaging
+description: "9Webs A2A Gateway: agent registration, Hindsight long-term memory, agent-to-agent communication, and automated inbox message handling."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [a2a, gateway, agent-communication, messaging, inbox, webhook, automation]
+---
+
+# A2A Gateway & Messaging
+
+Interact with 9Webs A2A Gateway for agent registration, long-term memory, agent-to-agent communication, and automated inbox message handling.
+
+**Architecture change (2026-06-22):** SG3 (atomlisting.com) now serves as the A2A Gateway, replacing the standalone `a2a-gateway` service. All agent registration, routing, inbox, and WebSocket endpoints are at `https://www.atomlisting.com/api/v1/a2a/*`.
+
+## Section 1: SG3 A2A Gateway — Registration & Communication
+
+Agent registration, routing, and communication via SG3's integrated A2A Gateway.
+
+**API base:** `https://www.atomlisting.com/api/v1/a2a`
+
+**When to use:** Registering agents for inter-agent communication, sending messages between agents, querying inboxes.
+
+**Key endpoints:**
+- `POST /agents/register` — register new agent (returns API key once)
+- `GET /agents` — list user's agents
+- `POST /route` — route message to target agent (WS then inbox)
+- `POST /broadcast` — broadcast to all user's agents
+- `GET /inbox/{agent_id}` — get inbox messages
+- `WS /ws/{agent_id}` — real-time WebSocket (auth: X-Agent-Key header)
+
+**Key features:**
+- Agents owned by users (tenant isolation)
+- API keys hashed with SHA-256
+- WebSocket delivery preferred, inbox fallback with HTTP push
+- Reuses SG3's JWT auth (hardened with refresh token families)
+
+**See:** `references/a2a-gateway.md` for legacy standalone gateway docs (deprecated).
+**See:** `references/sg3-a2a-gateway.md` for the new SG3-integrated API.
+
+## Section 1b: Memory Provider Migration (Hindsight → Holographic)
+
+**Current primary memory:** Holographic (built-in Hermes plugin)
+- Local SQLite + FTS5 + HRR vector + trust scoring
+- Zero config, zero external deps
+- Enable: `hermes config set memory.provider holographic`
+- Hindsight (bank=hermes, LLM=hunyuan-large, X-API-Key) kept as fallback
+
+**Hindsight current status:** Server up (hgents05.9webs.online) but LLM (hunyuan-large)
+returns BadRequestError on write. Script at `~/.hermes/a2a/hindsight.py` available
+for retry. Hindsight LLM model is set at server level, NOT configurable via bank API.
+
+## Section 2: A2A Inbox Handler
+
+Automated A2A message response mechanism — webhook reception + inotify real-time monitoring + cron fallback polling.
+
+**When to use:** Automatically processing incoming A2A messages without manual intervention.
+
+**Key patterns:**
+- Webhook receiver for instant message processing
+- inotify file watcher for local queue monitoring
+- cron fallback for guaranteed polling
+- Message parsing and response routing
+
+**Security:** All receiver scripts were hardened in 2026-06-22 audit (HMAC auth, path containment, quarantine mode for skill pushes). See `references/a2a-receiver-security.md`.
+
+**See:** `references/a2a-inbox-handler.md`
+
+## Section 3: Hindsight Long-Term Memory
+
+Write/recall to the Hindsight shared memory bank for durable cross-session knowledge.
+
+**Endpoint:** `https://hgents05.9webs.online/hindsight`
+**Bank:** `hermes`
+**Auth:** `X-API-Key` header
+**Script:** `~/.hermes/a2a/hindsight.py`
+
+**Key commands:**
+```bash
+python3 hindsight.py write "内容"        # 写入单条
+python3 hindsight.py recall "关键词"      # 语义检索
+python3 hindsight.py info                # 连通性检查
+```
+
+**Pitfall:** Hindsight's backend LLM (hunyuan-large) can return `BadRequestError`, making all writes fail. When this happens, save content to `~/.hermes/reference/<topic>.md` as local fallback and retry later.
+
+**Write pattern:** Split long content into ≤3-item batches with 2s delays. Timeout 90s with 2 retries.
+
+**See:** `references/hindsight-troubleshooting.md` for diagnostics and fallback workflows.