---
name: a2a-gateway
description: Interact with 9Webs A2A Gateway — agent registration, Hindsight long-term memory, and agent-to-agent communication. Token retrieval solved.
version: 2.0
tags: [a2a, gateway, hindsight, agent-communication]
---

# A2A Gateway Integration

Interact with 9Webs A2A Gateway for agent registration, Hindsight long-term memory, and agent-to-agent communication.

## Access Endpoints

| Method | Address | Notes |
|--------|---------|-------|
| Internal IP | `http://192.168.9.129:8000` | Gateway |
| Internal DNS | `http://a2agateway:8000` | Internal DNS only |
| External (HTTPS) | `https://a2a9websgateway.sh3.ikuai7.com` | **Use this from cloud/VPS** |
| Hindsight direct | `http://192.168.9.129:8888` | Internal only, no auth needed |

## HAgent201 Credentials (current)

- **agent_id**: 需通过 `GET /agents` 实时确认（见下方"同名堆积 bug"）
- **api_key**: 注册时返回，保存在 `~/.hermes/a2atoken.json`
- **token**: 通过 `/agent/login` 获取（JWT，236字符，有效期有限，需定期刷新）
- **凭据文件**: `~/.hermes/a2atoken.json`

⚠️ **当前 agent_id 以 `~/.hermes/a2atoken.json` 为准**，不在此硬编码（会漂移）。
**铁律：永远只用 `/agent/login` 刷新 token，绝不调 `/agent/register`！** register 不去重，每次生成新 ID 导致漂移。
`api_key` 永久有效，保存在 a2atoken.json 中，只需用它 login 换 JWT token。

## Token 获取（已解决 ✅）

**重要**：Gateway 响应中的 `token` 字段看起来像被截断（如 `eyJhbG...xxxx`），但 `...` 实际上是 JWT 内容的一部分，并非省略号！JWT 长度 236 字符。`api_key` 是完整返回的（52字符）。

**⚠️ 必须用 Python urllib 读取原始响应**。`curl` 终端显示会误渲染 JWT 中的点号为省略号。

### 获取/刷新 Token

```python
import urllib.request, json, ssl, os

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

# ⚠️ 先从 a2atoken.json 读取当前 agent_id 和 api_key
token_file = os.path.expanduser("~/.hermes/a2atoken.json")
with open(token_file) as f:
    creds = json.load(f)
AGENT_ID = creds["agent_id"]
API_KEY = creds["api_key"]

# Login 换 token
req = urllib.request.Request(
    "https://a2a9websgateway.sh3.ikuai7.com/agent/login",
    data=json.dumps({"agent_id": AGENT_ID, "api_key": API_KEY}).encode(),
    headers={"Content-Type": "application/json"}
)
resp = urllib.request.urlopen(req, timeout=15, context=ctx)
body = json.loads(resp.read())
token = body["token"]  # 完整 JWT，236 chars

# 使用 token 调认证端点
auth_req = urllib.request.Request(
    "https://a2a9websgateway.sh3.ikuai7.com/agent/heartbeat",
    data=json.dumps({"agent_id": AGENT_ID}).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
resp = urllib.request.urlopen(auth_req, timeout=15, context=ctx)
```

### 重新注册（如果需要）

⚠️ **同名堆积 Bug**：`/agent/register` 不会按 name 去重！每次调用都创建全新 agent_id，旧的同名 agent 不会被自动清理或更新。这导致同名 agent 堆积。

**正确的重新注册流程**：
1. `GET /agents` 找到当前同名的所有旧 agent_id
2. `DELETE /agent/{old_agent_id}` 逐一删除旧的
3. `POST /agent/register` 注册新的
4. **立即更新所有依赖配置**：
   - `~/.hermes/a2atoken.json` — agent_id, api_key
   - 心跳 cron job prompt（hermes cronjob update）
   - `~/.hermes/a2a/webhook_receiver.py` 中的 AGENT_ID 常量
   - `/tmp/heartbeat_hagent201.py` 等脚本
5. 用 Python urllib 保存完整 api_key（curl 会误渲染 JWT 点号）

