Skip to main content

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):

KaedahLaluan
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​

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