Ajan Yeteneklerinde Yeni Dönem: Tek Sağlayıcıyla Üç Yazım Şekli

Neden bu haber bana tanıdık geldi?

Şunu açık konuşayım: Agent Framework tarafında bazen minicik görünen bir özellik, sahada büyük çoğunluk akışı değiştiriyor. Buradaki konu da tam öyle. Python’da ajan yeteneklerini artık dosya olarak, satır içi kodla ya da sınıf tabanlı şekilde yazıp aynı sağlayıcı içinde bir araya getirebiliyorsunuz. Kağıt üstünde “tamamdır” dedirtiyor; pratikte işe ekiplerin elini baya rahatlatıyor.

Vallahi, Bunun zayıf tarafı da belli: Mantık büyüdükçe tek dosyanın çevresine fazla yük binmeye başlıyor. Mesela referans belgeler artıyor, script sayısı çoğalıyor ve sız fark etmeden mini bir uygulamaya dönüşüyor… orası biraz sıkıntılı.

Inline Python code neden hâlâ değerli?

Açık söyleyeyim, ben inline kodu “geçici ama işe yarar” araçlardan sayıyorum (yanlış duymadınız). 10 dakikada yapılacak entegrasyonlarda baya iyi oluyor. 2024’te İzmir’deki bir SaaS ekibinde bunu kullandık; HR sistemi için tam paket gelene kadar mevcut internal client üzerine incecik bir köprü kurduk ve demo günü kurtuldu.

Gel gelelim bu yöntem uzun süre orada kalınca teknik borç başlıyor (buna dikkat edin). Kod görünürde hafif ama sahiplenme belirsizleşiyor; kim yazdıysa ona soruluyor ki bu da sürdürülebilir değil.

Sınıf tabanlı yetenekler niye daha kurumsal hissettiriyor?

Sınıflar bana hep “burada biraz düzen var” hissi verir. Bilhassa ortak davranışları paylaşan yeteneklerde çok rahat ediyoruz: doğrulama mantığı ortaksa tek yerde tutulur, loglama standardı varsa her alt sınıfa yayılır, test kurgusu temiz olur.

Buna rağmen herkes sınıfa koşmamalı diye düşünüyorum. Startup tarafında fazla soyutlama bazen gereksiz ağırlık yaratıyor; büyük kurumsalda işe tersine eksik soyutlama kaosa dönüyor.

Tek provider ile kompozisyon nasıl işleri toparlıyor?

Beni en çok etkileyen kısım burası öldü desem abartmış olmam. Tek sağlayıcı fikri aslında basit: farklı kaynaklardan gelen skills’leri toplayıp keşfetmekten filtrelemeye kadar aynı hat üzerinde yönetiyorsunuz. Dosya sistemi ayrı dert olmaktan çıkıyor; paket deposu başka dünya olmaktan çıkıyor; geçici bridge kodu da aynı mimarinin içine giriyor.

Bence asıl kazanım hız değil yalnızca; tutarlılık.

Farklı kaynaklardan gelen yetenekleri tek yerden toplamak, ajan mimarisini büyütürken sürprizleri azaltıyor.

Kendi sahamda en çok karşılaştığım problem deduplike meselesi öldü. Aynı işimde iki skill gelip — en azından ben öyle düşünüyorum — birbirini eziyordu ya da yanlış öncelik seçiliyordu. Kompozisyon katmanı bunu çözüyor gibi görünüyor ve dürüst olayım — sonunda biri bu işi düzgün düşünmüş dedirtiyor.

Kullanım Şekli	Ne Zaman İyi	Zayıf Tarafı
File-based	Dökümantasyon ağırlıklı akışlar	Büyüyünce klasör karmaşası
Inline code	Acil prototip ve köprü işleri	Tatmin edici ama geçici çözüm
Class-based	Tahmin edilebilir kurumsal yapı	Küçük işte fazla ağır kaçabilir
Multi-source composition	Melez ortamlar ve ölçeklenen ekipler	Kural seti doğru kurulmazsa karışır

Saha gerçekliği: Türkiye’de bunu nasıl okurum?

Bunu Türkiye’deki şirketler açısından değerlendirecek olursam… çoğu kurumun derdi teknoloji eksikliğinden çok organizasyonel parçalanma oluyor.

Bir ekip GitHub’dan beslenir

diğeri iç paket kaynağı kullanır

başka biri de “şimdilik local’den alalım” der.

Tam burada composable source mantığı baya işe yarıyor çünkü herkesin dünyasını zorla tek formata sokmadan ortak çalışma zemini veriyor.
)