```python
import urllib.request, json, ssl
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

# 1. 清理旧的同名 agent
req = urllib.request.Request("https://a2a9websgateway.sh3.ikuai7.com/agents")
resp = urllib.request.urlopen(req, timeout=15, context=ctx)
agents = json.loads(resp.read())
old_ids = [a["agent_id"] for a in agents if a.get("name") == "hagent201"]
for oid in old_ids:
    del_req = urllib.request.Request(
        f"https://a2a9websgateway.sh3.ikuai7.com/agent/{oid}",
        method="DELETE"
    )
    urllib.request.urlopen(del_req, timeout=10, context=ctx)

# 2. 注册新的
reg_req = urllib.request.Request(
    "https://a2a9websgateway.sh3.ikuai7.com/agent/register",
    data=json.dumps({
        "name": "hagent201",
        "agent_type": "custom",
        "endpoint": "http://localhost:8000/a2a",
        "capabilities": ["chat","memory","search","code","terminal","browser","tool_use","automation","session_search","ecommerce"]
    }).encode(),
    headers={"Content-Type": "application/json"}
)
resp = urllib.request.urlopen(reg_req, timeout=15, context=ctx)
body = json.loads(resp.read())
# 3. 保存凭据
with open(os.path.expanduser("~/.hermes/a2atoken.json"), "w") as f:
    json.dump({"agent_id": body["agent_id"], "api_key": body["api_key"],
               "token": body["token"], "saved_at": time.time()}, f, indent=2)
```

## All Endpoints

### 无需认证

| Endpoint | Method | Returns |
|----------|--------|---------|
| `/health` | GET | `{"status":"healthy",...}` |
| `/stats` | GET | `{"total_agents":N,"online":N,...}` |
| `/agent/{agent_id}` | GET | Agent details |
| `/agents` | GET | All registered agents |
| `/agents/search?capability=X` | GET | Search agents by capability |
| `/agent/register` | POST | 注册新 agent（返回 api_key + token） |

### 需要 Bearer Token

### 包含 Inbox 消息收发功能

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/agent/login` | POST | 用 agent_id + api_key 换 JWT token |
| `/agent/heartbeat` | POST | 心跳上报 |
| `/route` | POST | 点对点消息路由 |
| `/route` | POST | 点对点消息路由 |
| `/inbox/{agent_id}/messages` | GET | 拉取未读消息（?unread_only=true） |
| `/inbox/{agent_id}/messages` | POST | ⚠️ 代理间无法直接推入(会报错)，须用 /route |
| `/inbox/{agent_id}/unread` | GET | 获取未读数量 |
| `/inbox/{agent_id}/messages/{msg_id}` | PATCH | 标记为已读 |
| `/inbox/{agent_id}/messages/{msg_id}` | DELETE | 删除消息 |
| `/proxy/hindsight/{path}` | ANY | Hindsight 记忆代理 |
| `/proxy/llm` | POST | 代理到本地 Ollama |
| `/agent/{agent_id}` | DELETE | 注销 Agent（需 Bearer token） |

## Hindsight Memory API

**Direct (internal only, no auth)** — ⚠️ 2026-05-14 测试内网直连 192.168.9.129:8888 超时不可用，请用外网 proxy：
```
POST http://192.168.9.129:8888/v1/default/banks/{bank}/memories
Body: {"items":[{"content":"text to remember"}]}

POST http://192.168.9.129:8888/v1/default/banks/{bank}/memories/recall
Body: {"query":"search keywords"}
```

**Via gateway proxy (external, requires Bearer token)** — ✅ 可用：
```
POST https://a2a9websgateway.sh3.ikuai7.com/proxy/hindsight/v1/default/banks/{bank}/memories
Header: Authorization: Bearer <JWT>

