Gerbang A2A
Gerbang A2A YABANIN ialah pasangan ejen-ke-ejen bagi
gerbang MCP: organisasi mendaftarkan ejen
A2A luaran (protokol Agent2Agent) dalam registri berskop organisasi, dan prinsipal
ejen organisasi (kunci yag_) menghantar mesej kepada mereka melalui gerbang — dengan
kawalan akses ejen sahaja, pengawalan SSRF, pengawal parameter pra-keluar dan
jejak audit setiap penghantaran. Ia mati secara lalai: kumpulan laluan dipasang
hanya apabila YABANIN_A2A_GATEWAY=1.
Skop v1 — dinyatakan dengan jujur
Proxy membawa kaedah JSON-RPC A2A message/send
(permintaan/respons). Penstriman (message/stream) dan pemberitahuan tolak tidak
di-proxy dalam v1 — ia ialah tambahan kemudian, bukan jurang tersembunyi. Gerbang
membungkus params klien (objek message A2A) ke dalam
sampul JSON-RPC itu sendiri, supaya pemanggil tidak dapat menyeludup kaedah sewenang-wenang.
Cara ia berfungsi
agent (yag_ key) ──► POST /api/a2a/send {"agent":"helper","params":{...}}
│
├─ auth: agent-principal only (org keys → 403 agent_only)
├─ registry: (org, name) must exist and be enabled
├─ SSRF: per-send re-validation (rebind window)
├─ guard: pre-egress scan of the message params
└─ upstream: JSON-RPC message/send → the agent's URL
result (raw JSON-RPC result) ──► back to the caller
Setiap penghantaran diaudit ke jejak request_logs yang sama seperti trafik model:
model_used membawa label a2a:<agent>, params (yang dirahsiakan oleh pengawal) terbawa pada
muatan, dan tag X-Yabanin-Task mengaitkan penghantaran kepada tugasan.
Registri
a2a_agents (migrasi 0015) — berskop organisasi, URL https:// sahaja, UNIQUE (org_id, name), lengai sehingga didayakan. CRUD pentadbir (root sahaja,
berskop organisasi):
| Kaedah | Laluan |
|---|---|
| POST | /api/organizations/{id}/a2a/agents |
| GET | /api/organizations/{id}/a2a/agents |
| GET | /api/organizations/{id}/a2a/agents/{name} |
| PATCH | /api/organizations/{id}/a2a/agents/{name} |
| DELETE | /api/organizations/{id}/a2a/agents/{name} |
Pendaftaran (dan setiap kemas kini URL) menjalankan pengawal SSRF: https sahaja, tiada
kelayakan dalam URL, senarai benarkan domain pelaksanaan
(YABANIN_A2A_ALLOWED_UPSTREAMS, dipisahkan koma; kosong = tiada domain
dibenarkan — gagal-tertutup), dan peleraian DNS yang menolak jawapan IP terpelihara
(endpoint metadata, RFC1918, loopback, link-local, CGNAT). Pengawal dijalankan semula
pada setiap penghantaran — tetingkap DNS-rebind antara pendaftaran dan penggunaan tidak
boleh dieksploitasi.
API Gerbang
curl -X POST "$BASE_URL/api/a2a/send" \
-H "Authorization: Bearer yag_..." \
-H "Content-Type: application/json" \
-d '{
"agent": "helper",
"params": {"message": {"messageId": "m-1", "role": "user",
"parts": [{"kind": "text", "text": "status?"}]}}
}'
Kontrak ralat: agent_only (403), not_found (404 — ejen yang tiada, dilumpuhkan atau
organisasi lain tidak dapat dibezakan), ssrf_blocked (400), denied (409,
pengawal), upstream (502), timeout (504).
Konfigurasi
| Persekitaran | Lalai | Maksud |
|---|---|---|
YABANIN_A2A_GATEWAY | false | Pasang kumpulan laluan /api/a2a/send |
YABANIN_A2A_ALLOWED_UPSTREAMS | (kosong) | Senarai benarkan domain SSRF untuk URL ejen (kosong = gagal-tertutup) |
Panggilan huluan dihadkan: 10s sambung, 30s baca, had respons 8 MiB,
ubah hala ditolak. Pengepala identiti (X-Yabanin-Agent-Id/-Name/-Team-Id)
dibawa ke huluan daripada prinsipal yang disahkan — salinan klien dilucutkan pada
kemasukan.
Berbanding dengan gerbang MCP
Disiplin yang sama (SSRF, pengawal, audit, ejen sahaja), objek berbeza: registri MCP menunjuk kepada alat, registri A2A kepada ejen. Jadual geran setiap ejen (corak MCP) ialah tambahan terancang untuk A2A — v1 memberi kuasa penghantaran pada peringkat organisasi.