Agent SDK

Agent SDK Genel Bakış (Agent SDK Overview)

Claude Code'u bir kütüphane olarak kullanarak üretim yapay zeka ajanları oluşturun. Agent SDK, Claude Code'u güçlü kılan aynı araçları, ajan döngüsünü ve bağlam yönetimini Python ve TypeScript'te programlanabilir şekilde sunar.

Dokümantasyon indeksi: Tüm sayfaları keşfetmek için şu adresi kullanın: https://code.claude.com/docs/llms.txt

Not: Claude Code SDK, Claude Agent SDK olarak yeniden adlandırılmıştır. Eski SDK'dan geçiş yapıyorsanız, Migration Guide sayfasına bakın.

Önemli: Opus 4.7 (claude-opus-4-7) modeli, Agent SDK v0.2.111 veya sonraki sürümlerini gerektirir. thinking.type.enabled API hatası alırsanız, Troubleshooting sayfasına bakın.

Başlangıç (Get started)

1. SDK'yı yükleyin

TypeScript:

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

Python:

pip install claude-agent-sdk

TypeScript SDK, platformunuz için yerel bir Claude Code ikili dosyasını opsiyonel bağımlılık olarak paketler, bu nedenle Claude Code'u ayrıca yüklemeniz gerekmez.

2. API anahtarınızı ayarlayın

Console üzerinden bir API anahtarı alın ve ortam değişkeni olarak ayarlayın:

export ANTHROPIC_API_KEY=your-api-key

SDK ayrıca üçüncü taraf API sağlayıcıları üzerinden kimlik doğrulamayı da destekler:

• Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 ortam değişkenini ayarlayın ve AWS kimlik bilgilerini yapılandırın
• Claude Platform on AWS: CLAUDE_CODE_USE_ANTHROPIC_AWS=1 ve ANTHROPIC_AWS_WORKSPACE_ID değişkenlerini ayarlayın, ardından AWS kimlik bilgilerini yapılandırın
• Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 ortam değişkenini ayarlayın ve Google Cloud kimlik bilgilerini yapılandırın
• Microsoft Azure: CLAUDE_CODE_USE_FOUNDRY=1 ortam değişkenini ayarlayın ve Azure kimlik bilgilerini yapılandırın

Kurulum kılavuzları için Bedrock, Claude Platform on AWS, Vertex AI veya Azure AI Foundry sayfalarına bakın.

Uyarı: Önceden onaylanmadıkça, Anthropic, üçüncü taraf geliştiricilerin Claude Agent SDK üzerine inşa edilmiş ajanlar da dahil olmak üzere ürünleri için claude.ai girişi veya hız sınırları sunmasına izin vermez. Bunun yerine bu belgede açıklanan API anahtarı kimlik doğrulama yöntemlerini kullanın.

3. İlk ajanınızı çalıştırın

Bu örnek, yerleşik araçları kullanarak geçerli dizindeki dosyaları listeleyen bir ajan oluşturur:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(
            allowed_tools=["Bash", "Glob"]
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript:

import { query, ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: new ClaudeAgentOptions({
      allowed_tools: ["Bash", "Glob"],
    }),
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Yetenekler (Capabilities)

Claude Code'u güçlü kılan her şey SDK'da mevcuttur: yerleşik araçlar, hook'lar, alt ajanlar, MCP, izinler ve oturumlar.

Yerleşik Araçlar (Built-in tools)

Ajanınız kutudan çıktığı gibi dosya okuyabilir, komut çalıştırabilir ve kod tabanlarında arama yapabilir. Temel araçlar şunlardır:

Bu örnek, kod tabanınızda TODO yorumlarını arayan bir ajan oluşturur:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find all TODO comments and create a summary",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"]
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Hook'lar (Hooks)

Ajan yaşam döngüsünün önemli noktalarında özel kod çalıştırın. SDK hook'ları, ajan davranışını doğrulamak, günlüğe kaydetmek, engellemek veya dönüştürmek için geri çağırma fonksiyonları kullanır.

Mevcut hook'lar: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit ve daha fazlası.

Bu örnek, tüm dosya değişikliklerini bir denetim dosyasına kaydeder:

Python:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactor utils.py to improve readability",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(
                        matcher="Edit|Write",
                        hooks=[log_file_change]
                    )
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Hook'lar hakkında daha fazla bilgi için Hooks dokümantasyonu sayfasına bakın.

Alt Ajanlar (Subagents)

