Kendi Araç Döngünüzü Yazmayın: Claude Code Agent SDK İncelemesi ve Üretime Alma Rehberi

1. Neden herkes claude-agent-sdk'den söz ediyor?

Anthropic'in yerel SDK'sını kullandıysanız bir ajan oluşturmak için birkaç işi kendiniz yapmanız gerekir:

• while döngüsü yazıp /v1/messages uç noktasını tekrar tekrar çağırmak;
• API yanıtındaki tool_use ve tool_result bloklarını ayrıştırmak;
• mesaj geçmişinizi ve bağlam pencerenizi yönetmek;
• çeşitli uç durumları ve hataları ele almak.

Bunu ilk kez çalıştırmak etkileyici gelebilir; ikinci kez, Anthropic, OpenAI ve Gemini gibi sağlayıcılarda benzer işleri yeniden kurduğunuzu fark edersiniz. Asıl fark yalnızca temel LLM'de değil, ajanın arkasındaki mühendisliktedir.

claude-agent-sdk, Claude Code'un ajan döngüsünü programlı biçimde sunar. Böylece araç zincirini, izin denetimini ve konuşma bağlamını sıfırdan yeniden kurmadan üretimde kullanılabilecek bir kodlama ajanı oluşturabilirsiniz. Anthropic, bu paketi daha önce Claude Code SDK adıyla sunmuştu; paket adındaki değişiklikte de güncel resmî belgeyi izleyin.

claude-agent-sdk ile Claude Code arasındaki ilişki nedir?

Claude Code, terminalde çalışan ajan tabanlı kodlama aracıdır. claude-agent-sdk, bu aracın temel yeteneklerini kendi programınızdan çağrılabilir hâle getirir. SDK'yı terminal tabanlı bir iş akışına, CI/CD hattına veya uygulamanıza entegre edebilirsiniz. Bunlar aynı kullanım biçimi değildir: CLI doğrudan insan kullanımına elverişliyken SDK, uygulama içinden denetimli çağrılar kurmanızı sağlar.

claude-agent-sdk ile Anthropic SDK arasındaki ilişki nedir?

Anthropic SDK, Claude modelleriyle doğrudan konuşan daha düşük seviyeli API istemcisidir; Messages API'si, akış ve araç çağrıları sağlar. claude-agent-sdk onun üzerinde, ajan döngüsü ve araç yürütme gibi daha yüksek seviyeli davranışları yönetir. Bir benzetmeyle, temel SDK motoru sağlar; ajan SDK'sı ise uygulamada kullanabileceğiniz daha bütünlüklü bir araç sunar. Yine de SDK'nın verdiği izinleri ve ortam erişimini uygulamanızın güvenlik gereksinimlerine göre sınırlamanız gerekir.

---

2. Temel mimari ilkesi: her şey bir oturumdur

SDK'nın önemli tasarım kavramı oturumdur. Oturum, bir ajan çalıştırmasının durumunu taşıyan bağımsız yürütme bağlamıdır. Buna konuşma geçmişi, izin ayarları ve onay durumu, araçların çalışma durumu, dosya sistemiyle ilgili izlenen değişiklikler ve kesintiden sonra devam etmek için gereken bağlam dahildir.

Düşük seviyeli API'lerde kesintiden sonra devam etmek için mesaj geçmişini kendiniz serileştirmeniz gerekir. SDK'daki Session nesnesi ise belirli bir çalıştırmayı sürdürmek için gereken durumu yönetir. Bu, her ortamda tüm yan etkilerin otomatik olarak geri alınacağı anlamına gelmez; uygulamanızın dosya ve araç erişimini ayrıca denetlemesi gerekir.

Oturum oluşturma

Aşağıdaki örnek query ile bir oturum başlatır ve Bash ile Read araçlarına izin verir. İlk çağrıda SDK ortamı başlatabilir, bağımlılıkları kurabilir veya CLI bileşenlerini eşitleyebilir. Ağ ve makine koşullarına göre bu işlem birkaç saniye ya da daha uzun sürebilir.

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

