smolagents 1.26.0 ile Yerel Araç Ajanı: Erişilebilir Mekân Seçimi Testi

by

⏱️ 12 dk tahmini okuma süresi
📝 2097 kelime
♿ WCAG 2.2 Uyumlu
Bu Makaleyi Sesli Dinleyin
Doğal Türkçe ses sentezleyici hazır



Kısa sonuç: Hugging Face smolagents 1.26.0’ı Python 3.12 üzerinde geçici bir ortama kurdum ve ücretli API yerine Ollama’daki yerel Qwen3.5 4B modelini kullandım. Ajan, üç toplantı mekânı için fiziksel erişilebilirlik ve ulaşım araçlarını altı kez çağırdı; beş zorunlu koşulu karşılayan Kent Atölyesi’ni doğru seçti. Koşum 124 saniye sürdü. Sonuç doğruydu ama Türkçe metinde “ELİNE İNDE” gibi bozuk ifadeler vardı. Kütüphane küçük ve esnek; yerel modelin yavaşlığı, çıktı kalitesi ve araç izinleri ise sizin sorumluluğunuzda.

smolagents ne işe yarar, kimler için?

smolagents, bir dil modelini Python işlevleri, web araması, MCP araçları veya başka ajanlarla konuşturan açık kaynak bir ajan kütüphanesidir. İki ana yaklaşımı var: ToolCallingAgent araç adını ve parametrelerini yapılandırılmış çağrı olarak üretir; CodeAgent ise eylemlerini Python kodu biçiminde yazar. Bu yazıda daha dar izin yüzeyi için yalnız araç çağıran türü kullandım. Model hiçbir dosyayı, kabuk komutunu ya da internet adresini doğrudan açamadı.

Araç; kendi veri kaynaklarına bağlı küçük ajan prototipleri hazırlayan Python geliştiricileri, yerel modelle çalışmak isteyen ekipler ve hazır bir platformun getirdiği ağır altyapıyı istemeyen araştırmacılar için uygun. Görsel akış editörü, kullanıcı yönetimi ve hazır onay ekranı bekleyenler için Dify veya Flowise daha hızlı olabilir. smolagents bir son kullanıcı uygulaması değil; izin, arayüz, günlük saklama, değerlendirme ve insan onayı katmanlarını geliştirici kurar.

Kurulum ve sürüm durumu

8 Ağustos 2026’da PyPI ve GitHub’daki son kararlı sürüm 1.26.0’dı; 29 Mayıs’ta yayımlanan etiket 12c1bc8 commitine işaret ediyor. Paket Python 3.10 veya üstünü istiyor. Testte uv, Python 3.12.13 ve macOS arm64 kullandım. LiteLLM eklentisiyle birlikte 54 paket kuruldu. Sürümü sabitlemek, daha sonra gelen bağımlılık değişikliklerinin sonucu sessizce değiştirmesini önler.

mkdir smolagents-lab && cd smolagents-lab
uv venv --python 3.12
uv pip install --python .venv/bin/python \
  'smolagents[litellm]==1.26.0'
ollama pull qwen3.5:4b

Ollama modeli daha önce yerel makinede bulunduğu için test sırasında ağırlık indirmedim. Bir bulut modeline geçerseniz sağlayıcının API anahtarı, fiyatı, veri saklama koşulları ve bölgesi ayrıca devreye girer. smolagents deposu Apache-2.0 lisanslıdır; kullandığınız modelin ağırlıkları, araçların verileri ve harici hizmetler aynı lisansı paylaşmak zorunda değildir.

Adım adım gerçek kullanım: erişilebilir mekân seçimi

Senaryo, bir topluluk toplantısı için üç aday arasından mekân seçiyor. Beş zorunlu ölçüt belirledim: basamaksız giriş, işitme döngüsü, erişilebilir tuvalet, asansörlü toplu taşıma durağı ve durağın en fazla 150 metre uzakta olması. Veriler sentetikti; kişi adı, konum geçmişi veya gerçek işletme bilgisi içermiyordu.

  1. mekan_erisilebilirligi aracı giriş, işitme döngüsü, tuvalet ve bina içi mesafe kaydını döndürdü.
  2. erisilebilir_ulasim aracı durak mesafesi ile asansör durumunu verdi.
  3. İstemde ajandan her aday için iki aracı da kullanması, tahmin yürütmemesi ve tek mekân seçmesi istendi.
  4. max_steps=8 ile sonsuz veya gereksiz döngüye bir üst sınır koyuldu.
  5. Sonuç, ölçütlerin tümünü geçen tek adayla elle karşılaştırıldı.
import json
from smolagents import LiteLLMModel, ToolCallingAgent, tool

@tool
def mekan_erisilebilirligi(mekan: str) -> str:
    """Mekânın doğrulanmış erişilebilirlik kaydını getirir.

    Args:
        mekan: Tam mekân adı.
    """
    return json.dumps(MEKANLAR[mekan], ensure_ascii=False)