Odaklanmış alt görevleri halletmek için özelleşmiş ajanlar oluşturun. Ana ajanınız görevleri devreder ve alt ajanlar sonuçlarla geri döner. Özel talimatlarla özel ajanlar tanımlayın.

Alt ajanlar Agent aracı aracılığıyla çağrıldığından, allowedTools içinde Agent'ı dahil edin:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security reviews.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Bir alt ajanın bağlamındaki mesajlar, hangi mesajların hangi alt ajan yürütmesine ait olduğunu takip etmenizi sağlayan bir parent_tool_use_id alanı içerir.

Alt ajanlar hakkında daha fazla bilgi için Subagents dokümantasyonu sayfasına bakın.

MCP (Model Context Protocol)

Harici sistemlere Model Context Protocol aracılığıyla bağlanın: veritabanları, tarayıcılar, API'ler ve yüzlerce daha fazlası.

Bu örnek, Playwright MCP sunucusunu bağlayarak ajanınıza tarayıcı otomasyonu yetenekleri kazandırır:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open example.com and describe what you see",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

MCP hakkında daha fazla bilgi için MCP dokümantasyonu sayfasına bakın.

İzinler (Permissions)

Ajanınızın hangi araçları kullanabileceğini tam olarak kontrol edin. Güvenli işlemlere izin verin, tehlikeli olanları engelleyin veya hassas eylemler için onay gerektirin.

Etkileşimli onay istemleri ve AskUserQuestion aracı için Handle approvals and user input sayfasına bakın.

Bu örnek, kodu analiz edebilen ancak değiştiremeyen salt okunur bir ajan oluşturur. allowed_tools, Read, Glob ve Grep araçlarını önceden onaylar:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review this code for best practices",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

İzinler hakkında daha fazla bilgi için Permissions dokümantasyonu sayfasına bakın.

Oturumlar (Sessions)

Birden çok alışverişte bağlamı koruyun. Claude, okunan dosyaları, yapılan analizleri ve konuşma geçmişini hatırlar. Oturumları daha sonra devam ettirin veya farklı yaklaşımları keşfetmek için çatallayın.

