Claude Yönetilen Agent'lar ve Agent SDK (2026): Hangisini Seçmeli?

Claude üzerinde üretim yapay zeka aracısı yayınlayacaksanız ilk mimari karar şudur: aracı döngüsünü ve sanal alanı Claude Yönetilen Aracılar ile Anthropic’e mi bırakacaksınız, yoksa Claude Aracı SDK’sı ile döngüyü kendi sürecinizde mi çalıştıracaksınız? Demo seviyesinde iki seçenek benzer görünür; üretimde ise maliyet, veri yerleşimi, gözlemlenebilirlik ve nöbet sorumluluğu farklılaşır. Bu yazıda ödeme-iade aracısı ve destek bileti aracısı örnekleri üzerinden pratik karar çerçevesi kuracağız.

Apidog'u bugün deneyin

TL;DR

Claude Yönetilen Aracılar’ı seçin: Anthropic’in aracı döngüsünü, oturum durumunu ve sanal alanı barındırmasını istiyorsanız; özellikle uzun süren veya eşzamansız işler için altyapı işletmek yerine çalışma süresi ücreti ödemeyi tercih ediyorsanız.

Claude Aracı SDK’sını seçin: döngüyü kendi sürecinizde çalıştırmak, araçlar üzerinde tam kontrol sahibi olmak, veriyi kendi ortamınızda tutmak ve çalışma maliyetini kendi altyapınızla yönetmek istiyorsanız.

Her iki seçenek de Claude modellerini ve MCP’yi destekler.

Giriş

2026’da “yapay zeka aracısı oluşturmak”, artık yalnızca sohbet tamamlama etrafına bir while döngüsü koymak anlamına gelmiyor. Anthropic, üretim aracısı çalıştırmak için iki farklı yol sunuyor:

• Claude Aracı SDK’sı: Python veya TypeScript servisinize eklediğiniz bir kütüphane. Aracı döngüsü, bağlam yönetimi ve yerleşik araçlar sizin sürecinizde çalışır.
• Claude Yönetilen Aracılar: Anthropic’in aracı döngüsünü ve oturum başına sanal alanı çalıştırdığı barındırılan REST API. Uygulamanız olay gönderir, sonuçları akışla alır.

Bu seçim yalnızca kod organizasyonunu değil, şunları da belirler:

• Müşteri verisi nerede duracak?
• Bir araç çağrısı takıldığında kim müdahale edecek?
• Oturum geçmişi nasıl saklanacak?
• Maliyet token bazlı mı, çalışma süresi bazlı mı, yoksa altyapı maliyeti olarak mı görünecek?

Üretim aracılarının çoğu gerçek işi API çağırarak yapar: ödeme iadesi, Zendesk bileti oluşturma, envanter sorgulama, dahili fiyatlandırma servisine erişme. Bu nedenle aracınızın güvenilirliği büyük ölçüde çağırdığı API’lerin güvenilirliğidir.

Bu noktada Apidog gibi bir platform kullanışlıdır: aracınızın bağımlılıklarını taklit edebilir, sözleşme testleri çalıştırabilir ve MCP sunucularını aracının kullanacağı şekilde test edebilirsiniz. Barındırılan tarafı daha derin incelemek isterseniz Claude Yönetilen Aracılar rehberimize bakabilirsiniz.

Claude Yönetilen Aracılar Nedir?

Claude Yönetilen Aracılar, Anthropic tarafından yönetilen altyapıda çalışan yapılandırılabilir bir aracı çalışma zamanıdır. Kendi aracı döngünüzü, sanal alanınızı ve araç yürütme katmanınızı yazmak yerine bir aracı tanımlarsınız; Anthropic oturumu çalıştırır.

Nisan 2026’da genel beta olarak duyuruldu ve her istekte SDK’nın sizin için ayarladığı şu beta başlığını gerektirir:

managed-agents-2026-04-01

Temel kavramlar:

• Aracı: model, sistem istemi, araçlar, MCP sunucuları ve beceriler.
• Ortam: Python, Node.js, Go gibi paketleri ve ağ erişim kurallarını içeren kapsayıcı şablonu.
• Oturum: belirli bir ortamda çalışan ve tek bir görevi yürüten aracı örneği.
• Olaylar: uygulamanız ile aracı arasında akan kullanıcı mesajları, araç sonuçları ve durum güncellemeleri.

