Ajan kurmak: Skill’ler, alt ajanlar ve Agent SDK

Bu dersteki uygulama, Claude Console’dan alınacak bir API anahtarı gerektirir ve API kullanımı harcama doğurabilir. Harcamayı sınırlama yolunu aşağıda göreceksiniz.

Bu derste ajanın ne olduğunu, Skill’ler ile alt ajanların (subagent) birlikte nasıl kullanıldığını ve Claude Agent SDK ile ilk ajanınızı nasıl kuracağınızı öğreneceksiniz. Anlatım Anthropic’in resmî belgelerine dayanır; kodu kendiniz yazmak yerine Claude’a yazdırabilirsiniz.

Aklınıza bir soru mu takıldı?

Sorunuzu ya da aradığınız konuyu yazın Ders bul

Bu derste neler öğreneceksiniz?

• Ajanın sıradan bir sohbetten farkını ve Agent SDK’nın ne sağladığını.
• Skill ile alt ajanın görevlerini ve ikisini tek bir mimaride birleştirmeyi.
• Salt okunur bir alt ajan ile bir Skill’i çalıştırmayı ve harcamaya sınır koymayı.

Ajan nedir, Agent SDK ne sağlar?

Anthropic’in belgesine göre ajan, adımlarını kendisi planlayan ve dosya okuma, komut çalıştırma, düzenleme gibi araçları çağırarak görevi tamamlayan bir uygulamadır. Agent SDK, Claude Code’u çalıştıran araçları, ajan döngüsünü ve bağlam yönetimini Python ve TypeScript’te kullanmanızı sağlar.

Belgede sayılan yetenekler şunlardır: yerleşik araçlar, hooks (yaşam döngüsünde özel kod çalıştırma), alt ajanlar, MCP, izinler, oturumlar ve Skill’ler. Başlamak için Node.js 18 veya üzeri ya da Python 3.10 veya üzeri ile bir Anthropic hesabı gerekir.

Kimlik doğrulama için API anahtarı kullanılır. Belge, Anthropic’in önceden onay vermediği üçüncü taraf geliştiricilerin ürünlerinde claude.ai girişi ya da claude.ai kullanım sınırı sunamayacağını da belirtiyor.

Skill ve alt ajan: iki ayrı işlev

Skill, bir işin yöntemini anlatan SKILL.md dosyasıdır. SDK’da Skill’leri dosya olarak oluşturursunuz: .claude/skills klasörü altında her Skill için ayrı bir klasör ve içinde SKILL.md bulunur. Belgeye göre Skill’i program içinden kaydetmenin yolu yoktur. Claude, description alanına bakarak uygun Skill’i kendisi seçer.

Alt ajan ise ana ajanın görevlendirdiği ayrı bir ajan örneğidir. Kendi konuşmasında çalışır; ara adımlar ana konuşmaya yığılmaz, yalnızca son mesajı döner. Belge dört yarar sayar:

• Bağlam yalıtımı: Onlarca dosyayı okuyan bir alt ajan, ana konuşmayı şişirmeden özet getirir.
• Paralel çalışma: Bağımsız işler aynı anda yürür.
• Özel talimat: Her alt ajanın kendi sistem komutu olabilir.
• Araç kısıtı: Alt ajanı yalnızca belirli araçlarla sınırlayarak istenmeyen eylem riskini azaltırsınız.

Kısaca: Skill işin nasıl yapılacağını, alt ajan işi kimin yapacağını belirler.

Üç katmanlı mimari

Pratik bir yapı şöyle kurulabilir: ana ajan işi planlar, Skill’ler yöntemi sağlar, alt ajanlar odaklı parçaları yapar. Örneğin bir toplantı notları klasöründe ana ajan görevi böler, toplantı özeti Skill’i çıktı biçimini belirler, salt okunur bir denetçi alt ajan sonucu notlarla karşılaştırır.