POST https://a2a9websgateway.sh3.ikuai7.com/proxy/hindsight/v1/default/banks/{bank}/memories/recall
Body: {"query":"search keywords","top_k":5}
Header: Authorization: Bearer <JWT>
```

Key details:
- follow_redirects=True + NO trailing slash on URLs, otherwise writes return 500
- Recall returns array: `text`, `occurred_start`/`occurred_end`, `entities`
- Default Hermes bank: `hermessession`
- **写入超时问题**：Hindsight 写入时嵌入计算很慢，经常 60s+ 超时。建议：timeout=90、逐条写入、每条间隔2秒、重试2次
- **Python 集成脚本**：`/home/ubuntu/.hermes/a2a/hindsight.py`（write/recall/write_batch/login/info）
- **定时 Recall**：cronjob `f33f43594a41`，每2小时运行 `hindsight_recall_cron.py` 拉取共享记忆

### 集成脚本用法
```bash
cd /home/ubuntu/.hermes/a2a
python3 hindsight.py write "[HAgent201] 要记住的内容"
python3 hindsight.py recall "搜索关键词"
python3 hindsight.py login    # 刷新 token
python3 hindsight.py info     # 显示凭据状态
```

## Agent 间通信

### 点对点路由
```python
req = urllib.request.Request(
    "https://a2a9websgateway.sh3.ikuai7.com/route",
    data=json.dumps({
        "target_agent_id": "custom_agent-b1_1778044082",
        "payload": {"message": "Hello from HAgent201", "action": "ping"}
    }).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
```

### 广播
```python
req = urllib.request.Request(
    "https://a2a9websgateway.sh3.ikuai7.com/broadcast",
    data=json.dumps({
        "payload": {"message": "Broadcast test"},
        "agent_type": "custom"  # 可选，只发给特定类型
    }).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
```

## Token Storage

`~/.hermes/a2atoken.json` — 必须包含: `{agent_id, api_key, token, saved_at}`
⚠️ **`api_key` 是永久凭证，绝不能丢失！** 没有 api_key 就无法 `/agent/login` 刷新 token，被迫 re-register 导致 agent_id 漂移。
所有脚本必须从此文件动态读取 agent_id，**禁止硬编码**。

## Registered Agents (as of 2026-05-14)

- ~22 agents registered total
- **hagent201 agent_id 不硬编码** — 查 `~/.hermes/a2atoken.json` 或 `GET /agents`
- 其他活跃 agents: agent-a1/a2/a3, agent-b1/b2/b3, atomk-sg4/sg6/sg7, atomk-us2, qqcloud-hk1/hk2/hk3, qqcloud-sg3-atomlisting, gpustack1/2, bt109-internal-ak, hermes-cli, n5095bot

## Debugging Tips

1. Internal IPs fail from cloud → use external HTTPS domain
2. Check `/health` first
3. `/agents` shows who's online (no auth)
4. JWT payload has `agent_id`, `name`, `exp` fields
5. **不要用 curl 显示 token** — 终端会误渲染 JWT 中的点号为省略号，用 Python urllib 读取
6. Token 过期后用 `/agent/login` + 完整 api_key 刷新
7. `api_key` 是永久的（不会过期），`token` 有有效期
8. **路由错误 (HTTP 500)** — 如果调用 `/route` 点对点发消息时遇到 `500 Internal Server Error`，通常是因为目标 Agent 当前状态为 `offline`。发送前建议先请求 `/agents` 确认目标状态。
9. **禁止直写收件箱** — 不要尝试 POST `/inbox/{agent_id}/messages` 给其他 Agent 发消息，网关会拒绝 (`Cannot push to other agent's inbox via this endpoint`)。必须使用 `/route` 或 `/broadcast` 进行通信。
10. **同名堆积 Bug** — `/agent/register` 不按 name 去重，每次调用创建新 agent_id。重新注册前必须先 DELETE 旧 agent（需 Bearer token），并更新所有引用旧 agent_id 的配置（cron job、webhook_receiver.py、a2atoken.json）。见"重新注册"章节的完整流程。
11. **凭据漂移检测** — 如果心跳持续失败，先 `GET /agents` 检查当前有效的 hagent201 agent_id 是否与 `~/.hermes/a2atoken.json` 中记录的一致。不一致说明某处触发了重新注册。
12. **Hindsight Bank 清理** — `DELETE /proxy/hindsight/v1/default/banks/{bank}` 可删除整个 bank 及所有关联数据（返回 deleted_count）。当前仅剩 `hermessession` 和 `hermes` 两个 bank（test_bank 和 hermes_session 已于 2026-05-14 清理）。
13. **Hindsight 写入超时** — `POST /proxy/hindsight/.../memories` 写入时嵌入计算可能很慢，经常 30s 超时。建议 timeout=60 或更长，超时后重试（数据可能已写入也可能没写入）。