Tipik akış:

1. Aracıyı oluşturun.
2. Ortamı yapılandırın.
3. Oturum başlatın.
4. Kullanıcı mesajlarını olay olarak gönderin.
5. Yanıtları SSE üzerinden akışla alın.
6. Gerektiğinde yeni olaylarla aracıyı yönlendirin veya durdurun.

Yönetilen Aracılar, Claude’a hazır araçlar sağlar:

• Bash
• Dosya okuma/yazma/düzenleme
• Glob ve grep
• Web arama ve getirme
• MCP sunucu bağlantıları

Bu seçenek en çok şu iş yüklerine uyar:

• Dakikalar veya saatler sürebilen işler
• Çok sayıda araç çağrısı yapan görevler
• Eşzamansız arka plan işleri
• Sizin tarafınızda minimum altyapı isteyen ekipler
• Oturumlar arasında durumun korunmasını isteyen akışlar

Dikkat edilmesi gereken iki nokta var:

1. Özel araç yürütmesi hâlâ sizin tarafınızdadır. Claude bir aracı çağırmaya karar verir; uygulamanız aracı çalıştırır ve sonucu olay akışına geri gönderir.
2. Bazı özellikler araştırma önizlemesindedir. Çıktılar ve çoklu aracı gibi özellikler ayrı erişim isteği gerektirebilir.

Döngü, araçlar ve bellek modelinin genel mimarisi için ajanik yapay zeka mimarisi yazımıza da bakabilirsiniz.

Claude Aracı SDK’sı Nedir?

Claude Aracı SDK’sı, Claude Code’un aracı döngüsünü, araçlarını ve bağlam yönetimini Python ve TypeScript içinde kullanmanızı sağlayan kütüphanedir. Daha önce Claude Code SDK olarak biliniyordu; yeniden adlandırma, kullanım alanının kodlama dışına genişlediğini gösterir.

Kurulum örnekleri:

pip install claude-agent-sdk

npm install @anthropic-ai/claude-agent-sdk

SDK ile döngü sizin sürecinizde çalışır. Python tarafında genel akış şu şekildedir:

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"]
)

async for message in query(
    prompt="Bu repoda testleri çalıştır ve başarısız olanları düzelt.",
    options=options,
):
    print(message)

Buradaki fark şudur: düz Client SDK kullanırken genellikle tool_use durumunu yakalayıp her aracı kendiniz çalıştırırsınız. Aracı SDK’sı bu döngüyü hazır getirir.

SDK’nın sunduğu ana mekanizmalar:

• Yerleşik araçlar: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Watch ve AskUser.
• Kancalar: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit gibi yaşam döngüsü noktalarında doğrulama, loglama veya engelleme.
• Alt aracılar: odaklanmış alt görevler için özelleşmiş aracılar.
• MCP desteği: veritabanları, tarayıcılar ve API’leri Model Context Protocol üzerinden bağlama.
• İzinler: güvenli araçları önceden onaylama, riskli araçları engelleme veya insan onayı isteme.
• Oturumlar: oturum kimliğini yakalama, devam ettirme veya çatallama.

Örneğin ödeme iadesinde insan onayı zorunlu kılmak için PreToolUse benzeri bir kanca mantığı kullanabilirsiniz:

async def pre_tool_use_hook(tool_name, tool_input):
    if tool_name == "refund_payment":
        amount = tool_input.get("amount", 0)

        if amount > 1000:
            raise PermissionError("1000 üzerindeki iadeler insan onayı gerektirir.")

    return tool_input

SDK ayrıca Claude Code’un dosya sistemi yapılandırmasını okuyabilir:

• .claude/skills/
• Slash komutları
• CLAUDE.md
• Eklentiler

Kimlik doğrulama tarafında doğrudan Anthropic API’sinin yanında Amazon Bedrock, AWS üzerindeki Claude Platformu, Google Vertex AI ve Azure AI Foundry seçenekleri de desteklenir. Kurulum adımları için Claude planıyla Claude Aracı SDK’sını kurma ve kendi Claude Kodunuzu oluşturma rehberlerine bakabilirsiniz.

