92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
---
|
|
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.
|