Skip to main content

Tadbir Urus Ejen

Ejen ialah prinsipal kelas pertama dalam Yabanin. Ejen ialah identiti mesin (pekerja automatik, saluran paip CI, sesi OpenCode) yang mengesahkan dengan cara yang sama seperti kunci API manusia — tetapi dijejaki secara berasingan supaya anda boleh menetapkan bajet, menanda, dan menganalisis perbelanjaannya secara bebas daripada mana-mana pasukan.

Halaman ini merangkumi enam bahagian yang menjadikan ejen boleh ditadbir:

  1. Kunci ejen (yag_*) — kelayakan yang digunakan oleh ejen.
  2. Bajet per ejen — siling perbelanjaan harian yang keras bagi setiap ejen.
  3. Penandaan tugasan + bajet token — atribusikan perbelanjaan kepada tugasan logik dan hadkan token bagi setiap tugasan / setiap sesi.
  4. Cangkuk pengawal — semakan PII / rahsia / suntikan pra-keluar yang deterministik.
  5. Kunci diwakilkan (anak) — kunci terhad tempoh, terhad geran, bersiling bajet yang dikeluarkan oleh pengendali ejen untuk subtugasan.

Profil ejen — objek peranan (petunjuk peringkat + templat geran + siling bajet

  • mod pengawal) yang kunci dikeluarkan terhadapnya.

Setiap ciri di sini ialah ikut serta dan dimatikan secara lalai; pelaksanaan yang tidak menetapkan pemboleh ubah persekitaran baharu berkelakuan tepat seperti sebelumnya.


Pengepala keputusan​

Gerbang mengeluarkan keputusan penghalaan yang boleh dibaca mesin sebagai pengepala respons X-Yabanin-Decision (dan, apabila didayakan, pada peristiwa analitik). Pengepala itu ialah objek JSON padat yang menerangkan mengapa permintaan mendarat pada model yang digunakannya:

X-Yabanin-Decision: {"source":"tier_router","class":"easy","confidence":0.92,"threshold":0.7,"from":"gpt-4o","to":"gpt-4o-mini","reason":"time_window_downgrade"}
MedanMaksud
sourceSiapa yang memilih model: cache_exact, cache_semantic, tier_router, rule_override, atau passthrough.
classKelas pengelas yang digunakan (easy / medium / hard); kosong apabila tiada pengelas dijalankan.
confidenceKeyakinan pengelas [0..1]; 0 apabila tiada pengelas dijalankan.
thresholdAmbang penghalaan per organisasi yang keyakinan dibandingkan dengannya.
fromModel yang keputusan beralih daripadanya (diminta klien atau pra-penimpaan).
toModel yang keputusan beralih kepadanya.
reasonSebab bentuk bebas pilihan, contohnya always_premium, always_cheap, time_window_downgrade.
affinity / preferredHasil afiniti sesi yang peka terhadap KV-cache (used / miss) dan model hangat yang diutamakan.

Dayakan/nyahdayakan pengepala dengan YABANIN_DECISION_HEADER (lalai hidup) dan salinan peristiwa analitik dengan YABANIN_DECISION_EVENT (lalai hidup).


Kunci ejen​

Kunci ejen ialah kelas kelayakan yang berasingan daripada kunci API. Ia dicipta dan dibatalkan melalui API pentadbir (CLI yb tidak mengurusnya):

POST /api/agent-keys {"name": "nightly-etl", "org_id": "<org>"} → 201
GET /api/agent-keys?org_id=<org>
GET /api/agent-keys/<id>
POST /api/agent-keys/delegate mint a delegated child key (below)
POST /api/agent-keys/<id>/revoke
GET /api/agent-keys/<id>/budget read the agent's daily budget
PUT /api/agent-keys/<id>/budget upsert (daily_limit_cents)
DELETE /api/agent-keys/<id>/budget remove (returns the agent to denied)

POST /api/agent-keys menjana kunci yag_ dan memulangkan teks biasa tepat sekali dalam respons; hanya sha256 miliknya yang disimpan. Contoh kunci yang dipulangkan (bentuk: yag_ + 32 aksara heks):

{
"key": "yag_9f2c1a4b7e8d30f6a5c9b2d1e4f7a8c3",
"key_id": "8d4f…",
"name": "nightly-etl",
"org_id": "…",
"active": true
}

Ejen mengesahkan dengan menghantar kunci sebagai kelayakan Authorization: Bearer <yag_…>. Apabila sepadan, gerbang:

  • menetapkan org_id permintaan, agent_id (prinsipal), dan sebarang skop pasukan;
  • menanda request_logs dengan agent_id supaya perbelanjaan boleh diatribusikan;
  • menguatkuasakan bajet per ejen jika satu dikonfigurasi.