const session = await query({
  prompt: "Please write a Python script that prints 1 to 100",
  options: {
    allowedTools: ["Bash", "Read"],
  },
});

Akış olayları

Oturum, yalnızca tek bir nihai yanıt döndürmez. Eşzamansız akış üzerinden olayları izleyerek ajanın ne yaptığını görebilirsiniz. Aşağıdaki örnek stream_event iletilerini JSON olarak yazdırır. Bu yaklaşım akış odaklı bir gözlemlenebilirlik sağlar; sistemin karmaşıklığını ortadan kaldırmaz, çalışma sırasında görünür kılar.

for await (const message of session) {
  if (message.type === "stream_event") {
    console.log(JSON.stringify(message.event, null, 2));
  }
}

Oturum yaşam döngüsü

Ajan işi tamamlayınca oturumun o çalıştırması sona erer; isterseniz aynı oturum kimliğini vererek yeni bir istemle kaldığı yerden devam edebilirsiniz. İlk çağrı yeni bir oturum oluştururken sonraki çağrı sessionId kullanır. Bu kimlik, SDK’ya önceki çalıştırmanın bağlamını geri yükleyip sürdürmesini söyler. Bağlamı serileştirme ve geri yükleme işlemlerini SDK yönetir. Devam ettirilen oturuma hangi araçların verildiğini ve bir önceki adımın etkilerini yine siz gözden geçirmelisiniz.

const resumed = await query(
  "Based on the previous answer, change the script to print 1 to 1000",
  {
    sessionId: session.sessionId,
    options: { allowedTools: ["Bash", "Read", "Write"] },
  }
);

---

3. Temel mekanizmalar: araçlar, izinler ve hook'lar

3.1 Yerleşik araçlar: tamamlanmış bir ajan araç zinciri

Anthropic'in temel SDK'sıyla her aracı kendiniz tanımlamanız gerekir: Bash komutlarını çalıştırmak, dosyaları okumak ve yazmak, izin sınırlarını uygulamak gibi. claude-agent-sdk, Claude Code'da bulunan araç zincirini uygulamanızda kullanıma açar. Kaynakta listelenen araçlar ve varsayılan izin düzeyleri şunlardır:

Araç adı	Açıklama	İzin düzeyi
Bash	Kabuk komutlarını çalıştırma	DefaultAsk
Read	Dosya okuma	DefaultAllowed
Edit	Dosyaları düzenleme	DefaultAsk
Write	Dosya yazma	DefaultAsk
Glob	Desene göre dosya bulma	DefaultAllowed
Grep	Dosya içeriğinde arama	DefaultAllowed
WebFetch	Web adresini alma	DefaultAsk
WebSearch	Web'de arama	DefaultAsk
TodoList	Görevleri parçalara ayırma	DefaultAllowed

Bunlar terminalde Claude Code'un kullandığı araçlardır; sizin uygulamanızın bağlamında çalışırlar. Araçların var olması, onları sınırsız vermeniz gerektiği anlamına gelmez. İzinleri yalnızca gerekli en düşük kapsamda açın.

3.2 İzin sistemi: iki çalışma biçimi

İzin gerektiren bir araç çağrıldığında SDK, çağrının nasıl ele alınacağını belirlemelidir. Kaynak iki örüntüyü karşılaştırır: otomatik izin ve çalışma anında çalışan hook'lar.

Yöntem 1: otomatik izin (CI/CD için önerilen)

allowedTools içinde araca izin verebilir, örneğin Bash için her çağrıda true döndüren bir isAllowed işlevi kullanabilirsiniz. Bu ayar bütün Bash komutlarını otomatik onaylayabileceği için ancak ortamın bilindiği, izole edildiği ve güvenli biçimde sınırlandığı otomasyonlarda düşünülmelidir.

const session = await query({
  prompt: "Initialize a git repository and commit all files",
  options: {
    allowedTools: [
      { toolName: "Bash", isAllowed: () => true },
      "Read",
      "Write",
    ],
  },
});