Eh, Lafı gevelemeden söyleyeyim: Kurumsal müşterilerimde gördüğüm kadarıyla insanlar önce esneklik istiyor sonra kontrol arıyor.

Bu yüzden hibrit model değerli.

Küçük startup iseniz tek repo + birkaç inline deney yeterli olabilir;

enterprise taraftaysanız onay mekanizması,
kaynak önceliği,
deduplication politikası
ve gözlemlenebilirlik şart.
Yoksa üç ay sonra kim hangi skill’i nereden getirdi diye toplantı açarsınız…
ve o toplantılar hiç sevimli olmaz.

Ayrıca maliyet tarafından bakınca da ilginç nokta var:

Azure tarafındaki agent katmanlarında ana maliyet çoğu zaman sadece çalışma anından gelmiyor;
bakım süresi,
entegrasyon kırılmaları
ve yeniden düzenleme emeği de ciddi para yakıyor.
TL bazında düşününce bugün ufak görünen düzenleme ihtiyacı yarın ekibe iki sprint yedirir.
O yüzden ben kompozisyonlu yaklaşımı sadece teknik değil ekonomik açıdan da mantıklı buluyorum.
Bazen pahalı olan servis ücreti değil,
dağınıklığın faturasıdır.
“””

Kod tarafında dikkat edeceğiniz noktalar neler?

from pathlib import Path
from agent_framework import Agent, SkillsProvider
from agent_framework.foundry import FoundryChatClient
skills_provider = SkillsProvider.from_sources(
file_system=Path("skills"),
packages=["contoso.hr.skills"],
inline_code=[
"""
def time_off_balance(employee_id):
return {"employee_id": employee_id}
"""
]
)
agent = Agent(
client=FoundryChatClient(),
skills_provider=skills_provider
)

Kod örneği sade görünüyor ama mesele satırlarda bitmiyor.

En hayatı konu discovery ile filtering arasındaki sınırın net olması.

Hangi kaynak önce taranacak?

Aynı işim çakışınca hangisi kazanacak?

Bir sorun olduğunda log’a ne düşecek?
İşte bunları baştan belirlemek lazım…

Ben AZ-305’e hazırlanırken yıllar önce öğrendiğim şey şuydu:

iyi mimarı yalnızca çalışan sistem değildir;

bakımı öngörülebilen sistemdir.

Agent Skills tarafında da aynı refleks geçerli geliyor bana.

Mesela class-based tasarım sizi testte rahatlatırken,
file-based yapı içerik sahibini mutlu eder,

inline code işe acil durumda nefes aldırır.

Hepsinin yeri var.
Ama hepsini plansız karıştırırsanız hikâye kötüleşir.”
“

Sorun çıktığında ne yaptım?

2004’ten beri sistemcilikte gördüğüm klasik hata yine burada çıktı:
aynı anda hem local path hem package index hem inline bridge tanımlanınca sıra karıştı.
İlk denememde `skill not found` benzeri sınır bozucu bir hata aldım;
meğer priority sırası beklentimin tersindeymiş.
Çözümü oldukça basitti:
önce kaynak listesini daralttım,
sonra isimleri netleştirdim,
ardından dedup kuralını görünür hâle getirdim.

Bu tür sorunlarda panikle daha fazla source eklemeyin;
tam tersine azaltın.”

.NET tarafıyla kıyaslayınca ne görüyorum?

Bu konuda %100 emin değilim ama sanırım Python cephesi biraz daha serbest ruhlu ilerliyor.
.NET postundaki karşılıklarla konsept aynı olsa da Python API’sinde doğallık hissi daha yüksek geliyor bana.

Ha bu arada Prompt Injection’ı Durdurmak: Agent Framework’te FIDES:

gibi güvenlik odaklı konularla birlikte düşündüğünüzde multi-source yaklaşımı ayrıca dikkat gerektiriyor;

çünkü her yeni source beraberinde yeni saldırı yüzeyi getirir.

En çok da internal package index üzerinden gelen içerikler iyi taranmıyorsa risk büyür.

Bunu Azure IaaS projelerinde savunma katmanlarını planlarken de gördüm:
özgürlük arttıkça denetim ihtiyacı artar.

Yanı “çok kaynak = daha iyi” diye düz hesap yok;

kontrol mekanizması zayıfsa tam tersi olur.

E tabi burada Microsoft’un AGT yaklaşımı veya Foundry güvenlik modelleriyle yan yana düşünmek faydalı;

ajanların eriştiği şey sadece veri değil,

