diff --git a/skills/cross-border-ecommerce/a2a-gateway-messaging/SKILL.md b/skills/cross-border-ecommerce/a2a-gateway-messaging/SKILL.md new file mode 100644 index 0000000..f8e3819 --- /dev/null +++ b/skills/cross-border-ecommerce/a2a-gateway-messaging/SKILL.md @@ -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/.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.