Alt ajan varsayılan olarak ana konuşmayı görmez. Ona ulaşan tek şey görevlendirme metnidir; gereken dosya yolunu ve kararları o metne yazın. Aşağıdaki Python taslağı belgedeki yapıdan uyarlanmıştır. Denetçi yalnızca okuyabilir.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="belge-denetcisi ajanını kullanarak notlar.md dosyasını incele",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            max_budget_usd=2.0,
            agents={
                "belge-denetcisi": AgentDefinition(
                    description="Özetleri kaynak notlarla karşılaştırır.",
                    prompt="Yalnızca verilen dosyalara dayan. Bulamadığın bilgiyi yazma.",
                    tools=["Read", "Grep", "Glob"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Skill dosyası da sadedir. Aşağıdaki taslak, belgedeki örneğin biçimini izler:

---
name: toplanti-ozeti
description: Toplantı notlarını karar, görev ve açık soru başlıklarıyla özetler. Kullanıcı toplantı özeti istediğinde kullan.
---

Notları oku. Çıktıyı Kararlar, Görevler ve Açık sorular başlıklarıyla yaz.
Notlarda olmayan bilgiyi ekleme.

Skill’lerin yüklenmesi için setting_sources seçeneğini kendiniz belirliyorsanız “user” ve “project” değerlerini listeden çıkarmayın. Çalışma klasörünüz de .claude/skills klasörünün bulunduğu proje içinde olmalıdır.

Sınırlar koyun

Claude kaç alt ajan açacağına kendisi karar verir ve her alt ajan ayrı API istekleri yapar. Belgeye göre bir alt ajan kendi alt ajanlarını da başlatabilir; tek bir komut bir ajan ağacına dönüşebilir. Bunu üç şeyle sınırlarsınız: iç içe derinlik için CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, eşzamanlı alt ajan sayısı için CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ortam değişkenleri ve toplam harcama için Python’da max_budget_usd seçeneği. Ayrıca allowed_tools ile hangi araçların onaysız çalışacağını siz belirlersiniz.

Adım adım uygulama

1. Tekrarlanan, riski düşük küçük bir iş seçin; örneğin toplantı notlarından özet çıkarmak.
2. Anthropic hesabınızla Claude Console’dan bir API anahtarı alın ve kimseyle paylaşmayın.
3. Boş bir proje klasörü açın ve listenin altındaki komutları orada çalıştırın. Komutlar Windows PowerShell içindir; macOS ve Linux’ta etkinleştirme ve anahtar komutları farklıdır.
4. Anahtarı ortam değişkeni olarak tanımlayın. Belgeye göre SDK .env dosyalarını kendiliğinden okumaz.
5. Skill dosyasını oluşturun, ardından alt ajanı salt okunur araçlarla tanımlayın.
6. Ajanı çalıştırın. Başlangıç mesajındaki skills listesinde Skill’inizi, çıktı akışında Agent aracının çağrıldığını arayın.
7. Üç farklı notla deneyin ve özeti kaynak notlarla elle karşılaştırın.

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
$env:ANTHROPIC_API_KEY = "api-anahtariniz"

Kontrol listesi

• Alt ajan yalnızca gereken araçlara sahip.
• Harcama sınırı konuldu.
• API anahtarı kodun içinde değil.
• Skill’in description alanı ne zaman kullanılacağını açıkça söylüyor.
• Çıktıyı kaynakla karşılaştırdım.

Sık yapılan hatalar

• Alt ajana fazla araç vermek: Denetçiye Bash ve Write vermek, denetçiyi bir işçiye çevirir.
• Bağlam aktarmamak: Alt ajan ana konuşmayı görmez; görevlendirme metni eksikse yanlış işi yapar.
• Belirsiz description: Claude Skill’i ve alt ajanı bu açıklamaya bakarak seçer.
• Skill’in yüklenmemesi: setting_sources listesinde user ve project yoksa Skill’ler bulunamaz.
• Sınırsız bırakmak: Harcama ve derinlik sınırı olmayan bir ajan beklenenden fazla iş açabilir.

Kendinizi deneyin

Kaynaklar

• Agent SDK overview – Claude Code Docs (İngilizce)
• Agent SDK quickstart – Claude Code Docs (İngilizce)
• Subagents in the SDK – Claude Code Docs (İngilizce)
• Extend agents with skills – Claude Code Docs (İngilizce)

Son kontrol: 7 Kasım 2026

Kaynak: yzdersleri.com/ders/claude-ajan-kurmak/ · Yapay Zeka Dersleri