Daha seçici bir işlev, komut metnini inceleyip yalnızca git veya npm ile başlayan komutlara izin verebilir. Bu örnekteki gibi önek kontrolü tek başına eksiksiz bir güvenlik politikası değildir: kabuk bileşimi, yönlendirmeler, alt komutlar ve argümanların anlamı daha geniş bir inceleme gerektirebilir.

allowedTools: [
  {
    toolName: "Bash",
    isAllowed: async (input) => {
      const command = input.command;
      return command.startsWith("git ") || command.startsWith("npm ");
    },
  },
]

Bu yöntem, CI/CD gibi otomatik iş akışlarında pratik olabilir; fakat yalnızca bilinen ve sınırlandırılmış bir ortamda kullanılmalıdır. Geniş izinleri kullanıcıya ait dosyalar veya kimlik bilgileri bulunan bir makinede gelişigüzel açmayın.

Yöntem 2: hook'lar — üretim düzeyinde izin denetimi

Dinamik izin politikası, kara/izin listesi veya insan onayı gerekiyorsa hook'lar araya girerek bir araç çağrısını değerlendirebilir. Örnekte PreToolUse, Bash çalışmadan önce komutu inceler; rm -rf eşleşmesini reddeder, diğer durumlar için izin kararı üretir.

const session = await query({
  prompt: "Run all tests and fix any failures",
  options: {
    hooks: {
      PreToolUse: [
        {
          matcher: "Bash",
          hook: async (input) => {
            const command = input.tool_input.command;
            if (command.includes("rm -rf")) {
              return {
                hookSpecificOutput: {
                  hookEventName: "PreToolUse",
                  permissionDecision: "deny",
                  permissionDecisionReason:
                    "rm -rf is not allowed in our CI environment",
                },
              };
            }
            return {
              hookSpecificOutput: {
                hookEventName: "PreToolUse",
                permissionDecision: "allow",
              },
            };
          },
        },
      ],
    },
  },
});

isAllowed varken neden hook gerekir? isAllowed, yalnızca allowedTools listesine alınmış bir araç için değerlendirme yapar; listede bulunmayan yeni araçlara izin veremez ve yürütme sürerken izin kapsamını yeniden düzenlemez. Hook'lar araç çalışmadan önce veya sonra (örneğin PreToolUse, PostToolUse) devreye girebilir; oturum durumunu değiştirebilir, yürütmeyi durdurabilir ya da insan onayı gibi daha karmaşık akışları uygulayabilir. Hangi davranışın mümkün olduğunu SDK sürümünüzün güncel belgelerinden doğrulayın.

3.3 Hook olay türleri

Temel olay örnekleri şunlardır:

• PreToolUse: araç çalıştırılmadan önce tetiklenir.
• PostToolUse: araç çalıştıktan sonra tetiklenir.
• Notification: ajan bildirim gönderdiğinde tetiklenir.
• UserPromptSubmit: kullanıcı istem gönderdiğinde tetiklenir.
• Stop: ajan işi bitirdiğinde tetiklenir.

Tam yaşam döngüsü daha ayrıntılı olabilir; tüm olayların ve alanların güncel listesi için Anthropic'in hook belgelerine bakın. Buradaki temel nokta, SDK'nın ajan döngüsünde görünürlük ve denetim noktaları sunmasıdır. Hook'ları tek başına güvenlik sınırı kabul etmeden önce hata durumlarını ve varsayılan davranışı da inceleyin.

---

4. Üretim hook'ları: güvenlik geçidi oluşturma

Kaynak metnin hedeflediği politika; rm -rf içeren tehlikeli silme komutlarını reddetmek, çalışma alanı dışına yazmayı (örneğin cd /etc && echo "hello" > test.txt) ve .env, /etc ya da ~/.aws/credentials gibi konumlardan kimlik bilgisi okumayı engellemek, diğer işlemlere izin vermektir. Aşağıdaki örnek kod kara listeye uyanları reddeder, izin listesindeki komutları doğrudan geçirir ve eşleşmeyen diğer komutlara izin verip denetim kaydı yazar. Kod, metinde tarif edilen çalışma alanı dışına yazma kuralını tek başına uygulamaz.

