Claude Code SDK

 (docs.anthropic.com)
1 puan yazan GN⁺ 2025-05-20 | 1 yorum | WhatsApp'ta paylaş
  • Claude Agent SDK, Claude Code’un araç yürütme, ajan döngüsü ve bağlam yönetimini Python·TypeScript kodundan kontrol etmeyi sağlayarak dosya okuma, komut çalıştırma, web araması ve kod düzenlemeyi otomatikleştirir
  • Temel araçlar olarak Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion sunar; böylece kod tabanı keşfinden kullanıcıya doğrulama soruları sormaya kadar işlemler ayrı bir yürütme katmanı olmadan yapılabilir
  • Hook’lar, alt ajanlar, MCP, izinler ve oturumlar birleştirildiğinde dosya değişiklikleri için denetim günlüğü, yalnızca kod incelemeye özel alt ajan, Playwright tabanlı tarayıcı otomasyonu ve salt okunur analiz ajanı gibi yapılandırmalar oluşturulabilir
  • Kurulum @anthropic-ai/claude-agent-sdk veya claude-agent-sdk ile yapılır; Python için 3.10 ve üzeri gerekir ve TypeScript SDK, platforma uygun yerel Claude Code ikilisini isteğe bağlı bağımlılık olarak içerir
  • Agent SDK, araç döngüsünü doğrudan uygulayan Anthropic Client SDK’den farklı olarak yerleşik araç yürütme sağlar ve Managed Agents gibi Anthropic altyapısında değil, kullanıcının kendi süreci ve altyapısında çalışır

Claude Agent SDK’nın kapsadığı alan

  • Claude Agent SDK, Claude Code’u çalıştıran araçları, ajan döngüsünü ve bağlam yönetimini Python ve TypeScript içinde kullanılabilir hale getirir
  • Ajanlar dosya okuyabilir, komut çalıştırabilir, web araması yapabilir ve kod düzenleyebilir
  • Yerleşik araç yürütme içerdiği için kullanıcıların ayrıca bir araç yürütme katmanı kurmasına gerek kalmadan ajanlar işe başlayabilir
  • Temel örnekte auth.py içindeki bir hatayı bulup düzeltmek için Read, Edit, Bash araçlarına izin verilir

Kurulum ve kimlik doğrulama akışı

  • Dil bazlı paketlerle kurulur
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • Python paketi için Python 3.10 veya üzeri gerekir
    • No matching distribution found for claude-agent-sdk hatası alınıyorsa yorumlayıcı sürümü 3.10’dan eski olabilir
    • macOS veya Linux’ta python3 --version, Windows’ta py --version ile kontrol edilir
  • TypeScript SDK, platforma uygun yerel Claude Code ikilisini isteğe bağlı bağımlılık olarak içerdiğinden Claude Code’u ayrıca kurmak gerekmez
  • API anahtarı Console üzerinden alınır ve ANTHROPIC_API_KEY ortam değişkeni olarak ayarlanır
  • Üçüncü taraf API sağlayıcı kimlik doğrulaması da desteklenir
    • Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 ayarlanır, ardından AWS kimlik bilgileri yapılandırılır
    • Claude Platform on AWS: CLAUDE_CODE_USE_ANTHROPIC_AWS=1 ve ANTHROPIC_AWS_WORKSPACE_ID ayarlanır, ardından AWS kimlik bilgileri yapılandırılır
    • Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 ayarlanır, ardından Google Cloud kimlik bilgileri yapılandırılır
    • Microsoft Azure: CLAUDE_CODE_USE_FOUNDRY=1 ayarlanır, ardından Azure kimlik bilgileri yapılandırılır
  • Anthropic, önceden onay vermeden üçüncü taraf geliştiricilerin Claude Agent SDK tabanlı ürünlerde claude.ai girişi veya rate limit sunmasına izin vermez

