---
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.