Claude Agent SDK: Ne İşe Yarar ve Nasıl Değerlendirilir

Claude Agent SDK , Claude'un sınırlı, araç kullanan iş akışlarını çalıştırmasına olanak tanıyan uygulamalar oluşturmak için bir geliştirici arayüzüdür. SDK, oturumları yönetebilir, araçları çağırabilir ve işi koordine edebilir, ancak uygulama izinlerine, kaynak kontrollerine, değerlendirmeye veya insan onayına olan ihtiyacı ortadan kaldırmaz. Bunu eksiksiz bir üretim sistemi olarak değil, bir aracı çalışma zamanı bileşeni olarak ele alın.

Ajan çalışma ortamına sahip olmadan kaynak tabanlı çalışmaları tamamlaması gereken ekipler için Ottermind, yönetilen çalışma alanı yolunu sunar: bir kişi sonucu incelerken dosyaları, araştırma bağlamını, kararları ve teslim edilebilirleri birbirine bağlı tutun. SDK ve yönetilen bir çalışma alanı, farklı işletim sorunlarını çözer.

Araştırma ve açıklama: Bu kılavuz, 3 Eylül 2026 tarihinde incelenen Claude Agent SDK deposu, Anthropic alet kullanım dokümantasyonu ve AWS AgentCore Claude Agent SDK dokümantasyonu'e dayanmaktadır. API'ler ve sınırlar gelişmektedir; uygulamadan önce mevcut sürümü doğrulayın.

Temel yapı taşları

Geri alınabilir bir görevle başlayın

Onaylanmış depo dosyalarını bir değişiklik özetine dönüştürmek gibi okuma ağırlıklı bir iş akışının prototipini oluşturun. Giriş kümesini, istemi, model sürümünü, araç çağrılarını, çıktıyı, gözden geçiren düzeltmelerini ve nihai kararı yakalayın. İzleme anlaşılabilir hale geldikten ve hatalar kurtarılabilir olduktan sonra yalnızca yazma erişimi ekleyin.

Minimum görev sözleşmesi

Amaç: Kaynak koda dayalı bir uygulama özeti oluşturmak.
İzin verilen kaynaklar: Yalnızca ekli depo dosyaları.
İzin verilen araçlar: Dosya listeleme ve dosya okuma; yazma veya ağ çağrısı yok.
Çıktı: Bulgular, önerilen değişiklikler, kanıtlar, riskler ve açık sorular.
Durdurma zamanı: Gerekli bir kaynak eksikse veya izinler belirsizse.

Oturumlar ve alt aracılar

İş akışının birkaç adımda sürekliliğe ihtiyacı olduğunda oturum kullanın. Rol, araçlar veya değerlendirme kriterleri gerçekten farklı olduğunda yalnızca alt aracı kullanın. Daha fazla aracı, koordinasyonu, gecikmeyi ve hata yollarını artırır. Her rolün ihtiyaç duyduğu en küçük bağlamı iletin ve durum ve kanıtlarla yapılandırılmış sonuçlar döndürün.

Pratik bir mimari

SDK'yı beş sorumlulukla bir uygulama sınırının arkasında tutun:

1. İstek işleyici: Kullanıcıyı doğrular, izin verilen projeyi seçer ve bir bütçe belirler.
2. Bağlam yükleyici: Yalnızca izin verilen dosyaları alır ve tanımlayıcılarını ve tarihlerini kaydeder.
3. Ajan çalıştırıcı: Oturumu başlatır, araçları sağlar ve her araç isteğini ve sonucunu kalıcı hale getirir.
4. Politika katmanı: Argümanları doğrular, izin verilmeyen eylemleri engeller ve onay ister.
5. Sonuç adaptörü: Döndürülen şekli doğrular ve taslağı gözden geçirene veya bir sonraki sisteme iletir.

Bu ayrım önemlidir çünkü SDK, modelin bir araç talep etmesine yardımcı olabilir, ancak uygulamanız bu talebin izin verilip verilmeyeceğine karar verir. Yetkilendirme mantığını bir istem içine yerleştirmeyin veya bir modelin kiracı sınırlarını kendi başına koruyacağını varsaymayın.

Oturumlar, devam etme ve başarısızlık

Her çalıştırmaya completed, needs_review, blocked veya failed gibi açık bir tanımlayıcı ve son durum verin. Model ve SDK sürümünü, istem revizyonunu, giriş kaynaklarını, araç çağrılarını ve gözden geçirenin kararını saklayın. Yazma işleminden sonra bir ağ hatası oluşursa, tekrar denemeden önce bir idempotentlik anahtarı kullanın ve kayıt sistemini sorgulayın. Bir oturum insan düzenlemesinden sonra devam ederse, şeffaf olmayan bir konuşmayı yeniden oynatmak yerine, düzenlenmiş öğeyi ve değişikliğin nedenini ekleyin.

Araç tasarım örnekleri

Genel amaçlı bir kabuk aracı yerine create_draft_task(title, owner, due_date) gibi bir işlevi tercih edin. Dar işlev, tarih biçimlerini, izin verilen sahipleri, proje kapsamını ve yalnızca taslak durumunu uygulayabilir. Bir dosya arama aracı, dosya tanımlayıcılarını ve özetlerini döndürmeli, tüm sürücüyü sessizce ifşa etmemelidir. Bir tarayıcı aracı, izin verilenler listesini kullanmalı ve kimlik doğrulama veya ödeme öncesinde durmalıdır.

Maliyetler ve gecikme