Kunci ejen boleh dibatalkan (padam lembut: active=false, revoked_at dicop). Kunci yang dibatalkan gagal pengesahan.

Bajet per ejen​

Tetapkan had harian bagi setiap ejen dalam jadual agent_budgets (agent_id, daily_limit_cents). Tingkah laku (gagal selamat, mencerminkan bajet pasukan):

SyaratHasil
Tiada baris agent_budgets bagi ejen403 agent_budget_not_configured — ejen tanpa bajet tidak boleh berbelanja.
Perbelanjaan harian ≥ had429 agent_budget_exceeded — cuba semula kemudian.
Stor bajet tidak tersedia503 agent_budget_check_unavailable — gagal tertutup (jangan sekali-kali benarkan perbelanjaan tanpa batas semasa gangguan pangkalan data).
Dalam hadpermintaan diteruskan; perbelanjaan direkod dalam agent_spend_daily (agent_id, day).

Ejen tanpa baris yang dikonfigurasi dinafikan, jadi mendayakan bajet per ejen ialah tindakan yang disengajakan: cipta baris bagi setiap ejen yang anda benarkan untuk berbelanja.

Kunci diwakilkan (anak)​

Pengendali ejen boleh mengeluarkan kunci anak untuk subtugasan yang terhad tanpa menyerahkan kelayakan induk:

POST /api/agent-keys/delegate
{"parent_agent": "<agent-key id>", "org_id": "<org>", "name": "subtask-render",
"ttl": 86400, "budget_caps": 500, "mcp_grants": ["knowledge"]}

(ttl ialah saat, dihadkan kepada 90 hari; mcp_grants menyenaraikan nama pelayan yang anak boleh panggil — setiap satu disilangkan dengan pelayan yang induk diberi geran.)

Kunci anak mempunyai bentuk yag_ yang sama dan mengesahkan seperti mana-mana kunci ejen. Invarian (dikuatkuasakan pada masa pengeluaran, TTL pada masa penyelesaian):

InvarianPenguatkuasaan
Geran ⊆ geran induk yang didayakangeran yang disimpan ialah persilangan himpunan yang diminta dengan geran induk — anak tidak sekali-kali boleh melebarkan apa yang induknya boleh panggil
Bajet anak ≤ ruang baki indukdelegasi ditolak apabila ia akan melebihi baki had harian induk
Terhad tempohexpires_at disemak dalam penyelesai kunci pada setiap permintaan: kunci anak yang tamat tempoh gagal pengesahan, dan hasil tamat tempoh tidak sekali-kali disimpan dalam cache (tiada hanyut TTL)
Atribusiperbelanjaan jatuh pada agent_id anak sendiri (agent_spend_daily), boleh dilaporkan kepada induk mengikut tag tugasan
Strukturparent_id dicop — anak sentiasa anak; hanya kunci akar (tiada induk) boleh mewakilkan

Profil ejen​

Profil menghimpun tetapan peranan yang dikongsi oleh kelas ejen — petunjuk peringkat penghalaan, templat geran MCP, siling bajet harian (sen) dan mod pengawal — supaya mengeluarkan kunci terhadap profil mewarisi kesemuanya dan bukannya mengkonfigurasi setiap kunci secara manual:

POST /api/agent-profiles {"name": "ci-runner", "tier_hint": "cheap", ...}
GET /api/agent-profiles
GET /api/agent-profiles/<id>
PUT /api/agent-profiles/<id>
DELETE /api/agent-profiles/<id>

POST /api/agent-keys dengan profile_id mengeluarkan kunci pada profil: baris bajet dicipta daripada siling profil dan geran MCP digunakan daripada templat. Invarian: templat geran profil tidak sekali-kali boleh merujuk pelayan yang organisasi belum daftarkan (geran ⊆ registri organisasi sendiri) — pengeluaran tidak sekali-kali melebarkan jejari letupan organisasi.

Geran MCP dan kelayakan per pengguna​

Geran MCP (mcp_server_grants) ialah apa yang ejen boleh panggil; kelayakan MCP ialah cara panggilan mengesahkan ke huluan. Geran ialah siling bagi setiap langkah aliran kelayakan (butiran dalam Gerbang MCP §6):

  • Kelayakan per pengguna hanya boleh diserahkan (pengepala) atau dimulakan (oauth) semasa ejen memegang geran yang didayakan pada pelayan itu — stor menguatkuasakannya pada serah, mula, dan penulisan token.
  • Membatalkan geran mengyatimkan kelayakan (status orphaned): baris dan rahsia yang disulitkan enc: kekal, tetapi tiada seruan yang menggunakannya. Memberi geran semula pada pasangan (server, agent) yang sama memulihkan kelayakan — manusia tidak perlu memberi kebenaran semula.
  • mcp_grants kunci anak (lihat kunci diwakilkan di atas) bersilang dengan geran induk, jadi ejen yang diwakilkan tidak sekali-kali boleh memegang aliran kelayakan yang lebih luas daripada geran induknya.

