Agent versiyonlama

Kodda tanımlı bir agent'ın model/system-prompt/maxSteps kombinasyonunu prod'a almadan önce denemek, birden fazla sürümü yan yana tutmak ve gerektiğinde eskisine dönmek (rollback) istediğinizde kullanılır. Her yeni sürüm POST /managed-agents ile journal'a değişmez bir kayıt olarak eklenir (yeni deneme = yeni sürüm numarası); POST /managed-agents/:name/promote yalnızca hangi sürümün "aktif" (prod) olduğunu gösteren işaretçiyi taşır — rollback, eski sürüm numarasını tekrar promote etmekten ibarettir. Aktif sürüm, Studio Playground'dan o agent çalıştırıldığında (run/stream) açık bir model/system override'ı verilmediği sürece otomatik uygulanır. Her sürüm ekleme ve her promote agent.version/agent.promote olay adlarıyla denetim (audit) kaydına düşer.

Ayrı bir kurulum adımı yoktur — agent versiyonlama, @gnldev/studio Studio API'sinin bir parçasıdır ve yazılabilir bir journal (listKeys/get/put destekleyen) verildiğinde kendiliğinden açılır:

import { createStudioApp } from '@gnldev/studio';

app.route('/studio', createStudioApp({
  reader: toJournal(storage.runs), // a writable journal → agent versioning is ON
  gnl: createStudioRunner(gnl, config),
  auth,
}));

GET /capabilities üzerinden agentVersions alanı, journal yazılabilir olduğu için bu görünümün açık olup olmadığını bildirir; değilse (salt-okunur reader) ilgili uçlar 501 döner.

1) Yeni bir sürüm ekleyin — name ve model zorunlu, diğerleri opsiyonel:

{ "name": "destek-botu", "model": "gpt-4o-mini", "system": "Kısa ve nazik yanıt ver.", "maxSteps": 4, "note": "daha kısa ton" }
// -> { ok: true, name: "destek-botu", version: 2, active: 1 }
//    a new version number + an audit 'agent.version'

Sürüm numarası otomatik artar (son sürümün version + 1); kayıt ilk kez oluşuyorsa active: null ile başlar (henüz hiçbir sürüm prod'a alınmamış demektir).

2) Denediğiniz sürümü aktif edin (promote) — rollback için eski sürüm numarasını tekrar promote edin:

{ "version": 2 }
// -> { ok: true, name: "destek-botu", active: 2, previous: 1 }
//    switches the active version (passing the eval gate first, when one is configured)

3) Kayıtları listeleyin — sürüm geçmişi + o an aktif sürüm no birlikte döner:

GET /studio/api/managed-agents
// -> { agents: [ { name: "destek-botu", active: 2, versions: [ { version: 1, model: "...", createdAt }, { version: 2, model: "...", note: "daha kısa ton", createdAt } ] } ] }

Aktif sürüm, Playground'dan POST /agents/:name/run veya /agents/:name/stream çağrıldığında, istek gövdesinde açıkça model/system verilmediği sürece otomatik uygulanır (managed sürüm devreye girdiğinde audit kaydında managedVersion: true işaretlenir).