Temel araçlar ve ajan yetenekleri

  • SDK, Claude Code’un başlıca yeteneklerinin kod içinden kullanılmasını sağlar
    • yerleşik araçlar
    • hook’lar
    • alt ajanlar
    • MCP
    • izinler
    • oturumlar
  • Başlıca yerleşik araçlar şu işlevleri üstlenir
    • Read: çalışma dizini içindeki dosyaları okur
    • Write: yeni dosya oluşturur
    • Edit: mevcut dosyalara hassas düzenlemeler uygular
    • Bash: terminal komutları, betikler ve git işlemlerini çalıştırır
    • Monitor: arka plan betiklerini izler ve her çıktı satırına olay olarak tepki verir
    • Glob: **/*.ts, src/**/*.py gibi desenlerle dosya bulur
    • Grep: dosya içeriğinde düzenli ifadeyle arama yapar
    • WebSearch: en güncel bilgileri web’de arar
    • WebFetch: web sayfası içeriğini alır ve ayrıştırır
    • AskUserQuestion: çoktan seçmeli seçeneklerle kullanıcıya doğrulama sorusu sorar
  • Örnek ajan, kod tabanındaki TODO yorumlarını bulup özetlemek için Read, Glob, Grep kullanımına izin verir

Hook’lar, alt ajanlar ve MCP

  • Hook’lar, ajan yaşam döngüsünün önemli noktalarında kullanıcı kodunu çalıştırır
    • Callback işlevleriyle ajan davranışı doğrulanabilir, kaydedilebilir, engellenebilir veya dönüştürülebilir
    • Kullanılabilir hook’lar arasında PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit gibi seçenekler vardır
    • Örnekte PostToolUse içinde Edit|Write işlemleri algılanarak dosya değişiklikleri audit.log içine kaydedilir
  • Alt ajanlar, odaklanmış alt görevleri işleyen uzmanlaşmış ajanlardır
    • Ana ajan görevi devreder, alt ajan ise sonucu geri döndürür
    • Özel ajanlar açıklama, prompt ve kullanılacak araçlarla tanımlanır
    • Alt ajan çağrısı Agent aracı üzerinden yapıldığından otomatik onay için allowedTools içine Agent eklenmelidir
    • Alt ajan bağlamındaki mesajlar, hangi alt ajan çalıştırmasına ait olduklarını izlemek için parent_tool_use_id alanını içerir
  • Model Context Protocol(MCP) ile veritabanı, tarayıcı, API gibi harici sistemlere bağlanılabilir

İzinler ve oturum yönetimi

  • İzin ayarları, ajanın kullanabileceği araçları sınırlar
    • Güvenli işlemler izinli olabilir, riskli işlemler engellenebilir ve hassas eylemler için onay istenebilir
    • Örnekte yalnızca Read, Glob, Grep önceden onaylanarak kodu analiz eden ama değiştirmeyen salt okunur ajan yapılandırılır
  • AskUserQuestion aracı ile etkileşimli onay istemleri, kullanıcı girdisi işleme akışında birlikte kullanılır
  • Oturumlar, birden fazla etkileşim boyunca bağlamı korur
    • Claude, okunan dosyaları, yapılan analizleri ve konuşma geçmişini hatırlar
    • Aynı oturum daha sonra sürdürülebilir veya farklı bir yaklaşımı denemek için çatallanabilir
    • Örnekte ilk sorguda session_id alınır, ikinci sorguda resume=session_id ile aynı bağlam sürdürülür