// secure-gate.ts
import { query } from "@anthropic-ai/claude-agent-sdk";

const WORKSPACE = "/home/user/project";

const DENY_PATTERNS = [
  /^\s*rm\s+(-[a-z]*\s+)*-\s*[a-z]*[r]/i,
  /^\s*sudo\s+/i,
  /^\s*curl\s+.*(\||>)/i,
  /^\s*(cat|tail|head|less|more)\s+.*\.(env|pem|key|p12)/i,
];

const ALLOW_PATTERNS = [
  /^\s*(cd|ls|pwd|git|npm|node|python3?|pip|bun|yarn|pnpm|tsc|eslint|prettier)\b/i,
];

function isSafeCommand(command: string): { allowed: boolean; reason?: string } {
  const trimmed = command.trim();

  // Block dangerous patterns
  for (const pattern of DENY_PATTERNS) {
    if (pattern.test(trimmed)) {
      return {
        allowed: false,
        reason: `Command matches dangerous pattern: ${pattern}`,
      };
    }
  }

  // If it matches our allow-list of build/test commands, let it through
  for (const pattern of ALLOW_PATTERNS) {
    if (pattern.test(trimmed)) {
      return { allowed: true };
    }
  }

  // Otherwise, allow but with audit log
  return { allowed: true, reason: "Allowed with audit" };
}

async function main() {
  const session = await query({
    prompt: "Run npm test and fix any errors",
    options: {
      allowedTools: ["Bash", "Read", "Write", "Edit"],
      hooks: {
        PreToolUse: [
          {
            matcher: "Bash",
            hook: async (input) => {
              const command = input.tool_input.command as string;
              const result = isSafeCommand(command);

              if (!result.allowed) {
                console.warn(`[SECURITY] Blocked command: ${command}`);
                console.warn(`[SECURITY] Reason: ${result.reason}`);
                return {
                  hookSpecificOutput: {
                    hookEventName: "PreToolUse",
                    permissionDecision: "deny",
                    permissionDecisionReason: result.reason,
                  },
                };
              }

              if (result.reason === "Allowed with audit") {
                console.log(`[AUDIT] ${command}`);
              }

              return {
                hookSpecificOutput: {
                  hookEventName: "PreToolUse",
                  permissionDecision: "allow",
                },
              };
            },
          },
        ],
      },
    },
  });

  for await (const message of session) {
    // consume stream
  }
}

main().catch(console.error);

Bu örnek, düzenli ifadelerle bir kara liste ve izin listesi birleştirir. Komutlar kabuk içinde birleştirilebilir veya farklı biçimde yazılabilir; bu nedenle birkaç desen tüm tehlikeli biçimleri yakalayacağını garanti etmez. Özellikle salt metin denetimi, komutun etkisini güvenilir biçimde çözümlemekle aynı şey değildir. Üretimde gerçek dosya sistemi izinleri, yalıtılmış çalışma alanı, en az ayrıcalık ilkesi, insan onayı ve denetim kayıtları kullanın. Ayrıca yalnızca dosya okuma örüntülerini engellemek, bir aracın aynı bilgiyi başka yolla almasını önlemeyebilir.

Kaynak, kurallara uymayan komutları açık bir gerekçeyle reddeden ve izin verilenleri sürdüren bir PreToolUse hook'u gösterir. Bu kod, güvenlik yaklaşımını açıklayan örnektir; her işletim sistemi ve kabuk için eksiksiz bir güvenlik ürünü olarak değerlendirilmemelidir. Kendi tehdit modelinize göre gözden geçirin ve test edin.

---

5. GitHub Actions CI/CD: ajanı otomatik geliştirici olarak kullanma

Ajanı bir CI hattına eklemek, otomasyonun kodu incelemesini veya belirli bir görev üzerinde çalışmasını sağlayabilir. Ancak otomatik değişiklikleri doğrudan güvenilir kabul etmeyin. Çalışma alanını sınırlayın, değişiklikleri gözden geçirin ve üretime geçişi mevcut onay sürecinize bağlayın.

