Qwen-Agent ile Yerel Bir Araç Ajanı Kurma: Ollama ile Uçtan Uca Test

by

Kısa sonuç: Qwen-Agent, bir dil modelini kendi yazdığınız araçlarla, belge aramayla, MCP sunucularıyla ve web arayüzüyle birleştiren Apache-2.0 lisanslı bir Python çerçevesi. 30 Temmuz 2026 tarihli uygulamalı testte Qwen-Agent 0.0.34’ü Ollama’daki yerel Qwen3 8B modeliyle çalıştırdım; ajan iki sayıyı toplamak için tanımlanan aracı çağırdı, aracın 42 sonucunu aldı ve Türkçe yanıt üretti. Ancak kurulum bağımlılıkları beklenenden pürüzlüydü ve depoda üretim kullanımını doğrudan ilgilendiren açık güvenlik bildirimleri var. Bu nedenle aşağıdaki örnek dar izinli, çevrimdışı ve zararsız bir araçla sınırlı.

Qwen-Agent ne işe yarar, kimler için?

Alibaba’nın Qwen ekibi tarafından geliştirilen Qwen-Agent, model ile araç arasına bir orkestrasyon katmanı koyuyor. Temel yapı üç parçalı: LLM sınıfı modele bağlanıyor; BaseTool tabanlı araçlar dış işlevleri tanımlıyor; Assistant gibi ajan sınıfları konuşma geçmişini, araç seçimini ve sonuçların modele geri verilmesini yönetiyor. Resmî depo; işlev çağırma, RAG, MCP, kod yorumlayıcı ve Gradio tabanlı web arayüzünü desteklediğini belirtiyor.

Çerçeve özellikle Qwen modellerini yerelde ya da OpenAI uyumlu bir sunucuda kullanmak, özel bir iş aracını modele açmak veya belgelere dayalı bir asistan prototiplemek isteyen Python geliştiricilerine uygun. Hazır bir tüketici uygulaması arayanlar için fazla teknik; üretimde çok kiracılı ve güçlü izolasyon isteyen ekipler içinse tek başına yeterli bir güvenlik sınırı değil.

Başlamadan önce: sürüm, lisans ve bakım durumu

PyPI’de güncel paket 0.0.34 ve yükleme tarihi 16 Şubat 2026. GitHub’daki “Releases” bölümü ise hâlâ 29 Mayıs 2025 tarihli 0.0.26’yı son sürüm olarak gösteriyor. Ana dalın son görülen kod değişiklikleri Şubat-Mart 2026’da Qwen3.5 örneği ve DeepPlanning güncellemeleri etrafında. Yani proje tamamen terk edilmiş görünmüyor; fakat GitHub sürümleri ile PyPI paketi senkron değil ve yüzlerce açık issue/PR bulunuyor. Sürümü sabitlemek, değişiklik günlüğünü ayrı ayrı kontrol etmek ve yükseltmeyi otomatikleştirmemek akıllıca.

Depodaki gerçek LICENSE dosyası Apache License 2.0 metnini içeriyor. Bu lisans genel olarak kullanma, değiştirme ve dağıtmaya izin verir; telif, lisans ve gerekiyorsa değişiklik bildirimlerini koruma yükümlülüğü getirir. Fakat Qwen-Agent lisansı, kullandığınız Qwen model ağırlıklarını, veri kümelerini, üçüncü taraf MCP sunucularını veya DashScope hizmetini otomatik olarak aynı lisansa sokmaz. Her bileşenin koşullarını ayrıca okuyun.

Kurulum: izole ortam ve yerel model

Üretim makinenizin sistem Python’una doğrudan paket kurmayın. Python 3.10 veya 3.11 ile sanal ortam oluşturun. Resmî README, GUI için en az Python 3.10 istiyor. Benim Python 3.9 testimde temel pip install qwen-agent komutu, paket içe aktarılırken numpy, ardından soundfile ve python-dateutil eksikleriyle durdu. 0.0.34’ün paket metadatası bu zorunlu içe aktarımları eksiksiz yansıtmıyor. Aşağıdaki komut, testte gereken ekleri açıkça kuruyor:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install "qwen-agent[python-executor]==0.0.34" soundfile

python-executor ekini kurmak, o aracı ajana otomatik olarak vermiyor; fakat bağımlılıkları getiriyor. Yine de üretimde ihtiyaç duymadığınız araçları function_list listesine eklemeyin. Yerel model için Ollama’yı kurup modeli indirin:

ollama pull qwen3:8b
ollama list

