Vercel, her bir aracın (tool) yalnızca açıkça beyan ettiği sırları (secrets) almasını zorunlu kılan bir kapsamlı araç bağlamı (scoped tool context) özelliğiyle AI SDK'nın 7. sürümünü yayınladı. Maruziyeti sınırlayarak geliştiriciler, üçüncü taraf araçların ortamlarında (environment) saklanan tüm kimlik bilgilerini yanlışlıkla görmesini engelleyebilir.

Bu değişiklik neden önemli

AI ajanları genellikle sipariş sorgulama, bilet oluşturma, ödeme işleme gibi her biri kendi API anahtarlarına veya URL'lerine ihtiyaç duyan birden fazla harici servisi bir araya getirir. Yaygın olan kısa yol, her araca tüm process.env nesnesini vermektir:

execute(input, { context: process.env })

Bu desen, örtük bir yetki genişlemesine (implicit privilege expansion) neden olur: yeni bir araç eklemek, herhangi bir kod inceleme uyarısı olmaksızın, veritabanı şifreleri veya ödeme jetonları (tokens) dahil olmak üzere mevcut tüm sırların erişimini anında sağlar. Risk, ele geçirilmiş veya hatalı bir aracın, kendisine asla verilmemesi gereken kimlik bilgilerini aniden sızdırmasıdır.

Kapsamlı araç bağlamı (scoped tool context) nasıl çalışır

SDK 7'de bir araç, ihtiyaç duyduğu alanların tam bir Zod tabanlı tanımı olan bir bağlam şeması (context schema) beyan eder. Ajan bir aracı çağırdığında, çağırıcı yalnızca beyan edilen bu alanları içeren bir toolsContext nesnesi sağlar. SDK, yürütmeden önce yapıyı doğrular; eksik veya fazla anahtarlar hata verir.

Minimal bir demo, birbirinden farklı gereksinimleri olan iki aracı gösterir:

  • lookupOrder – dahili bir sipariş servisini çağırmak için baseUrl gerektirir.
  • createTicket – bir destek bileti açmak için supportToken gerektirir.

Her araç, tek bir gerekli anahtarını listeleyen bir contextSchema dışa aktarır. Ajan çalıştığında şunları iletir:

{
  lookupOrder: { baseUrl: "https://orders.internal" },
  createTicket: { supportToken: "s3cr3t-token" }
}

Yalnızca lookupOrder baseUrl değerini görür; createTicket ona asla dokunmaz ve tam tersi de geçerlidir. SDK, bu sınırı çalışma zamanında (runtime) uygular ve gizli bir bağımlılığı, incelemecilerin denetleyebileceği açık bir yetenek listesine dönüştürür.

Güvenlik avantajları

  • Veri maruziyetini sınırlar – kimlik bilgileri ihtiyaç duyulan yerde kalır.
  • Bağlamı doğrular – eşleşmeyen veya eksik alanlar yürütmeyi durdurur.
  • Yetenekleri açık hale getirir – incelemeciler her bir aracın tam olarak neye erişebileceğini görebilir.
  • Etki alanını (blast radius) azaltır – bir araç ele geçirilirse, saldırgan yalnızca o aracın yetkili olduğu sırları elde eder.

Bu özellik geleneksel kum havuzu (sandboxing) yöntemlerinin yerini almaz. Geliştiriciler hala günlük gizleme (log redaction), ağ çıkış kontrolleri (network egress controls) ve düzenli jeton rotasyonu (token rotation) uygulamalıdır. Kapsamlı bağlam bir sınırdır; odayı tamamen mühürlemez.

Geliştiricilerin neleri düzenlemesi gerekiyor

  1. Her araç için bir şema tanımlayın – SDK ile birlikte gelen Zod kütüphanesini kullanın.
  2. Dar kapsamlı bir toolsContext iletin – her şeyi kapsayan process.env kullanımından kaçının.
  3. Mevcut ajanları gözden geçirin – araç çağrılarından kaldırılabilecek tüm sırları belirleyin.
  4. Otomatik testler ekleyin – fazladan veri enjekte edildiğinde bağlam doğrulamasının başarısız olduğundan emin olun.

Hızlı başlangıç şu şekildedir:

mkdir scoped-tools && cd scoped-tools
npm init -y
npm install ai zod
npm install -D typescript tsx @types/node

demo.ts dosyasını oluşturun, her aracın contextSchema değerini tanımlayın ve tsx demo.ts ile çalıştırın. Eğer bir araca istemediği bir sır vermeye çalışırsanız SDK hata verecektir.

Karşı görüş

Bazı ekipler, fazladan şema tanımlarının gereksiz kod kalabalığına (boilerplate) yol açtığını ve prototipleme sürecini yavaşlattığını savunabilir. Bu doğru olsa da maliyet oldukça düşüktür — araç başına sadece birkaç satır — ve güvenlik getirisi, entegre edilen servis sayısı arttıkça büyür. Ödeme verilerini veya kişisel bilgileri işleyen ortamlarda, bu takas göz ardı edilemeyecek kadar önemlidir.

Sırada ne var?

  • Benimsenme metrikleri – ilk kullanıcılar daha az sır sızıntısı vakası bildirmeye başladı.
  • Topluluk araçları – yapılandırma dosyalarından otomatik olarak bağlam şemaları oluşturan eklentiler.
  • Gelecekteki SDK sürümleri – Vercel'in kapsamlı bağlamları ağ izinlerini ve hız sınırı (rate-limit) kısıtlamalarını da içerecek şekilde genişletebileceğine dair ipuçları.

Eğer halihazırda Vercel'in SDK'sı ile AI ajanları geliştiriyorsanız, ilk adım mevcut process.env kullanımınızı denetlemektir. Tüm araç çağrılarından çıkarılabilecek tekil değerleri belirleyin ve her şeyi kapsayan deseni kapsamlı bir toolsContext ile değiştirin. Sonuç, AI ajanlarını güçlü kılan esneklikten ödün vermeden daha sıkı bir güvenlik duruşu olacaktır.