Planlama notu: 15 Haziran 2026’dan itibaren abonelik planlarındaki Aracı SDK’sı ve claude -p kullanımı, etkileşimli kullanım limitlerinden ayrı bir aylık Aracı SDK kredi havuzundan çekilecektir. Bütçe yapmadan önce güncel şartları Anthropic kaynağından doğrulayın.

Karşılaştırma: Yönetilen Aracılar ve Aracı SDK’sı

Mimari değerlendirme için pratik tablo:

Canlı maliyetler için Anthropic fiyatlandırma sayfasını ve Yönetilen Aracılar belgelerini kontrol edin.

Maliyet

Yönetilen Aracılar, standart Claude token ücretlerine ek olarak aktif oturum süresi için ücret alır. Araç çağrıları arasında bekleyen bir aracı bile oturum süresi biriktirebilir.

SDK’da Anthropic tarafında saatlik çalışma ücreti yoktur; ancak sunucu, otomatik ölçeklendirme, izleme ve nöbet maliyeti size aittir.

Operasyonel yük

Yönetilen Aracılar şu işleri sizden alır:

• Sanal alan işletme
• Oturum deposu yönetme
• İşçi ölçeklendirme
• Olay günlüğü saklama

SDK ise bunları sizin kontrolünüze verir. Bu, VPC içinde çalışması gereken aracılar için avantajdır; küçük ekipler için ek yük olabilir.

Veri yerleşimi

Veri yerleşimi çoğu zaman kararı doğrudan belirler.

• SDK: araç yürütmesi ve oturum durumu kendi altyapınızda kalır.
• Yönetilen Aracılar: sanal alan ve olay günlüğü Anthropic ortamında veya desteklenen AWS seçeneğinde bulunur.

Düzenlenmiş veri, finansal işlem veya özel ağ gereksinimleri varsa SDK daha doğal seçimdir.

Gözlemlenebilirlik

Yönetilen Aracılar size alınabilir olay günlüğü sağlar. SDK’da aynı seviyeyi elde etmek için hook’ları kendi gözlemlenebilirlik yığınınıza bağlamanız gerekir.

Örneğin SDK ile araç çağrılarını loglamak:

async def post_tool_use_hook(tool_name, tool_input, tool_result):
    logger.info(
        "tool_used",
        extra={
            "tool": tool_name,
            "input": tool_input,
            "result_status": tool_result.get("status"),
        },
    )

Aracılarınızın Çağırdığı API’leri Test Etme ve Hata Ayıklama

Hangi barındırma modelini seçerseniz seçin, aracınız çağırdığı API’ler kadar güvenilirdir. İyi akıl yürüten ama hatalı ödeme endpoint’ine istek atan bir iade aracısı hâlâ hatalıdır.

Yayınlamadan önce üç katmanı test edin.

1. API sözleşmeleri

Aracınızın çağırdığı her araç aslında şeması olan bir API’dir. Bu API’ler için:

1. Mock servis oluşturun.
2. İstek ve yanıt şemalarını tanımlayın.
3. Sözleşme testlerini CI içinde çalıştırın.
4. Gerçek servis mock’tan saparsa dağıtımı engelleyin.

Apidog ile ödeme veya biletleme servisini taklit edebilir, aracının beklediği şemayı tanımlayabilir ve sözleşme testleri çalıştırabilirsiniz. Detaylı yaklaşım için API’leri çağıran yapay zeka aracılarını nasıl test edeceğinize dair rehbere bakabilirsiniz.

2. MCP sunucuları

Her iki seçenek de harici araçları MCP üzerinden bağlayabilir. MCP sunucularında sık görülen hatalar:

• Araç çıktısının beklenen şemadan sapması
• Timeout davranışının belirsiz olması
• Hata yanıtlarının yapılandırılmış veri yerine düz metin dönmesi
• Aynı aracın farklı durumlarda farklı alanlar döndürmesi

Canlı aracıya bağlamadan önce MCP sunucusunu doğrudan test edin. Apidog ile MCP sunucusu testi rehberi, sunucunun açığa çıkardığı araçları listelemeyi ve her birini çalıştırmayı gösterir.

3. Aracının gerçek istek davranışı