Siling geran, bukan pelebaran: kelayakan diselesaikan bagi setiap seruan (aktif per pengguna → didayakan peringkat pelayan → tiada) dan tidak sekali-kali boleh meluaskan permukaan keluar yang dikawal SSRF.


Penandaan tugasan & bajet token​

X-Yabanin-Task​

Hantar pengepala X-Yabanin-Task untuk mengatribusikan permintaan kepada tugasan logik (contohnya kerja kelompok, ciri, beban kerja penyewa). Format: [A-Za-z0-9._:-]{1,128}. Permintaan tanpa tag tidak mengapa — ia mendarat dalam baldi '(untagged)' dalam analitik. Nilai tidak sah ditolak dengan 400 invalid_task_id.

Tag tugasan membekalkan:

  • bajet token per tugasan (di bawah), dan
  • analitik kos CTOR / tugasan — GET /api/analytics/tasks?group_by=task dan skrin Tugasan papan pemuka (kos berkumpulan / kontrafaktual / penjimatan per tugasan, dengan eksport CSV untuk caj balik).

Yabanin-Task: treler commit + YABANIN_TASK env CI​

Bagi pembangunan berasaskan ejen (satu tugasan dipacu ejen → satu atau lebih commit → satu PR), tag tugasan dibawa pada commit itu sendiri supaya perbelanjaan PR boleh dibina semula daripada git:

Konvensyen treler. Tambah treler Yabanin-Task: pada setiap commit yang tugasan hasilkan (nilai = tag tugasan, [A-Za-z0-9._:-]{1,128}, format yang sama seperti pengepala X-Yabanin-Task):

git commit -m "feat: …" -m "Yabanin-Task: a142-add-login"

git trailer (bukan baris badan bentuk bebas) ialah perkara yang git interpret-trailers dan semakan CI di bawah bergantung kepadanya.

Env CI. Dalam CI anda (atau pada pelari ejen), eksportkan tag untuk tempoh tugasan supaya setiap panggilan model yang dibuat oleh ejen ditanda:

YABANIN_TASK=a142-add-login # CI env, mirrors the X-Yabanin-Task header

Dengan YABANIN_TASK ditetapkan, gerbang menggunakan tag tugasan yang sama pada setiap permintaan yang dihantar oleh kunci ejen (setara dengan klien yang menghantar X-Yabanin-Task). Bagi gerbang pusat, gunakan yb ci exec atau label task. Tag itu kemudian mendarat dalam request_logs.task_id, jadi skrin Tugasan papan pemuka dan GET /api/analytics/tasks?group_by=task mengatribusikan perbelanjaan model PR kepada a142-add-login — nilai yang sama yang muncul dalam treler commit.

Pasangan itulah yang menjadikan kos PR boleh diaudit: treler pada commit (apa yang dihantar di bawah tag) + env CI pada trafik (apa yang tag belanjakan). Eksport CSV skrin Tugasan (kumpulan, kos, kontrafaktual, penjimatan, hit cache, kiraan permintaan) ialah artifak sedia caj balik bagi nombor itu.

Bajet token (per tugasan / per sesi)​

Siling pilihan bagi token kumulatif dalam memori, merentas tetingkap 24 jam:

EnvLalaiMaksud
YABANIN_TASK_TOKEN_BUDGET0 (mati)Siling token per X-Yabanin-Task. Nilai permulaan yang disyorkan: 500000.
YABANIN_SESSION_TOKEN_BUDGET0 (mati)Siling token per X-Session-Id. Nilai permulaan yang disyorkan: 200000.

0 bermaksud skop itu mati (tiada keadaan dibina, sifar perubahan tingkah laku). Apabila siling ditetapkan:

  • Sebelum pemajuan, gerbang menyemak jumlah berjalan. Pada atau melebihi 80% siling ia menetapkan pengepala respons X-Yabanin-Budget-Warning: token budget at or above 80% dan membenarkan permintaan lalu (peringatan awal, bukan hentian). Pada atau melebihi 100% ia memulangkan 429 token_budget_exceeded dengan pengepala Retry-After.
  • Selepas respons, ia merekod penggunaan token akhir (prompt + completion) terhadap kedua-dua bajet tugasan dan sesi. Ini berjalan pada kedua-dua laluan sembang dan penstriman.

Semantik 429/amaran sama seperti pintu bajet yang lain: amaran tidak mematikan, pelampauan ialah 429 berstruktur yang klien boleh undur daripadanya.


Cangkuk pengawal​

Cangkuk pengawal berjalan pra-keluar pada respons model yang keluar dan prompt yang masuk. Ia ialah pengesan regex/checksum yang deterministik bagi data sensitif dan suntikan prompt — bukan sistem DLP (lihat kaveat di bawah).