Bu örnek, ilk sorgudan oturum kimliğini yakalar, ardından tam bağlamla devam eder:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # First query: capture the session ID
    async for message in query(
        prompt="Read the authentication module",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob"]
        ),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Resume with full context from the first query
    async for message in query(
        prompt="Now find all places that call it",
        options=ClaudeAgentOptions(
            resume=session_id
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

Oturumlar hakkında daha fazla bilgi için Sessions dokümantasyonu sayfasına bakın.

Claude Code Özellikleri (Claude Code features)

SDK ayrıca Claude Code'un dosya sistemi tabanlı yapılandırmasını da destekler. Varsayılan seçeneklerle SDK, bunları çalışma dizininizdeki .claude/ ve ~/.claude/ dizinlerinden yükler. Hangi kaynakların yükleneceğini kısıtlamak için seçeneklerinizde setting_sources (Python) veya settingSources (TypeScript) ayarını yapın.

Agent SDK'yı Diğer Claude Araçlarıyla Karşılaştırma (Compare the Agent SDK to other Claude tools)

Claude Platformu, Claude ile uygulama geliştirmek için birden çok yol sunar. İşte Agent SDK'nın bunlara nasıl uyduğu:

Agent SDK vs Client SDK

Anthropic Client SDK, size doğrudan API erişimi sağlar: siz istemler gönderir ve araç yürütmeyi kendiniz uygularsınız. Agent SDK ise size yerleşik araç yürütmeyle birlikte Claude'u verir.

Client SDK ile siz bir araç döngüsü uygularsınız. Agent SDK ile Claude bunu halleder:

## Client SDK: Siz araç döngüsünü uygularsınız
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

## Agent SDK: Claude araçları otonom olarak halleder
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

Aynı yetenekler, farklı arayüz:

Birçok ekip her ikisini de kullanır: günlük geliştirme için CLI, üretim için SDK. İş akışları doğrudan birbirine çevrilebilir.

Agent SDK vs Managed Agents

Managed Agents, barındırılan bir REST API'sidir: Anthropic ajanı ve sanal alanı çalıştırır, uygulamanız olaylar gönderir ve sonuçları geri akış olarak alır. Agent SDK ise ajan döngüsünü kendi işleminiz içinde çalıştıran bir kütüphanedir.

Yaygın bir yol, önce Agent SDK ile yerel olarak prototip oluşturmak, ardından üretim için Managed Agents'a geçmektir.

Değişiklik Günlüğü (Changelog)

SDK güncellemeleri, hata düzeltmeleri ve yeni özellikler için tam değişiklik günlüğünü görüntüleyin:

• TypeScript SDK: CHANGELOG.md sayfasını görüntüleyin
• Python SDK: CHANGELOG.md sayfasını görüntüleyin

Hata Bildirme (Reporting bugs)

Agent SDK ile ilgili hatalar veya sorunlarla karşılaşırsanız:

• TypeScript SDK: GitHub üzerinden bildirin
• Python SDK: GitHub üzerinden bildirin

Marka Kullanım Yönergeleri (Branding guidelines)

Claude Agent SDK'yı entegre eden ortaklar için Claude markasının kullanımı isteğe bağlıdır. Ürününüzde Claude'a atıfta bulunurken:

İzin verilenler:

• "Claude Agent" (açılır menüler için tercih edilir)
• "Claude" (menü zaten "Agents" olarak etiketlenmişse)
• "Powered by Claude" (mevcut bir ajan adınız varsa)

İzin verilmeyenler:

• "Claude Code" veya "Claude Code Agent"
• Claude Code markalı ASCII sanatı veya Claude Code'u taklit eden görsel öğeler

Ürününüz kendi markasını korumalı ve Claude Code veya herhangi bir Anthropic ürünü gibi görünmemelidir. Marka uyumluluğu ile ilgili sorular için Anthropic satış ekibiyle iletişime geçin.

Lisans ve Şartlar (License and terms)

Claude Agent SDK'nın kullanımı, kendi müşterilerinize ve son kullanıcılarınıza sunduğunuz ürün ve hizmetleri güçlendirmek için kullandığınızda da dahil olmak üzere, Anthropic'in Ticari Hizmet Şartları tarafından yönetilir; belirli bir bileşen veya bağımlılık, o bileşenin LICENSE dosyasında belirtildiği gibi farklı bir lisans kapsamında olmadığı sürece.

Sonraki Adımlar (Next steps)

• Quickstart — Dakikalar içinde hata bulan ve düzelten bir ajan oluşturun
• Example agents — E-posta asistanı, araştırma ajanı ve daha fazlası
• TypeScript SDK — Tam TypeScript API referansı ve örnekler
• Python SDK — Tam Python API referansı ve örnekler

Örnek kullanım senaryosu

Bir yazılım ekibi, CI/CD hattında otomatik kod incelemesi yapacak bir ajan geliştirmek istiyor. İşte adım adım uygulama:

1. SDK'yı yükleyin: Ekip, Python SDK'sını pip install claude-agent-sdk komutuyla yükler ve ANTHROPIC_API_KEY ortam değişkenini CI ortamında ayarlar.

2. Salt okunur bir inceleme ajanı oluşturun: Ajanın kodu değiştirmesini engellemek için allowed_tools parametresine yalnızca Read, Glob ve Grep araçları eklenir. Bu sayede ajan yalnızca analiz yapabilir.

3. Hook ile denetim günlüğü ekleyin: PostToolUse hook'u kullanılarak, ajanın her Read çağrısı bir denetim günlüğüne kaydedilir. Bu, hangi dosyaların incelendiğini takip etmeyi sağlar.

4. Alt ajanlarla uzmanlık alanları oluşturun: Bir "security-reviewer" alt ajanı tanımlanır. Bu alt ajana özel bir prompt verilir: "Analyze code for security vulnerabilities like SQL injection, XSS, and insecure deserialization." Ana ajan, kod tabanını tararken güvenlikle ilgili dosyaları bu alt ajana yönlendirir.

5. MCP ile harici veritabanına bağlanın: Ajan, projenin bağımlılıklarını kontrol etmek için bir MCP sunucusu aracılığıyla npm audit veya pip audit çıktılarını alır. Bu, bilinen güvenlik açıklarına sahip paketleri tespit etmeyi sağlar.

6. Oturum yönetimi ile çoklu inceleme turları: İlk inceleme turunda ajan, kod tabanını tarar ve bir oturum kimliği döndürür. Ekip, bu oturum kimliğini kullanarak ikinci bir turda "Şimdi sadece güvenlik açıklarını raporla" diyerek bağlamı korur ve yalnızca güvenlikle ilgili bulguları alır.

7. Üretime geçiş: Yerel testler tamamlandıktan sonra ekip, aynı mantığı Managed Agents REST API'sine taşıyarak CI/CD hattında uzun süreli ve asenkron inceleme oturumları çalıştırır.