CLI’yi --output-format stream-json ile kullanma

Kaynakta, GitHub Actions içinde Claude Code CLI'yi çalıştırıp JSON akış çıktısını dosyaya yönlendiren bir iş akışı örneği bulunur. Örnek ana dala gelen push ile tetiklenir; depoyu kontrol eder, Node.js kurar, npx üzerinden Claude Code CLI’yi başlatır ve --output-format stream-json çıktısını ister. Kaynak iş akışı düzenleme izni için --permission-mode acceptEdits kullanır; daha temkinli bir inceleme akışında --permission-mode plan seçeneğiyle önce yalnızca plan üretilebilir.

name: Agent Code Review & Fix
on:
  push:
    branches: [main]

jobs:
  agent-code-review:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx -y @anthropic-ai/claude-code@latest \
            --output-format stream-json \
            --allowedTools "Read,Write,Edit,Bash" \
            --permission-mode acceptEdits \
            "Review the code, find bugs, fix them, and create a commit"
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          branch: agent-fixes
          base: main
          title: "Agent auto-fix: code review & bug fixes"
          body: "This PR is automatically generated by claude-agent-sdk"

Önemli noktalar: ajan tarafından üretilen commit kimlik bilgilerine ve kimlik ayarlarına doğrudan güvenmek yerine peter-evans/create-pull-request eylemini kullanın. --permission-mode acceptEdits, ajanın ayrıca izin sormadan dosya düzenlemesine izin verir. Güvenlik açısından hassas iş akışlarında --permission-mode plan seçerek önce plan oluşturun ve bunu elle uygulayın. CI günlüklerinde çalışmanın akışını görmek istiyorsanız --output-format stream-json kullanın. CI içinde etkileşimli komutlar çalıştırmayın; gereken izinleri önceden tanımlayın. GitHub Actions önbelleği kurmak istiyorsanız kaynak ayrıca Claude Code dizinini önbelleğe alan bir adım önerir.

- name: Cache Claude Code
  uses: actions/cache@v4
  with:
    path: ~/.claude
    key: ${{ runner.os }}-claude-${{ hashFiles('**/package-lock.json') }}

Önbellek örneğinde Claude Code’un ~/.claude dizini tutulur. İlk CLI çalıştırmasında ortamın başlatılması kaynakta yaklaşık 30–60 saniye olarak tahmin edilir; gerçek süre değişebilir. Sık çalıştırılan iş akışlarında ~/.claude dizinini önbelleğe almak bu başlangıç adımını azaltabilir. Önbellek anahtarlarını çalıştırıcı ve kilit dosyası gibi değişikliklerle eşleştirin; hassas verileri önbelleğe koymayın. Önbellek, güvenlik veya doğrulama adımlarının yerini tutmaz.

SDK'yı Node.js CI ortamında kullanma

CLI yerine özel bir node betiği kullanmak, oturum olaylarını ve araç izinlerini programatik biçimde ele almanıza olanak verir. Kaynaktaki betik query ile oturum başlatır, stream-json olaylarını toplar ve PreToolUse hook'u aracılığıyla çalıştırılmasına izin verilen komutları denetler.

// ci-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import { execSync } from "node:child_process";
import * as fs from "node:fs";

async function runAgent() {
  const prompt = `
    You are working in a Node.js project.
    Please complete the following tasks:
    1. Read the current git diff
    2. Look for any obvious bugs or type errors
    3. Fix them
    4. Write a test for the changes
    5. Run the tests to make sure they pass
  `;

  const session = await query({
    prompt,
    options: {
      allowedTools: ["Bash", "Read", "Write", "Edit"],
      hooks: {
        PreToolUse: [
          {
            matcher: "Bash",
            hook: async (input) => {
              const command = input.tool_input.command;
              if (!["git", "npm", "node", "npx"].some((cmd) => command.trim().startsWith(cmd))) {
                return {
                  hookSpecificOutput: {
                    hookEventName: "PreToolUse",
                    permissionDecision: "deny",
                    permissionDecisionReason: `Command not allowed in CI: ${command}`,
                  },
                };
              }
              return {
                hookSpecificOutput: {
                  hookEventName: "PreToolUse",
                  permissionDecision: "allow",
                },
              };
            },
          },
        ],
      },
    },
  });

  for await (const message of session) {
    if (message.type === "stream_event") {
      // You can send this to your log aggregation system
      console.log(JSON.stringify(message.event));
    }
  }

  const diff = execSync("git diff --stat").toString();
  console.log("===== Agent Changes =====");
  console.log(diff);
}