Ollama’nın OpenAI uyumlu uç noktası varsayılan olarak http://localhost:11434/v1 adresinde. Bu yol, istem ve araç sonuçlarını DashScope’a göndermeden yerelde işlemeyi sağlıyor. Yerel çalışmak “otomatik olarak güvenli” demek değil: model dosyası birkaç gigabayt yer kaplar, bellek ve enerji tüketir; Ollama’yı ağ arayüzlerine açarsanız erişim denetimi ayrıca gerekir.

Adım adım gerçek kullanım: dar izinli toplama aracı

Bu senaryoda kullanıcı “17,25 ile 24,75’i topla” diyor. Modelin kendi zihinsel hesabına güvenmek yerine yalnız iki sayıyı alan bir araç tanımlıyoruz. Araç dosya okumuyor, kabuk komutu çalıştırmıyor ve ağa çıkmıyor.

import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool

@register_tool("topla")
class Topla(BaseTool):
    description = "İki sayıyı güvenli biçimde toplar."
    parameters = [
        {"name": "a", "type": "number", "required": True},
        {"name": "b", "type": "number", "required": True},
    ]

    def call(self, params: str, **kwargs) -> str:
        veri = json5.loads(params)
        return json5.dumps({"sonuc": veri["a"] + veri["b"]})

llm_cfg = {
    "model": "qwen3:8b",
    "model_server": "http://localhost:11434/v1",
    "api_key": "EMPTY",
    "generate_cfg": {"temperature": 0, "max_tokens": 512},
}

bot = Assistant(
    llm=llm_cfg,
    function_list=["topla"],
    system_message="Toplamayı mutlaka topla aracıyla yap."
)

mesajlar = [{"role": "user",
             "content": "17,25 ile 24,75 sayılarını topla."}]
for yanit in bot.run(messages=mesajlar):
    son_yanit = yanit
print(son_yanit)

Testte akış üç adım üretti: ajan topla aracını 17.25 ve 24.75 argümanlarıyla çağırdı; araç 42.0 döndürdü; ajan “17,25 ile 24,75 sayılarının toplamı 42,0’dır” yanıtını verdi. İlk denemede Qwen3.5 4B ile yerel sunucunun yerel araç şeması uyumsuzluğu ve uzun döngü gözlendi; Qwen3 8B’nin Qwen-Agent’ın istem tabanlı araç çağırma yolu başarılı oldu. Dolayısıyla “OpenAI uyumlu” etiketi, her model-sunucu-çerçeve birleşiminin araç şemasında kusursuz çalışacağı anlamına gelmiyor.

Arayüz ve erişilebilirlik notları

Qwen-Agent, WebUI(bot).run() ile Gradio arayüzü açabiliyor. Tipik akışta üstte uygulama başlığı, ortada konuşma geçmişi, altta metin giriş alanı ve gönderme denetimi bulunuyor; dosya işlevi etkinse ayrıca yükleme denetimi görünüyor. Klavye kullanıcıları giriş alanına, gönder düğmesine ve dosya seçicisine mantıklı sırayla ulaşabilmeli. Ekran okuyucuyla testte özellikle araç çalışırken oluşan durum mesajlarının canlı bölge olarak duyurulması, yalnız renk veya animasyonla verilmemesi ve model cevabının odağı zorla taşımaması kontrol edilmeli.

Gradio sürümü, tema ve eklediğiniz özel bileşenler bu davranışı değiştirebilir; Qwen-Agent erişilebilirlik uygunluğunu garanti etmiyor. Web arayüzünü internete açmadan önce anlamlı denetim adları, görünür odak, hata metinleri, yüzde 200 yakınlaştırma, 320 piksel genişlik ve ekran okuyucu akışını kendiniz sınayın. Dosya yükleme açıksa kabul edilen türleri ve verinin nereye gittiğini açıkça yazın.

Gözlemlenebilirlik, hata kurtarma ve maliyet

Örnek çıktı, model mesajı, araç çağrısı, araç sonucu ve son yanıtı ayrı roller halinde gösteriyor. Bu ayrım denetim kaydı için iyi bir başlangıç. Üretimde her çağrıya ilişki kimliği ekleyin; araç adı, süre, başarı durumu ve insan onayını kaydedin, fakat API anahtarlarını ve kişisel veriyi loglamayın. Araç zaman aşımında sınırlı yeniden deneme, salt okunur geri dönüş ve kullanıcıya açık hata mesajı tanımlayın. Para transferi, dosya silme veya dışarı mesaj gönderme gibi işlemler model kararıyla otomatikleşmemeli.

Yerel Ollama kullanımında istek başına bulut ücreti yok; maliyet donanım, elektrik, bellek ve bakım olarak gelir. DashScope kullanılırsa hesap, API anahtarı, bölgesel erişim ve modele göre ücret gerekir. Çin ana kara ile uluslararası uç noktaların erişim, fiyat ve veri işleme koşulları farklı olabilir. Bu yazı DashScope’a veri göndermedi; veri konumu ve saklama koşulları seçtiğiniz hizmet sözleşmesinden ayrıca doğrulanmalı.