Claude Code yapılandırma desteği

  • SDK, Claude Code’un dosya sistemi tabanlı yapılandırmasını destekler
  • Varsayılan olarak ayarlar çalışma dizinindeki .claude/ ve ~/.claude/ içinden yüklenir
  • Yüklenecek yapılandırma kaynaklarını sınırlamak için Python’da setting_sources, TypeScript’te settingSources seçeneği kullanılır
  • Desteklenen özellikler ve konumları şunlardır
    • Skills: Claude’un otomatik kullandığı veya /name ile çağrılan uzmanlaşmış yetenekler, .claude/skills/*/SKILL.md
    • Commands: eski biçimde özel komutlar, .claude/commands/*.md
    • Memory: proje bağlamı ve talimatlar, CLAUDE.md veya .claude/CLAUDE.md
    • Plugins: skills, agents, hooks, MCP servers genişletmeleri; plugins seçeneğiyle programatik olarak yapılandırılır

Diğer Claude araçlarından farkı

  • Anthropic Client SDK, doğrudan API erişimi sağlar; kullanıcı prompt gönderir ve araç yürütmeyi kendisi uygular
  • Agent SDK’de Claude, araç işleme sürecini otonom biçimde yürütür
    • Client SDK’de araç döngüsünü kullanıcı uygular
    • Agent SDK, Claude’a yerleşik araç yürütme sağlar
  • Kullanım amacına göre seçim ölçütleri şöyledir
    • etkileşimli geliştirme: CLI
    • CI/CD pipeline’ları: SDK
    • özel uygulamalar: SDK
    • tek seferlik işler: CLI
    • üretim otomasyonu: SDK
  • Birçok ekip, günlük geliştirmede CLI’ı, üretimde ise SDK’yı birlikte kullanır; iş akışları da doğrudan birbirine taşınabilir
  • Managed Agents, Anthropic’in ajanları ve sandbox’ları çalıştırdığı barındırmalı bir REST API’dir
  • Agent SDK, ajan döngüsünü kullanıcının kendi süreci içinde çalıştıran bir kütüphanedir
    • çalışma konumu: Agent SDK kullanıcının süreci ve altyapısında, Managed Agents ise Anthropic tarafından yönetilen altyapıda çalışır
    • arayüz: Agent SDK bir Python veya TypeScript kütüphanesidir, Managed Agents ise REST API’dir
    • çalışma hedefi: Agent SDK kullanıcının altyapısındaki dosyalarla çalışır, Managed Agents ise oturum başına yönetilen sandbox üzerinde çalışır
    • oturum durumu: Agent SDK dosya sistemindeki JSONL kullanır, Managed Agents ise Anthropic tarafından barındırılan olay günlüklerini kullanır
    • özel araçlar: Agent SDK süreç içi Python veya TypeScript işlevleri kullanır, Managed Agents’ta Claude aracı tetikler ve kullanıcı yürütme sonucunu geri döndürür
    • uygun kullanım: Agent SDK yerel prototipleme ve dosya sistemi·servislere doğrudan erişen ajanlar için, Managed Agents ise sandbox veya oturum altyapısı işletmeden üretim ajanları ve uzun süreli·asenkron oturumlar için uygundur
  • Yaygın yol, önce Agent SDK ile yerel prototip oluşturup ardından üretimde Managed Agents’a geçmektir

Değişiklik günlüğü, hata bildirimi ve markalama

  • SDK güncellemeleri, hata düzeltmeleri ve yeni özellikler ilgili depoların değişiklik günlüğünden takip edilir
  • Hatalar veya sorunlar GitHub üzerinden bildirilir
  • İş ortakları Claude Agent SDK’yı entegre ederken Claude markalamasını kullanmak isteğe bağlıdır
    • izinli: “Claude Agent”, “Claude”, “Powered by Claude”
    • yasak: “Claude Code”, “Claude Code Agent”, Claude Code marka ASCII art’ı veya Claude Code’u taklit eden görsel öğeler
    • Ürün kendi markasını korumalı ve Claude Code ya da Anthropic ürünü gibi görünmemelidir
  • Claude Agent SDK kullanımı Anthropic’s Commercial Terms of Service kapsamındadır
    • Belirli bileşen veya bağımlılıkların kendi LICENSE dosyalarında farklı bir lisans belirtmesi durumu istisnadır

İlgili okumalar

1 yorum

 
GN⁺ 2025-05-20
Hacker News yorumları

  • Claude Code’un yöneldiği doğrultu, benim ajan tabanlı kodlama araçlarında istediğim şeyle tam olarak örtüşüyor; “Unix aracı gibi” felsefesini de seviyorum
    Açık önizlemenin ilk dönemlerinden beri kullanıyorum ve yönü o zamandan belliydi. Bir kodlama ajanının ideal nihai durumunun, Jira bileti gibi bir özellik isteği verildiğinde bunu inceleyip geri bildirim verilebilecek bir PR oluşturması olduğunu düşünüyorum. Bu anlamda Cursor, Windsurf gibi yerel editör merkezli araçlar CI içinde çalışamadıkları için çıkmaz sokağa yakın. Kod tabanını kurallar, MCP vb. ile yapay zekaya uygun hâle getiriyorsanız, headless kullanıma kadar uzanabilecek bir teknolojiyi hedeflemek gerekir. Claude Code, araçlar üzerinden otomasyonun bir parçası olarak kolayca kullanılabildiği için artık kodlama ajanlarını düşünürken varsayılanım oldu; Codex npm paketi de benzer. Yine de şirketlerin kod tabanlarını ajan kullanımına uygun hâle getirmelerine yardımcı olan bir iş yaptığım için, kolay yapılandırılabilen araçlara doğru bir önyargım olabilir

    • O “ideal nihai durum”a katılmak zor. Benim istediğim görüntü, bir odada birden fazla ekranla çevrili olup yapay zeka ajanlarının kodlama, tasarım ve test yaptığı; benim de ortada yön verdiğim ve zevklerimi uygulattığım bir düzen
      Her şeyin konuşmayla ilerlediği ve %99 oranında klavyeye dokunmam gerekmeyen bir biçim bekliyorum
    • Bence değil. Bir kodlama ajanının “ideal” nihai durumu, benim bilgisayarımda ya da istediğim makinede çalışan özgür ve açık kaynaklı bir kodlama ajanı olmalı
      Terminalde ls, ps, kill gibi komutları her çalıştırdığınızda para ödediğinizi hayal edin; hiç mantıklı değil. LLM’ler için de aynı şey geçerli. Tescilli LLM’leri yasaklayalım demiyorum ama eski usul hacker’ların ana araç olarak kullanması gereken şey özgür ve açık kaynaklı araçlar olmalı
    • Anthropic de bugün benzer yönde bir özelliği beta olarak duyurdu: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Cursor ve MCP ile de bu tür işleri denedim. Yaklaşık bir gün sonra kullanım sınırına takıldım ve en yavaş, en aptal modele düşürüldüm
      Claude ile de denedim ama sınırları hızla tükettim. PR’nin doğrudan “geçilebilir” seviyede olduğu durumlar ancak yaklaşık %25; yapay zekanın nerede batırdığını bulmaya çalışmaktansa çoğu zaman işi baştan doğru düzgün kendim yapmak daha hızlı
    • Özellik isteği verildiğinde incelenecek bir PR üretmesi fikrini anlıyorum ama o zaman yazılım işinin ruhu en çok kemiren kısmı olan Jira biletleri geriye kalıyor; bu da iç karartıcı

  • Claude Code, kodlamada LLM kullanma biçimleri arasında en çok hoşuma gidenlerden biri
    Ama gerçekten ihtiyaç duyulan şey, istediğiniz modeli verebildiğiniz ve birden fazla modelin yanıtlarını da karşılaştırabildiğiniz açık kaynaklı bir sürüm bence. Aider ya da diğer alternatifler Claude Code kadar kullanışlı hissettirmiyor. Anthropic açısından bakınca hendek ortadan kalkacağı için bunu istemezler, ama tüketici tarafında insan yalnızca belirli bir ekosisteme kilitlenmeden en iyi modeli kullanmak istiyor. Muhtemelen LLM model sağlayıcılarının en çok korktuğu nokta da bu

    • OpenAI Codex muhtemelen en yakın alternatif. Açık kaynaklı ve herhangi bir sağlayıcının modeliyle kullanılabiliyor
      Şu anda Claude Code kadar iyi değil ama kısa sürede yetişecek gibi görünüyor. https://github.com/openai/codex/tree/main
    • OpenCode projesi ilginizi çekebilir: https://github.com/opencode-ai/opencode
      Hâlâ geliştirme aşamasında ama umut verici görünüyor
    • Claude Code’un Aider’dan daha iyi yaptığı şeyin ne olduğunu merak ediyorum
    • Son zamanlarda kendimi biraz fazla tanıtmış olabilirim ama önceki yorumlarıma bakarsanız Go ile yaptığım bir servis var. Tam olarak bu ihtiyacı hedefliyor
    • Katılıyorum ama diğer modellerin de MCP sunucularıyla çalışma şeklini bilecek şekilde eğitilmiş olması gerekmez mi? Yoksa bu sorun değil mi?

  • Aider uzun zamandır Python ve shell scripting desteği sunuyor [0]
    Yakın zamanda 130 yeni programlama dili desteği ekleme sürecinde, Aider ile doğaçlama Bash scripting yapmayı gösteren bir screencast de hazırladım [1]. Bu yaklaşımın ne kadar güçlü olabileceğine dair fikir verebilir.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Aider’ı gerçekten seviyorum. MCP desteği de yakında gelecek; geliştirme dalını test ediyorum
      Böylece güvendiğiniz modeli kullanarak PR’ler, biletler vb. üzerinden baştan sona geliştirme yapabilirsiniz
    • Aider’ı Claude Code’a ne kadar yaklaştırabileceğimizi merak ediyorum. Claude Code’un kullanıcı deneyimi iyiydi ama Gemini 2.5 Proyu tercih ettiğim için kullanmıyorum
      Commit atmasını pek istemiyorum; daha çok Claude Code’un kullanım hissini beğeniyorum
    • Aider, iyi cilalanmış bir GitHub Actions workflow’u olursa ciddi ölçüde iyileşebilir
      Depoya tek bir dosya ekleyince issue’lar üzerinden herhangi bir modelle konuşabilmek gibi bir şey yeterli olur

  • Claude Code ekibinin daha ayrıntılı ele aldığı içerik: http://latent.space/p/claude-code
    Sadece transkripte göz atmak bile yeterli; kişisel olarak Anthropic çalışanlarının sınırsız Claude kullanmalarına rağmen ortalama günde yaklaşık 6 dolar harcamaları, headless Claude Code’u CI’ın her yerinde kullanılabilen bir “Linux” yardımcı aracı gibi görmeleri, kullanıcı tarafından genişletilebilir bir platform olarak değerlendirmeleri, sandboxing·branching·planlama özelliklerinin gelecek yol haritasında olması ve Sonnet 3.7’yi kalıcı ajan modeli olarak görmeleri etkileyiciydi.

    • Bağlantıda Anthropic’in iç mühendisleri arasında günde 1.000 dolardan fazla harcayan birinin de olduğu yazıyor.
      Çalışan bazında harcamaların P50, P75, P95 değerleri ne kadar, merak ediyorum.
    • Belki ben yanlış kullanıyorumdur ama Claude Code’u 2 saat kullanınca kolayca 20 doların üzerine çıkıyor.
      Kişisel projeler için fazla pahalı olduğundan kullanmayı bıraktım.
    • Son zamanlarda latent space podcast’ini gerçekten keyifle dinliyorum. Bu kadar yüksek sinyal-gürültü oranını korurken genel çıktı miktarı bu seviyede olan kişi ya da podcast neredeyse yok bence.
      Son yarım yılda ya da birkaç yılda birden fazla işi büyütürken herkese açık çalışmalarının miktarının ve değerinin artmaya devam etmesi şaşırtıcı. Başkaları da benzer bir üretkenlik eğimi bulabilse keşke. Kabaca neyin iyi uyduğunu paylaşıyor ama yeniden üretmesi kolay değil. Aklıma simonw, gwern geliyor.
    • O podcast’in ne kadar tarafsız olduğunu, yoksa sadece bu ürünün satış odaklı tanıtımı mı olduğunu merak ediyorum.

  • Ben bir AI kod asistanı yapsaydım, onu belirli bir foundation model sağlayıcısına bağlamak en son yapacağım şey olurdu.
    Bu ürünün başarılı olması için model performansının tam şu anda platoya ulaşmış olması, tüm foundation modellerinin neredeyse aynı performans ve yeteneklerde yakınsaması ve entegratörlerin alışıldık SDK gibi küçük kolaylıklar nedeniyle seçim yapacağı varsayımı gerekiyor.

    • Komutlar ve argümanlar dışında bağlayıcı çok şey yok. Sadece girdi ve çıktıdan ibaret.
      Başka bir şeyle değiştirir ya da wrapper koyarsınız. Burada karmaşık pek bir şey yok.
    • Şu an için Claude Code, ajan tabanlı kodlama alanında yazılımsal farklılaştırıcı unsur.
      AI kod asistanıyla ilgili bir şey geliştiriyoruz ve önce Claude Code’u nasıl entegre edeceğimizi hack’liyorduk. Üzerine inşa etmek istediğimiz ilk şey buydu. Lock-in’i dert etmek için çok erken; en iyisine ihtiyacımız var, bu yüzden yalnızca en iyisinin etrafında geliştireceğiz.

  • Claude Code zaten etkileşimsiz modda kullanılabiliyordu; dolayısıyla diğer Unix komut satırı yardımcı araçları gibi başka uygulamalara entegre edilebiliyordu.
    Bu SDK şu anda yalnızca komut satırı kullanımını destekliyor gibi görünüyor; o zaman zaten var olanla aynı şey değil mi? Gerçekte neyin yeni olduğunu anlamıyorum. Ben neyi kaçırıyorum?

    • Ben de bilmiyorum. Bana göre kimsenin bundan pek bahsetmemesi tuhaf.

  • Codebuff’u (https://www.codebuff.com/) da öneririm. Claude Code’a benzer, harika bir CLI kod asistanı ve token maliyetinden çok tasarruf ettirebilir.
    Bu projeyle bir bağlantım yok, sadece kullanıcısıyım.

  • Şartlarda “Hizmetle rekabet eden ürün veya hizmetler geliştirmek, yapay zeka veya makine öğrenmesi algoritmaları ya da modelleri geliştirmek/eğitmek veya hizmeti yeniden satmak için kullanılamaz” deniyor.
    Genel zekayla rekabet etmeyen yazılım ürünü veya hizmeti tam olarak ne olabilir, merak ediyorum. Zeka satıp, katı yorumlandığında hiçbir yerde kullanmayın anlamına gelen bir yasal madde eklemek gibi. Fazla muğlak olduğu için uygulanamaz mı? Genel zekayla rekabet etmek için kullanılamıyorsa çıktının sahibi nasıl olunuyor? “Yasal şartları kimse umursamaz” tarzı bir şey mi? Kimse umursamıyorsa hizmet kullanımına neden kapsamlı bir yasak koyuyorlar? Böyle çıktılar almak için dava kaybetme sorumluluğunu da kabul etmek mi gerekiyor; çok fazla soru var.

    • Avukatları istedikleri gibi yazmaya bırakırsanız böyle olur.
    • “artificial”ı “general” yaptığınız için anlamı doğal olarak değişiyor.

  • Model lock-in varsa kullanım açısından büyük dezavantaj olur. Birisi en yeni ve en yüksek performanslı modeli çıkarırsa ve siz zaten bu altyapıya yatırım yaptıysanız kilitlenmiş olursunuz.
    Daha sonra açsalar bile, ilgili model büyük olasılıkla o CLI’a özel olarak eğitilmiş olduğundan iyi çalışmayabilir. Codex CLI’a bakın; Gemini 2.5 Pro kullanılabiliyor ama OpenAI modellerine kıyasla rastgele durma ya da başarısız olma çok daha sık yaşanıyor.

  • Yeni GitHub Action tam aradığım özellik: https://docs.anthropic.com/en/docs/claude-code/github-action...
    Ancak Claude Code’un Max planıyla kullanmanın bir yolu görünmüyor. Bana göre yalnızca API key kabul ediyor gibi.