Aracılar API’leri insanlardan farklı kullanır:

• Peş peşe yeniden deneme yapabilir.
• Aynı endpoint’i kısa sürede birçok kez çağırabilir.
• Kısmi veriyle karar verebilir.
• Timeout sonrası işlemi yeniden başlatabilir.

Bu nedenle geçmiş veya sentetik görevleri mock servislerinize karşı tekrar oynatın. Aracının gerçekten ne gönderdiğini inceleyin.

Örneğin ödeme iadesi için test matrisi:

Yönetilen Aracılar döngüyü gizlediği için görünürlüğünüz olay günlüğü ve API testleri üzerinden gelir. SDK döngüyü açtığı için hook’larla daha fazla enstrümantasyon yapabilirsiniz; ancak yine de API düzeyindeki testlere ihtiyacınız vardır.

Başlamadan önce Apidog’u indirin ve aracıyı gerçek müşteriye bağlamadan bağımlılıklarını test edin.

Karar Çerçevesi

Özellik listesini tek tek karşılaştırmak yerine aşağıdaki soruları sırayla yanıtlayın.

Claude Yönetilen Aracılar’ı seçin, eğer:

• Aracınız dakikalar veya saatler süren eşzamansız işler yapıyorsa.
• İş yürütücüsü, sanal alan ve oturum deposu işletmek istemiyorsanız.
• Küçük bir ekipseniz ve operasyonel yük en büyük kısıtsa.
• Barındırılan, alınabilir olay günlüğü istiyorsanız.
• Veri ve uyumluluk gereksinimleriniz Anthropic veya desteklenen AWS ortamında oturum durumuna izin veriyorsa.
• Beta durumunu ve bazı özelliklerin erişim isteği gerektirmesini kabul ediyorsanız.

Claude Aracı SDK’sını seçin, eğer:

• Aracı VPC içinde, özel veritabanı veya dahili servislerin yanında çalışmak zorundaysa.
• Oturum durumunun üçüncü taraf sanal alanda tutulmasını istemiyorsanız.
• İnce taneli kontrol gerekiyorsa: izinler, hook’lar, denetim, süreç içi araç mantığı.
• Veri yerleşimi veya regülasyon gereksinimleri barındırılan sanal alanı dışlıyorsa.
• Çıkarımı Bedrock, Vertex veya Azure üzerinden faturalandırmak istiyorsanız.
• Yerel prototipleme yapıyor ve aracının dosya sisteminizde çalışmasını istiyorsanız.

Yaygın geçiş yolu

Pratik yol genellikle şudur:

1. SDK ile yerelde prototip oluşturun.
2. Araçları, MCP sunucularını ve API sözleşmelerini sabitleyin.
3. Operasyonel yük ağır basıyorsa üretimde Yönetilen Aracılar’a geçin.

Ancak bu geçiş bir yapılandırma değişikliği değildir. Arayüzler, araç yürütme modeli ve oturum durumu farklıdır. Geçişi ayrı bir proje olarak planlayın.

Model veya kodlama aracıları da değerlendiriyorsanız 2026 için Claude ve Codex karşılaştırmamız tamamlayıcı olabilir.

Gerçek Dünya Kullanım Durumları

1. Ödeme İade Aracısı

Senaryo: Bir fintech destek ekibi, iade taleplerini uçtan uca işleyen aracı istiyor.

Aracının yapacağı işler:

1. Destek biletini oku.
2. İşlemi ödeme sisteminde ara.
3. İade politikasını kontrol et.
4. Gerekirse ödeme API’siyle iade başlat.
5. Bilete özet yaz.

Bu aracı para hareketi yaptığı için denetim izi ve sözleşme testi kritik.

Bu durumda SDK doğal seçimdir:

• Aracı ödeme servisinin yanında VPC içinde çalışabilir.
• Oturum durumu şirket altyapısından çıkmaz.
• PreToolUse hook’u ile belirli tutarın üzerindeki iadeler için insan onayı zorunlu kılınabilir.
• Tüm araç çağrıları iç denetim sistemine yazılabilir.

Yayın öncesi test akışı:

1. Apidog’da ödeme ve defter endpoint’lerini mock’layın.
2. İade, işlem arama ve defter kayıtları için sözleşme testleri yazın.
3. Geçmiş destek biletlerini mock servislere karşı tekrar oynatın.
4. Retry ve timeout davranışlarını gözlemleyin.

Bu testler özellikle şu hatayı yakalar: ödeme API’si 504 döner, ancak işlem arka planda gerçekleşmiştir; aracı aynı iadeyi tekrar başlatmamalıdır.

2. Eşzamansız Destek Bileti Ön Ayıklama Aracısı

Senaryo: Bir SaaS şirketi günde binlerce destek bileti alıyor. Aracıdan beklenenler:

• Bileti sınıflandırma
• İlgili logları çekme
• Yanıt taslağı hazırlama
• Basit durumları çözme
• Karmaşık durumları üst kademeye iletme

Biletler gün boyu gelir, her biri birkaç dakika araç çağrısı gerektirir ve veri düşük hassasiyetlidir.

Bu durumda Yönetilen Aracılar iyi uyum sağlar:

• İş eşzamansızdır.
• Ekip küçük olabilir.
• Otomatik ölçeklenen işçi filosu çalıştırmak istenmez.
• Barındırılan olay günlüğü bilet başına izleme sağlar.

Yine de API doğruluğu ekibin sorumluluğundadır. Loglama API’si ve bilet sistemi MCP sunucusu Apidog’da mock’lanmalı ve sözleşme testlerinden geçirilmelidir. Yönetilen çalışma zamanı altyapı yükünü azaltır; API kalitesini garanti etmez.

3. Güvenlik Duvarı Arkasında Dahili Veri Operasyonları Aracısı

Senaryo: Platform ekibi, şu tür istekleri çalıştıran dahili aracı istiyor:

“Dün başarısız olan ETL bölümlerini doldur.”

Aracının yapacağı işler:

1. Dahili iş API’sini sorgulama
2. Düzeltme betiği çalıştırma
3. Sonucu raporlama

Dahili API’ler internete açık değildir ve veri hassastır.

Bu durumda SDK varsayılan seçimdir:

• Aracı özel ağ içinde çalışmalıdır.
• Oturum durumu üçüncü taraf sanal alanda tutulmamalıdır.
• Dahili servisler MCP sunucuları olarak bağlanabilir.
• Her komut SDK hook’larıyla mevcut denetim hattına yazılabilir.

Bu, “SDK sizin sürecinizde çalışır” özelliğinin tercih değil gereklilik olduğu durumdur. Aracıların neden birincil API tüketicisi haline geldiğini anlamak için yapay zeka aracıları yeni API tüketicileri olarak yazısına bakabilirsiniz.

Uygulama Kontrol Listesi

Üretime çıkmadan önce şu listeyi tamamlayın:

• [ ] Aracının çağırdığı tüm API’leri listeleyin.
• [ ] Her API için istek/yanıt şeması tanımlayın.
• [ ] Mock servisleri oluşturun.
• [ ] Sözleşme testlerini CI’a ekleyin.
• [ ] MCP sunucularını aracıdan bağımsız test edin.
• [ ] Timeout ve retry senaryolarını simüle edin.
• [ ] İnsan onayı gerektiren aksiyonları belirleyin.
• [ ] SDK kullanıyorsanız hook’larla denetim izi üretin.
• [ ] Yönetilen Aracılar kullanıyorsanız olay günlüğü alma akışını test edin.
• [ ] Güncel fiyatlandırma ve beta durumunu Anthropic kaynağından doğrulayın.

Sonuç

Yönetilen Aracılar ile Aracı SDK’sı kararı, aslında operasyon ve veri yönetişimi kararıdır.

Özet:

• Yönetilen Aracılar döngüyü ve sanal alanı barındırır.
• SDK döngüyü sizin sürecinizde çalıştırır.
• Yönetilen Aracılar operasyonel yükü azaltır, ancak oturum durumu barındırılan ortamda yaşar.
• SDK daha fazla kontrol verir, ancak altyapı ve gözlemlenebilirlik sorumluluğu sizdedir.
• Veri yerleşimi çoğu zaman kararı belirler.
• Maliyet yalnızca fiyat tablosu değil; nöbet, ölçeklendirme ve bakım maliyetidir.
• Barındırma modelinden bağımsız olarak API ve MCP bağımlılıklarını test etmelisiniz.