@tool
def erisilebilir_ulasim(mekan: str) -> str:
    """En yakın durağın erişilebilirlik kaydını getirir.

    Args:
        mekan: Tam mekân adı.
    """
    return json.dumps(ULASIM[mekan], ensure_ascii=False)

model = LiteLLMModel(
    model_id="ollama_chat/qwen3.5:4b",
    api_base="http://127.0.0.1:11434",
    num_ctx=8192,
)
agent = ToolCallingAgent(
    tools=[mekan_erisilebilirligi, erisilebilir_ulasim],
    model=model,
    max_steps=8,
)
sonuc = agent.run(GOREV)

Ajan ilk model adımında üç fiziksel erişilebilirlik kaydını, ikinci adımda üç ulaşım kaydını çağırdı. Üçüncü adımda Kent Atölyesi’ni seçti; Kuzey Salonu’nu işitme döngüsü olmaması ve durağın 260 metre uzakta olması, Tarihi Oda’yı basamaksız giriş, erişilebilir tuvalet ve asansör eksikleri nedeniyle eledi. Toplam süre 124,07 saniye, son günlükte kümülatif kullanım 5.602 giriş ve 1.947 çıkış belirteciydi. Yerel model para başına belirteç ücreti oluşturmadı; buna karşılık 4B model bile bu küçük görevde iki dakikayı geçti.

Mimari, model ve araç bağlantıları

Akış basit bir ReAct döngüsüdür: model mevcut görev ve geçmişi okur, bir veya birden çok araç çağrısı üretir, araç sonuçları belleğe eklenir, model yeni adımı planlar. LiteLLMModel Ollama, OpenAI uyumlu uç noktalar ve birçok bulut sağlayıcısını aynı katmanda bağlayabilir. Araçlar Python işlevleri olabildiği gibi Hugging Face Space, MCP sunucusu veya yönetilen başka bir ajan da olabilir. Bu esneklik, sağlayıcı değiştirmeyi kolaylaştırır; modelin araç çağırma şemasını gerçekten desteklediğini ayrıca test etmek gerekir.

Modelin izinleri, araca verdiğiniz işlevlerin toplamıdır. Salt okunur sözlük kullanan örnekte etki alanı küçüktü. Gerçek veritabanında araç hesabına yalnız gereken tabloları ve sorguları açın. E-posta gönderme, ödeme, dosya silme veya kayıt güncelleme gibi geri alınması zor eylemleri ayrı araçlara bölün; çalıştırmadan önce insan onayı ve idempotent istek anahtarı kullanın. Anahtarı isteme gömmeyin, çevre değişkeninden okuyun ve günlükte maskeleyin.

Arayüz ve erişilebilirlik notları

Temel kullanım bir terminal ve Python dosyası üzerinden ilerliyor; hesap açma, fareyle sürüklenen tuval veya zorunlu web arayüzü yok. Bu, klavye kullanıcıları için doğrudan bir yol sunuyor. Ancak varsayılan Rich günlüğü kutu çizgileri, simgeler ve uzun model metinleri üretiyor. Ekran okuyucu bunları gereksiz ayrıntıyla seslendirebilir. Üretimde verbosity_level değerini azaltın, son yanıtı ayrı bir düz metin bölgesine yazın ve hata mesajını yalnız renkle göstermeyin.

Testte araç adları ve parametreler metin olarak görünür, süre ile belirteç sayısı her adımın sonunda okunabilirdi. Sonuçtaki bozuk “ELİNE İNDE” ifadesi, erişilebilir arayüzün yalnız doğru HTML veya terminal çıktısı olmadığını gösteriyor; anlaşılır dil de kalite ölçütüdür. Tam ekran okuyucu testi ve isteğe bağlı Gradio arayüzü denenmedi. Gradio kullananlar, depodaki açık yapılandırılmış çıktı çökmesi kaydını sürüm yükseltmeden önce izlemeli.

Gözlemlenebilirlik ve hata kurtarma

Yerleşik günlük; görev, araç çağrısı, gözlem, adım süresi ve belirteçleri gösteriyor. agent.memory.steps hata incelemesi için programatik olarak okunabiliyor. Üretimde OpenTelemetry eklentisiyle Phoenix, MLflow veya Langfuse’a iz gönderilebiliyor. Bu izler istem, araç parametresi ve araç sonucunda kişisel veri taşıyabilir; toplamadan önce alanları ayıklayın, erişim rolü ve saklama süresi belirleyin.

Hata kurtarmayı modele bırakmak yeterli değildir. Her araca zaman aşımı, sınırlı yeniden deneme ve açık hata türü ekleyin. Boş kayıt ile “kayıt bulunamadı” durumunu ayırın. Ajan adım sınırına gelirse başarısız sayın; eski bir araç sonucuyla işlem yapmayın. Son yanıt için “bütün adaylarda iki araç çağrıldı mı?” ve “seçilen aday beş koşulu da sağlıyor mu?” kontrollerini kodla uygulayın. Modelin güzel bir açıklama üretmesi doğrulama değildir.