Güvenlik ve gizlilik: en önemli sınırlamalar

30 Temmuz 2026 itibarıyla depoda resmî bir SECURITY.md bulunmuyor ve GitHub Security Advisories listesi boş görünüyor. Bu, açık olmadığı anlamına gelmez. Açık issue 866, PythonExecutor içindeki exec/eval kullanımının üretimde ana makinede keyfî kod çalıştırmaya yol açabileceğini bildiriyor; düzeltme PR’ı 886 birleştirilmeden kapatılmış. README de eski Python yürütücüsünün korumalı olmadığını, yeni kod yorumlayıcının Docker tabanlı temel izolasyon kullandığını ve yine dikkat gerektirdiğini söylüyor.

Açık issue 923 ise MCP yapılandırmasında iç ağa istek gönderme, alt sürece ortam değişkeni sızdırma ve araç yanıtıyla istem enjeksiyonu risklerini bildiriyor. Temmuz sonunda SSRF ve yerel dosya erişimini sınırlamaya çalışan PR’lar açık durumda. Bu nedenle güvenilmeyen MCP sunucusu bağlamayın; alt sürece boş ve açıkça seçilmiş bir ortam verin; sırları ana süreç ortamında toplamayın; URL ve dosya yollarını izin listesiyle kısıtlayın; kod aracını ayrı, ağsız ve geçici bir konteynerde çalıştırın.

Alternatiflerle kısa karşılaştırma

LangGraph, düğüm-kenar tabanlı durum makineleri ve kalıcı iş akışlarında daha kontrollü bir yapı sunar; model sağlayıcısından daha bağımsızdır. AutoGen, birden fazla ajanın konuşması ve ekip benzeri düzenler için daha zengin örneklere sahiptir. CrewAI, rol ve görev odaklı hızlı başlangıcı öne çıkarır. Qwen-Agent’ın avantajı Qwen araç çağırma şablonları, belge akışı ve yerel/uyumlu sunucu seçeneklerinin aynı projede bulunması. Dezavantajı, paketleme pürüzleri ile açık güvenlik konularının üretim öncesi daha fazla mühendislik istemesidir.

Sorun giderme kontrol listesi

  • ModuleNotFoundError: numpy/soundfile/dateutil: sanal ortamda yukarıdaki sabitlenmiş komutu uygulayın; pip check çalıştırın.
  • Araç şeması için HTTP 400: use_raw_api ayarını kaldırıp Qwen-Agent’ın istem tabanlı araç çağırmasını deneyin; sunucunun beklediği JSON Schema biçimini doğrulayın.
  • Ajan aynı çağrıyı tekrarlıyor: tur sayısını ve süreyi sınırlandırın, araç sonucuna açık başarı alanı ekleyin, küçük model yerine araç çağırmada doğruladığınız modeli kullanın.
  • Yanıt çok yavaş: daha küçük model, daha kısa bağlam ve düşük max_tokens deneyin; bunun doğruluk ve araç seçimi başarısını düşürebileceğini ölçün.
  • GUI açılmıyor: Python 3.10+ ve README’de sabitlenen Gradio bağımlılıklarını kullanın; portun yalnız yerel arayüze bağlı olduğunu kontrol edin.

Sonuç

Qwen-Agent ile yerel bir Qwen modeline gerçek araç kullandırmak mümkün ve temel desen anlaşılır: en küçük yetkiyle aracı tanımla, yalnız gereken aracı ajana ver, her çağrıyı kaydet ve sonucu doğrula. Fakat 0.0.34’ü “kur ve üretime aç” paketi olarak görmek doğru değil. Bugünkü en güvenli kullanım alanı, yerel ağda, sentetik verilerle, kabuk/dosya/MCP yetkisi vermeden yapılan prototipler. Üretim için bağımlılıkları sabitleyin, açık güvenlik konularının durumunu yeniden kontrol edin ve kod yürütmeyi ana makineden kesin olarak ayırın.

Kaynaklar

Editoryal test notu: Kurulum ve uçtan uca özel araç çağrısı Apple Silicon macOS üzerinde, yerel Ollama ve Qwen3 8B ile gerçekten çalıştırıldı. DashScope, Gradio GUI, RAG, MCP ve kod yorumlayıcı çalıştırılmadı. Metin README’nin çevirisi değildir; kaynaklar, depo durumu ve gözlenen test sonuçları özgün olarak sentezlenmiştir.

İlgili içerikler

Bir yanıt yazın

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