Mod (YABANIN_GUARD_MODE, lalai off):

ModTingkah laku
offTiada pengimbasan (lalai). Sifar overhed.
logKesan dan keluarkan metrik/log; jangan ubah respons.
redactGantikan rentang yang dikesan dengan pemegang tempat sebelum respons dipulangkan.
denyTolak permintaan (400 guard_denied) apabila pengesanan tercetus.

Kategori yang dikesan termasuk (tidak menyeluruh):

  • PII: INN (ID pembayar cukai Rusia 10/12 digit, dengan pengesahan digit semak), SNILS (nombor keselamatan sosial, dengan digit kawalan), dan PAN (nombor kad pembayaran yang sah Luhn).
  • Rahsia: bahan kunci peribadi (pengesanan pengepala PEM), corak token/kunci berentropi tinggi.
  • Suntikan prompt: kumpulan kecil corak berketepatan tinggi (penimpaan arahan / frasa eksfiltrasi).

Kaveat jujur tentang positif palsu​

Pengesan sengaja konservatif: jujukan 10 atau 12 digit semata-mata hanya ditanda apabila ia juga lulus pengesahan digit semak / Luhn yang sepadan, jadi nombor biasa (ID, nombor telefon, jumlah) tidak ditanda. Ini mengekalkan kadar positif palsu pada tahap rendah, tetapi ia bukan sifar — dan ia bukan kawalan pencegahan kehilangan data. Cangkuk pengawal ialah pagar keselamatan yang memunculkan dan boleh menyekat data sensitif yang jelas; ia tidak menjamin bahawa tiada data sensitif yang pernah keluar. Pelaksanaan yang dikawal selia sepatutnya menggandingkannya dengan penapisan keluar dan kawalan residensi/garis keturunan.


Analitik kos CTOR / tugasan​

GET /api/analytics/tasks memulangkan, bagi setiap kumpulan, kos sebenar, kos kontrafaktual (kos yang kerja yang sama akan dikenakan pada peringkat premium), penjimatan yang terhasil, dan hit cache:

GET /api/analytics/tasks?org_id=<org>&from=<RFC3339>&to=<RFC3339>&group_by=task&limit=100
  • group_by ialah task, session, atau agent (lalai task).
  • from / to ialah RFC3339 (lalai: 24 jam lepas → sekarang).
  • limit dihadkan pada 500 (lalai 100); kumpulan disusun mengikut kos menurun.
  • Baris tanpa nilai kumpulan jatuh ke dalam baldi '(untagged)'.

Contoh (satu kumpulan):

{
"org_id": "…",
"from": "2026-09-01T00:00:00Z",
"to": "2026-09-02T00:00:00Z",
"group_by": "task",
"groups": [
{
"group": "nightly-etl",
"cost_usd": 10.0,
"counterfactual_usd": 20.0,
"savings_usd": 10.0,
"cache_hits": 5,
"request_count": 50
},
{ "group": "(untagged)", "cost_usd": 3.0, "counterfactual_usd": 6.0, "savings_usd": 3.0, "cache_hits": 1, "request_count": 10 }
],
"total_cost_usd": 13.0
}

counterfactual_usd ialah kos peringkat premium yang direkod bagi setiap permintaan, jadi savings_usd ialah nombor CTOR sebenar (kontrafaktual bagi penghala): apa yang anda belanjakan berbanding kos yang kerja itu akan dikenakan tanpa pengoptimuman peringkat penghala.


Rujukan persekitaran​

Pemboleh ubahLalaiTujuan
YABANIN_GUARD_MODEoffMod cangkuk pengawal: off / log / redact / deny.
YABANIN_TASK_TOKEN_BUDGET0Siling token per tugasan (0 = mati).
YABANIN_SESSION_TOKEN_BUDGET0Siling token per sesi (0 = mati).
YABANIN_TIME_ROUTINGfalseDayakan penurunan peringkat waktu murah / kelompok.
YABANIN_TIME_CHEAP_WINDOW22:00-07:00Tetingkap murah (HH:MM-HH:MM, boleh merentasi tengah malam).
YABANIN_DECISION_HEADERtrueKeluarkan pengepala respons X-Yabanin-Decision.
YABANIN_DECISION_EVENTtrueBawa keputusan pada peristiwa analitik.

Pengepala yang boleh dihantar oleh klien:

PengepalaTujuan
X-Yabanin-TaskAtribusikan permintaan kepada tugasan logik (membekalkan bajet token + analitik).
X-Yabanin-Batch: truePaksa penurunan peringkat murah (kerja kelompok).
X-Yabanin-Priority: highTarik diri daripada penurunan waktu murah bagi permintaan ini.
X-Session-IdIdentiti sesi (membekalkan bajet token sesi).