Açık Ajan SDK Derinlemesine İnceleme (2. Bölüm): 34 Yerleşik Araç Arkasındaki Sır

Önceki makale, Ajan Döngüsü'nün nasıl çalıştığını analiz etti ve 'araçları çalıştırma' adımını ele aldı. LLM, 'Bash'i çağırmam gerekiyor' dediğinde, SDK aslında bir işlem oluşturur ve komutu çalıştırır. Ancak bu araç sisteminin arkasındaki mekanizma, basitçe 'bir fonksiyonu çağırmak'tan çok daha karmaşıktır. 34 yerleşik araç nasıl organize edilir? LLM'nin JSON girişini Swift türlerine nasıl dönüştürülür? Hangi araçların kullanılabilir olduğu nasıl kontrol edilir?

AraçProtokolü: Bir Araç Nasıl Görünür

Her araç, SDK'da AraçProtokolü protokolüne uyar. Bu protokol, bir aracı tanımlamak için beş özellik ve bir yöntem içerir.

public protocol ToolProtocol: Sendable { 
    var name: String { get } 
    var description: String { get } 
    var inputSchema: ToolInputSchema { get } 
    var isReadOnly: Bool { get } 
    var annotations: ToolAnnotations? { get } 
    func call(input: Any, context: ToolContext) async -> ToolResult 
}

name özelliği, aracın benzersiz tanımlayıcısıdır. LLM, tool_use bloklarında hangi aracı çağırmak istediğini bu ad kullanarak belirtir. Tüm yerleşik araçlar, PascalCase adlandırmayı kullanır: Read, Bash, Glob, CronCreate.

description özelliği, LLM'ye gösterilen araç açıklamasıdır. Bu metin, API'ye gönderilen araç tanımı的一部分idir ve kalitesi, LLM'nin bu aracı çağırmaya karar vermesini doğrudan etkiler.

inputSchema özelliği, aracı kabul ettiği girdi yapısını tanımlayan bir JSON Şeması sözlüğüdür. API çağrılarında input_schema alanına doğrudan geçirilir.

isReadOnly özelliği, Ajan Döngüsüne aracın yan etkileri olup olmadığını bildiren bir boolean bayrağıdır. Önceki makalede bahsedildiği gibi, Ajan Döngüsü bu alanı bucketing için kullanır: salt-okunur araçlar paralel olarak çalıştırılır, mutasyon araçları seri olarak çalıştırılır.

annotations özelliği, dört boolean alan içeren isteğe bağlı davranış ipuçlarını içerir.

public struct ToolAnnotations: Sendable, Equatable { 
    public let readOnlyHint: Bool 
    public let destructiveHint: Bool 
    public let idempotentHint: Bool 
    public let openWorldHint: Bool 
}

destructiveHint özelliği, varsayılan olarak true değerini alır — SDK, 'varsayılan olarak tehlikeli' bir yaklaşım benimser ve araçların kendilerini proaktiv olarak güvenli olduklarını beyan etmelerini gerektirir. Bu ipuçları, SDK'nin kendi yürütme mantığını etkilemez, ancak LLM, araçları nasıl kullanacağına karar verirken bunlara başvurur.

Üç Katmanlı Araç Mimarisi

SDK, 34 aracı üç kategoriye ayırır: Core (10), Advanced (11) ve Specialist (13).

Core Seviye (10) İlerleyici Seviye (11) Uzman Seviye (13) ┌──────────┐ ┌──────────────┐ ┌───────────────┐ │ Read │ │ Agent │ │ CronCreate │ │ Write │ │ Skill │ │ CronDelete │ │ Edit │ │ TaskCreate │ │ CronList │ │ Glob │ │ TaskGet │ │ LSP │ │ Grep │ │ TaskList │ │ Config │ │ Bash │ │ TaskOutput │ │ TodoWrite │ │ AskUser │ │ TaskStop │ │ EnterPlanMode │ │ ToolSearch│ │ TaskUpdate │ │ ExitPlanMode │ │ WebFetch │ │ SendMessage │ │ EnterWorktree │ │ WebSearch │ │ TeamCreate │ │ ExitWorktree │ └──────────┘ │ TeamDelete │ │ RemoteTrigger │ │ ListMcpRes │ │ NotebookEdit │ └──────────────┘ │ ReadMcpRes │ └───────────────┘

Kategori ayrımı, teknik uygulama zorluğuna değil, araçların genel kullanım amaçlarına dayanır. Gelecekte, bu araçların geliştirilmesine ve yeni araçların eklenmesine devam edeceğiz. Açık Ajan SDK, geliştiricilerinLarge Language Model'lerle daha fazla şey yapabilmesine olanak tanıyan güçlü bir araç seti sunar.