kurum politikalarıdır.

Ha unuttum neredeyse:

küresel ölçekte çalışan şirketlerde sürüm uyumu da önemli;
Python paket sürümü ile agent framework sürümü uyuşmazsa çıldırırsınız.

Ben böyle durumlarda önce bağımlılık ağacını temizleyip sonra ileri giderim.

• düşük riskli başlangıç için file-based skill kullanın;
• süreksiz ihtiyaçlar için inline code’u kısa tutun;
• büyüyen alanları class’a taşıyın;
• aynı anda birçok kaynağı eklemeden önce dedup kuralınızı netleştirin;
• endüstriyel ortamdaysanız logging ve approval sürecini atlamayın;

---

Sahadan küçük notlar

‍ve benim kişisel görüşüm

Mevcut örnek güzel

ama henüz ham

Biraz daha pişmesi lazım.

Bilhassa de büyük ekiplerde source öncelikleri

ve hata mesajları daha açıklayıcı olmalı;

aksi hâlde geliştirici yanlış yolda uzun süre oyalanabiliyor.

Ben bunu Logosoft’ta geçtiğimiz sene Nisan ayında yaptığımız bankacılık otomasyon demosunda birebir hissettim:

işleyen şey sayıca azdı

ama konfigürasyon çeşitliliği artınca debug süresi uzadı.

Yanı evet,

özellik fena değil;

hatta baya işe yarar.

Ama üretime çıkarırken gözünüz kapalı güvenmeyin.

Dört gözle beklediğim nokta şu:

provider seviyesinde observability daha görünür hâle gelsin;

hangi source’tan hangi skill geldiğini,

neden elendiğini

ve niye çakıştığını anlık görmek isterim.

O zaman iş gerçekten oturur.

### Ben olsam ilk gün ne yaparım?

1) Önce sadece file-based skill ile başlayın.

2) Ardından tek bir inline bridge ekleyin.

3) Sonra class tabanlı versiyona refactor edin.

4) En son multi-source composition’u açın.

5) Çatışma politikasını loglayın.

Aslında — dur bir saniye — önce güvenlik demeliyim:

prompt injection riski olan alanlarda external source kabulünü sınırlandırmadan ilerlemeyin.

Tek sağlayıcı fikri cazip çünkü karmaşıklığı saklamıyor;

tam tersine yönetilebilir hâle getiriyor.

Ama bunun bedeli disiplin:

isimlendirme,

sahiplik,

sürümleme

ve güvenlik kontrolleri net olacak.

Sıkça Sorulan Sorular

Python’da Agent Skills tam olarak ne işe yarıyor?

Aslında ajanlara dış dünyayla konuşabilme yeteneği kazandırıyor diyebilirim. Yanı dosya okuma, script çalıştırma, paketten gelen davranışı kullanma gibi işleri ortak bir modele bağlıyor — hepsini tek çatı altında topluyor (buna dikkat edin)

Tek provider içinde farklı kaynakları karıştırmak risk mi?

Kontrolsüz yapılırsa evet, risk var. Ama bence öncelik, filtreleme ve deduplication düzgün ayarlanırsa gayet sağlıklı işliyor; hatta açıkçası bakım yükünü bile azaltıyor.

Küçük ekipler hangi modeli seçmeli?

Küçük ekiplerde genelde file-based + ufak bir inline bridge yeterli oluyor. Her şeyi sınıfa taşımaya gerek yok; tecrübeme göre önce hız kazanın, sonra düzenlersiniz zaten.

Büyük enterprise yapılarda hangisi tercih edilmeli?

Size bir şey söyleyeyim, Büyük yapılarda class-based yaklaşım çok daha rahat ettiriyor, çünkü test, versiyonlama. Sahiplik meselesi netleşiyor. Multi-source composition işe mesela farklı departmanların katkısını bir araya getirmek için oldukça uygun bir çözüm (buna dikkat edin)

Peki güvenlik kısmı?

Dış kaynaktan gelen her yeteneği otomatik kabul etmeyin — bu konuda açıkçası çok dikkatli olmak gerekiyor. Approval akışı, loglama ve mümkünse allowlist kullanın. Bilhassa prompt injection gibi tehditlere karşı ekstra önlem şart.

Kaynaklar ve İleri Okuma

Orijinal Microsoft DevBlogs Yazısı — Agent Skills for Python: File, Code, and Class – Composed in Öne Provider

İşte, size bir şey söyleyeyim, Azure Identity for Python Resmî Dokümantasyonu

Microsoft Agent Framework GitHub Deposu