Sonraki adım: aracıyı müşteriye dokunan herhangi bir sisteme bağlamadan önce bağımlılıklarını test edin. Endpoint’leri mock’lamak, sözleşme testleri çalıştırmak ve gerçek aracı trafiğini incelemek için Apidog’u indirin.

Sıkça Sorulan Sorular

Claude Yönetilen Aracılar ile Claude Aracı SDK’sı arasındaki temel fark nedir?

Yönetilen Aracılar, Anthropic’in aracı döngüsünü ve oturum başına sanal alanı çalıştırdığı barındırılan REST API’dir. Siz olay gönderir ve sonuçları akışla alırsınız.

Aracı SDK’sı ise aynı döngüyü kendi sürecinizde ve altyapınızda çalıştıran Python veya TypeScript kütüphanesidir.

Claude Aracı SDK’sı eski Claude Code SDK ile aynı mı?

Evet. Claude Code SDK, daha geniş kullanım alanını yansıtmak için Claude Aracı SDK olarak yeniden adlandırıldı. Aracı döngüsü, yerleşik araçlar ve bağlam yönetimi Claude Code ile aynı temele dayanır.

Hangi seçenek daha ucuz?

İş yüküne bağlıdır. Yönetilen Aracılar, standart token ücretlerine ek olarak aktif oturum süresi için çalışma ücreti alır. SDK’da bu çalışma ücreti yoktur; ancak kendi sunucu, ölçeklendirme ve operasyon maliyetinizi ödersiniz.

Bütçe yapmadan önce güncel fiyatları Anthropic’in fiyatlandırma sayfasından doğrulayın.

Her ikisiyle de MCP sunucuları kullanabilir miyim?

Evet. Her iki seçenek de harici araçları Model Context Protocol üzerinden bağlayabilir. Bu yüzden MCP sunucularını üretim aracısına bağlamadan önce test etmek önemlidir. Apidog ile MCP sunucusu testi rehberi bu süreci gösterir.

Müşteri verilerini Anthropic altyapısından nasıl uzak tutarım?

Claude Aracı SDK’sını kullanın ve döngüyü kendi ortamınızda çalıştırın. SDK ile araç yürütme ve oturum durumu altyapınızda kalır; yalnızca model çıkarımı Claude’a gider.

Yönetilen Aracılar’da sanal alan ve olay günlüğü Anthropic ortamında veya desteklenen AWS seçeneğinde yaşar.

Claude Yönetilen Aracılar üretim için hazır mı?

Nisan 2026’da genel beta olarak duyuruldu ve managed-agents-2026-04-01 beta başlığını gerektiriyor. Çekirdek oturum işlevselliği API hesapları için kullanılabilirken bazı özellikler ayrı araştırma önizleme erişimi gerektirebilir. Güncel durum için belgeleri kontrol edin.

Gerçek API’lere dokunmadan önce bir aracıyı nasıl test ederim?

Şu sırayı izleyin:

1. Aracının çağırdığı API ve MCP sunucularını mock’layın.
2. İstek ve yanıt şemaları için sözleşme testleri yazın.
3. Gerçekçi trafiği mock’lara karşı tekrar oynatın.
4. Aracının gerçekten ne gönderdiğini inceleyin.
5. Retry, timeout ve hata senaryolarını test edin.

Apidog; mock, sözleşme testi ve canlı aracı trafiğini inceleme akışlarını destekler. Detaylar için API’leri çağıran yapay zeka aracılarını nasıl test edeceğinize dair rehbere bakabilirsiniz.

Birinden başlayıp daha sonra diğerine geçebilir miyim?

Evet. Yaygın yol, SDK ile yerelde prototipleme yapıp daha sonra üretimde Yönetilen Aracılar’a geçmektir.

Ancak bu basit bir ayar değişikliği değildir:

• SDK kütüphane tabanlıdır; Yönetilen Aracılar REST + olay akışı kullanır.
• Özel araç yürütme modeli farklıdır.
• Oturum durumu dosya sisteminizden barındırılan olay günlüğüne taşınır.

Geçişi ayrı bir proje olarak planlayın.