Güvenlik, gizlilik, maliyet ve lisans

Bu örnekte ToolCallingAgent kullandığım için model tarafından yazılmış Python kodu çalışmadı. CodeAgent seçerseniz durum değişir. Resmî README ve güvenlik politikası, LocalPythonExecutor bileşeninin bir güvenlik sınırı olmadığını açıkça söylüyor. Güvenilmeyen kod için Docker, E2B veya Modal gibi yalıtılmış arka uç; CPU, bellek, süreç ve ağ sınırı; ayrı kullanıcı ve temizleme adımı gerekir. 8 Ağustos’ta depoya özgü yayımlanmış GitHub güvenlik duyurusu görünmüyordu; bu, risk olmadığı anlamına gelmez.

Yerel koşumda görev metni ve araç verileri 127.0.0.1 üzerindeki Ollama’ya gitti; Hugging Face hesabı veya API anahtarı kullanılmadı. Böylece belirteç başı bulut ücreti ve üçüncü tarafa istem aktarımı oluşmadı. Donanım, elektrik ve bakım maliyeti devam eder. Bulut modelinde hem model çağrıları hem uzak sandbox ayrı ücret çıkarabilir. Apache-2.0 lisansı yazılımı kullanma, değiştirme ve dağıtmaya izin verir; telif, lisans ve değişiklik bildirimlerini koruma yükümlülüğü vardır. Model, veri ve hizmet koşullarını ayrıca okuyun.

Bakım durumu ve alternatiflerle karşılaştırma

Depo terk edilmiş görünmüyor: 1.26.0 sürümünden sonra ana dalda 11 Temmuz’a kadar CI ve güvenlik politikası güncellemeleri var. Bununla birlikte GitHub sorgusu 282 açık ve 537 kapalı issue gösterdi. Güncel açık kayıtlarda MCP 2.0 uyumsuzluğu, artan adımlarda yaklaşık karesel belirteç maliyeti, paralel araç hatasında başarılı sonuçların da kaybolması ve yerel çalıştırıcı zaman aşımı sorunları bulunuyor. Bu sayılar ve yıldızlar tek başına kalite kanıtı değildir; sürümünüzü temsil eden issue’ları okuyup kendi kabul testinizi çalıştırın.

  • smolagents: En küçük kavramsal yüzey ve hızlı Python prototipi güçlü yanı. Hazır işletim paneli ve yönetişim katmanı sunmuyor.
  • LangGraph: Kalıcı durum, dallanma ve uzun yaşayan akışlarda daha açık grafik denetimi sağlar; başlangıç kodu ve kavram sayısı daha fazladır.
  • AutoGen: Birden fazla konuşan ajan ve olay tabanlı uygulamalar için daha geniş bir çerçevedir; tek araç ajanı için gereğinden ağır olabilir.
  • Dify/Flowise: Görsel düzenleme ve ekip arayüzü sunar. Ekran okuyucu yükü, sunucu bakımı ve platformun veri/lisans koşulları ayrıca değerlendirilmelidir.

Sınırlamalar ve sorun giderme

  • Ollama bağlantısı reddediliyor: ollama list ile sunucuyu doğrulayın; konteyner içindeki 127.0.0.1 ana makineyi göstermez.
  • Model araç çağırmıyor: Araç açıklamalarını ve argüman türlerini sadeleştirin; kullandığınız modelin yapılandırılmış araç çağırmayı desteklediğini sınayın.
  • Ajan döngüye giriyor: max_steps, araç zaman aşımı ve son yanıt kontrolleri koyun. Aynı çağrının yinelenmesini günlükten yakalayın.
  • Türkçe bozuluyor: Daha güçlü veya Türkçe değerlendirilmiş model deneyin; son metni insan denetimine ya da dil kalite kuralına gönderin.
  • Bağımlılık güncellemesi kırıyor: smolagents ile model bağlayıcısını sabitleyin, kilit dosyası kullanın ve yükseltmeyi ayrı ortamda test edin.

Bu laboratuvar tek koşum, üç aday ve sentetik veriyle sınırlıydı. Gerçek veri tabanı, MCP, web arama, CodeAgent, sandbox, çoklu ajan, Gradio, bulut modeli ve ekran okuyucu denenmedi. Doğru tek sonuç; doğruluk oranı, güvenlik veya üretime hazır olma kanıtı değildir.

Kaynaklar

Test kapsamı: smolagents 1.26.0 ve LiteLLM bağımlılıkları geçici uv ortamına gerçekten kuruldu; yerel Qwen3.5 4B ile iki salt-okunur aracın altı çağrısı ve uçtan uca seçim çalıştırıldı. Geçici ortam ve test dosyaları doğrulama sonrasında kaldırıldı.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir

✅ Uygulama Başarıyla Güncellendi!
🟢 Profil Uygulandı