runAgent().catch(console.error);

Bu örnekte query ajan oturumunu yürütür; hook, Bash komutlarını git, npm, node ve npx önekleriyle sınırlar. Ardından betik git diff --stat özetini alır; bu diff’e bakarak değişiklikler için PR açmaya mı yoksa doğrudan push etmeye mi karar verilebilir. Bu örnek otomatik güvenliği garanti etmez: önek denetimi kabuk komutunun tüm etkilerini doğrulamaz. Kimlik bilgilerini gizli değişkenlerde tutun, çalıştırma izinlerini daraltın ve nihai sonucu gözden geçirin; başarısızlık, tekrar deneme, zaman aşımı ve kısmi çıktı durumlarını da tasarlayın.

---

6. Çoklu ajan işbirliği: görevleri ajanlar arasında bölme

Kaynağın önerdiği pratik çoklu ajan düzeni, karmaşık bir “supervisor” modeli yerine alt ajanlar ile bir ardışık iş hattını (sub-agent + pipeline) birleştirir. Her ajanı dev bir isteme yük bindirmek yerine kendi hedefi ve izin kapsamı olan bağımsız çalıştırmalara ayırarak görev sınırlarını açıklaştırabilirsiniz. Örneğin ödeme modülünü yeniden düzenleme ve test ekleme isteğini üç role ayırabilirsiniz: mevcut kodu okuyup plan çıkaran Keşif ajanı; planı uygulayıp testleri çalıştıran Uygulayıcı ajan; diff'i inceleyerek hata, güvenlik sorunu ve kod kalitesi hakkında rapor hazırlayan Gözden Geçirme ajanı.

Örnek: kodu yeniden düzenleme hattı

Aşağıdaki örnek runAgent yardımcı işleviyle oturum açar, Bash çağrılarında rm -rf komutunu engeller ve akıştaki sonuç metnini döndürür. Ardından üç rolü sırayla çalıştırır; sonraki rol öncekinin çıktısını istemine ekler.

// multi-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as fs from "node:fs";

interface AgentResult {
  sessionId: string;
  finalText: string;
  output: string;
}

async function runAgent(
  prompt: string,
  allowedTools: any[],
  sessionId?: string
): Promise<AgentResult> {
  const session = await query({
    prompt,
    options: {
      allowedTools,
      ...(sessionId ? { resume: sessionId } : {}),
      hooks: {
        PreToolUse: [
          {
            matcher: "Bash",
            hook: async (input) => {
              if (input.tool_input.command.includes("rm -rf")) {
                return {
                  hookSpecificOutput: {
                    hookEventName: "PreToolUse",
                    permissionDecision: "deny",
                    permissionDecisionReason: "rm -rf is prohibited",
                  },
                };
              }
              return {
                hookSpecificOutput: {
                  hookEventName: "PreToolUse",
                  permissionDecision: "allow",
                },
              };
            },
          },
        ],
      },
    },
  });

  const messages = [];
  for await (const message of session) {
    if (message.type === "stream_event") {
      messages.push(message.event);
      if (message.event.type === "result") {
        return {
          sessionId: session.sessionId,
          finalText: message.event.result,
          output: JSON.stringify(messages),
        };
      }
    }
  }
  throw new Error("Agent did not produce a result");
}