Çalıştırma başlamadan önce bütçeleri belirleyin: maksimum model dönüşleri, araç çağrıları, tokenlar, geçen süre ve alt ajan sayısı. Kalite izin verdiğinde çıkarma işlemini daha küçük bir modele yönlendirin ve karmaşık akıl yürütmeyi belirsiz adımlar için saklayın. Başarılı bir demo, ekonomik olmayan bir iş akışını gizleyemesin diye, gerçek kullanımı sonuçla birlikte kaydedin. Uzun süren görevler eşzamansız, iptal edilebilir ve kullanıcı tarafından görülebilir olmalıdır.

SDK mı, yönetilen çalışma alanı mı?

Ekibinizin uygulamaya özgü araçlara, dağıtım kontrolüne veya özel bir çalışma zamanına ihtiyacı olduğunda ve güvenlik, gözlemlenebilirlik ve bakımı üstlenebildiğinde SDK ile geliştirin. Ana gereksinim dosyaları, araştırmaları, kararları ve teslim edilebilirleri insan incelemesi için bağlamak olduğunda, yönetilen bir çalışma alanı daha iyi bir başlangıç ​​noktasıdır. Seçim, hangi etiketin daha özerk göründüğüyle değil, işletme sorumluluğuyla ilgilidir.

Örnek: Araştırmadan özete ajan

Haftalık rakip özeti gerektiren bir ekibi düşünün. İstek işleyici, analistin kimliğini kontrol eder ve onaylanmış projeyi seçer. Bağlam yükleyici, kaynak listesini alır ve alma tarihini kaydeder. Ajan oturumu yalnızca search_approved_sources ve draft_brief'i çağırabilir. Politika katmanı, rastgele URL'ler, harici gönderiler veya proje dışındaki dosyalar için gelen istekleri reddeder. Sonuç adaptörü, taslağı bir gözden geçirene sunmadan önce bulgular, alıntılar, belirsizlik ve açık sorular için bölümler gerektirir.

Faydalı çıktı sadece son metin değildir. İz kaydıdır: hangi kaynaklar mevcuttu, hangi araçlar çağrıldı, ne engellendi, gözden geçiren neyi değiştirdi ve özet kabul edildi mi? Bu iz kaydı, model veya SDK değiştiğinde hata ayıklamayı, maliyet analizini ve tekrarlanabilir bir değerlendirme setini destekler.

Sürümleme ve Yükseltmeler

Her ortamda SDK ve model sürümlerini sabitleyin. İzin modlarındaki, araç şemalarındaki, oturum davranışındaki ve desteklenen modellerdeki değişiklikler için sürüm notlarını okuyun. Yükseltmeden önce, yasaklı araçların yasaklı kaldığını doğrulayan bir test de dahil olmak üzere, regresyon testlerini çalıştırın. Geri alma sürümünü hazır bulundurun ve bir geçiş planı olmadan uzun süren bir iş akışının ortasında yükseltme yapmaktan kaçının.

Üretim hazırlığı kontrol listesi

• Kimlik doğrulama ve kiracı kontrolleri, bağlam alınmadan önce gerçekleşir.
• Her aracın dar bir şeması, zaman aşımı ve yetkilendirme kontrolü vardır.
• Oturumların bütçeleri, iptali, sona ermesi ve sonlandırma durumları vardır.
• Çıktılar, kayıt sistemine ulaşmadan önce doğrulanır.
• Hassas işlemler, açık bir insan onayı olayını gerektirir.
• Günlükler, gizli bilgileri saklamadan bir hatayı yeniden oynatmak için yeterli kaynak bilgisi içerir.
• Değerlendirme durumları kalite, güvenlik, maliyet ve gecikmeyi kapsar.

İzin ve güvenlik sınırları

Uygulama kodunda araç argümanlarını doğrulayın. Kimlik bilgilerini istemlerin dışında tutun, dosya sistemi ve ağ erişimini kapsam içine alın, zaman aşımı sürelerini ayarlayın ve gönderme, silme, satın alma veya erişim değiştirme işlemleri için onay gerektirin. Her sonuç doğuran araç çağrısını, işlem yapan kimlik ve onay kararıyla birlikte kaydedin.

İş akışını değerlendirin, demoyu değil.

Normal, eksik, çelişkili, düşmanca ve izin hassasiyeti gerektiren durumlarla bir test seti oluşturun. Doğru tamamlama, güvenli yükseltme, araç hataları, gecikme, maliyet ve gözden geçiren düzeltmelerini ölçün. Her değerlendirme çalışması için model ve SDK sürümlerini sabitleyin.

SSS

Claude Agent SDK, Claude API araç kullanımıyla aynı mıdır?

Hayır. Araç kullanımı bir model etkileşim modelidir. SDK, aracı oturumları ve iş akışları için daha fazla uygulama düzeyinde yapı taşı sağlarken, uygulamanız hala politika, depolama, izinler ve değerlendirmeden sorumludur.

Birden fazla aracıya ihtiyacım var mı?

Genellikle ilk başta hayır. Dar araçlara ve açık kontrol noktalarına sahip tek bir aracı test etmek ve çalıştırmak daha kolaydır.

SDK dosyaları güvenli bir şekilde düzenleyebilir veya komutları çalıştırabilir mi?

Bu tür araçlara bağlanabilir, ancak güvenlik, sanal alanınızdan, izin listelerinden, doğrulama, inceleme ve geri alma tasarımınızdan gelir. Oluşturulan bir komutu asla önceden onaylanmış olarak değerlendirmeyin.

Daha geniş sistem sınırı için Yapay zeka aracı mimarisi ve Yapay zeka ajanı güvenliği'e bakın.