async function main() {
  // Step 1: Explorer Agent — read and plan
  const explorerResult = await runAgent(
    `You are the code explorer. Read the payment module under src/payments/.
     Analyze the current structure and potential issues. Output a concise
     refactoring plan with specific file paths and actions.`,
    ["Read", "Glob", "Grep"]
  );

  console.log("===== Explorer Agent Plan =====");
  console.log(explorerResult.finalText);

  // Step 2: Implementer Agent — execute the plan
  const implementerResult = await runAgent(
    `You are the implementer. Here is the refactoring plan from the explorer:

    ${explorerResult.finalText}

    Implement the plan. Edit the code, make the changes, and run the tests
    to make sure everything passes.`,
    ["Read", "Write", "Edit", "Bash"]
  );

  console.log("===== Implementer Agent Result =====");
  console.log(implementerResult.finalText);

  // Step 3: Reviewer Agent — review the changes
  const reviewResult = await runAgent(
    `You are the code reviewer. Here is what the implementer did:

    ${implementerResult.finalText}

    Review the current git diff and the files that were changed.
    Look for bugs, security issues, and code quality issues.
    Write a detailed review report.`,
    ["Read", "Bash", "Glob", "Grep"]
  );

  console.log("===== Reviewer Agent Report =====");
  console.log(reviewResult.finalText);
}

main().catch(console.error);

Bu model neden daha sürdürülebilir olabilir?

• Her çalıştırmada yalıtılmış bağlam: yeni ajan, önceki tüm konuşmayı taşımak zorunda kalmaz; bu, bağlam taşması riskini azaltabilir.
• Görev sınırları: analiz, uygulama ve inceleme ayrıldığında rollerin araç ve izin kapsamları da ayrılabilir. Örneğin uygulayıcı yazma iznine sahipken gözden geçiren yalnızca okuma izni alabilir.
• Gözlemlenebilirlik: her aşamanın planı, değişiklikleri veya inceleme raporu ayrı çıktıdır; saklanabilir ve denetlenebilir.
• Hata yönetimi: bir aşama başarısız olursa yeniden deneyebilir veya önceki aşamanın özlü sonucundan devam edebilirsiniz. Bununla birlikte ajan çıktısı doğrulanması gereken girdidir; sonraki aşamada körü körüne güvenilmemelidir.

---

7. Özet: SDK, ajan çağının giriş kapısıdır

Özetle, bu SDK'da çalışma bir oturum etrafında düzenlenir; durum yönetimini SDK üstlenir ve devam etmek için oturum kimliğini kullanabilirsiniz. Yerleşik araçlar, izin ayarları ve hook'lar ajan döngüsünü denetlemenize yardım eder: isAllowed statik araç izni için, hook'lar ise yürütme sırasında dinamik kararlar için kullanılabilir. query() ile CI/CD iş akışlarına oturum ekleyebilir; ayrı oturumları düzenleyerek çoklu ajan hattı kurabilirsiniz. CLI basit terminal ve CI entegrasyonlarına, SDK ise özel uygulama içi akışlara uygundur.

Kendi ajan döngümü yazmaya devam etmeli miyim?

Her zaman değil. Özel gereksinimleriniz yoksa hazır ajan SDK'sı tekrar eden döngü, araç ve oturum yönetimi işini azaltabilir. Daha düşük seviyeli kontrol gerekiyorsa Anthropic'in temel SDK'sını doğrudan kullanabilirsiniz. Üretim kullanımında seçiminizi modülerlik, izin kapsamı, gözlemlenebilirlik ve bakım gereksinimine göre yapın; hiçbir SDK uygulamanızın güvenlik ve doğrulama sorumluluğunu ortadan kaldırmaz.

Yapay zekâ mühendisliğinde önemli olan yalnızca yenilik iddiası değil; süreç, izin, gözlemlenebilirlik ve ölçülü uygulamadır. Bu SDK, ajan uygulamaları kurmak için bir araçtır; her senaryoda tek doğru çözüm olduğuna dair garanti değildir.

Kaynaklar

• Claude Agent SDK belgeleri
• Claude Code hook rehberi
• Claude Code GitHub Actions rehberi

---

Bu yazı Claude tarafından çevrilmiştir. Çeviride bir sorun fark ederseniz lütfen bildirin.