Claude Opus 5.5 API Eğitimi: Bir Yapay Zekâ Olay Araştırıcısı Oluşturun

Bu eğitimde bir senaryoyu test edeceğim: Bir yazılım güncellemesinden birkaç dakika sonra, bu senaryo için kullanacağım HarborCart — ödeme adımında hatalar görmeye başlıyor. Bazı müşteriler 30 saniyeden fazla bekliyor; diğerleri sunucu hatası görüyor ve ödeme yapamıyor. Ödeme sağlayıcısında da kısa bir kesinti var, bu yüzden bariz neden o gibi duruyor.

Ancak sağlayıcı kesintisi, sepet ve sipariş sayfalarının da neden başarısız olduğunu açıklamıyor. Kayıp halkayı bulmak için uygulama günlükleri, grafikler, istek kayıtları ve yakın zamanda yapılan kod değişikliği gerekiyor. Bu eğitim, Claude Opus 5.5'in bu kanıtları takip edip açıklamasını kontrollü koşullarda test edip yalnızca kanıtların desteklediğini raporlayıp raporlayamayacağını sınar.

Biraz arka plan: Claude Opus 5.5, bu projeye başlamadan hemen önceki hafta geldi. Claude Opus 5.5 genel bakışımız lansmanı ve kıyaslamaları kapsıyor, bu nedenle bu eğitim API üzerinde kalıyor ve ilk istekte başlayan, doğrulanmış rapora kadar giden tek bir soruşturma aracını inşa ediyor.

Şunları ele alacağız:

• İlk Claude Opus 5.5 çağrınızı yapın ve içerik bloklarını türüne göre okuyun
• Aracıya okuma yetkili araçlar verin; katı şemalar
• Claude'un kendi kodunun günlükleri ve izleri süzmesine izin verin; programatik araç çağrımı
• Ekran görüntülerini hipotez olarak ele alın ve metriklerle karşılaştırın
• Bir karşıolgusal yeniden oynatmayla kök nedeni test edin
• Aynı kanıtlara karşı effort seviyelerini karşılaştırın
• "sonuçsuz" demesine izin verilen bir yapılandırılmış rapor döndürün
• Araştırma maliyetini API kullanım kayıtlarından hesaplayın

Özet

HarborCart'ın araştırıcısı, ödeme ağ geçidi patlamasını onu büyüten yeniden deneme ilkesinden ayırdı, ardından bu açıklamayı test edip bir rapor döndürdü.

• Ağ geçidi hatası tetikleyicidir, tam kök neden değildir. Yeniden denenen tahsilatlar, ağ geçidini hiç çağırmayan uç noktaları bile düşürecek kadar uzun süre veritabanı bağlantılarını elde tutar.
• Araştırma ve raporlama ayrı istekler kullanır. Web araması ve atıflar araştırma sırasında kullanılabilir; ikinci bir istek doğrulanmış kanıtları JSON olarak biçimler.
• Programatik araç çağrımı, serileştirilmiş kanıtları %98,8 azalttı. Üç araştırma boyunca, 142,8 KB araç sonucu, modele geri dönen 1,7 KB özet haline geldi.
• Daha yüksek effort temel yeniden oynatma planını değiştirmedi. Orta ve yüksek, aynı hipotezi ve temel nedensel testleri seçti.
• Ölçülen üç tam araştırmanın ortalaması 2 dakika civarında ve 0,2737 ABD dolarıydı.

Claude Opus 5.5 API Nedir?

Claude Opus 5.5'e Anthropic'in Messages API'ı üzerinden claude-opus-5-5 model kimliğiyle erişirsiniz. Model genel bakışına göre metin ve görsel alır, 1M belirteçlik bağlam penceresi ve 128K maksimum çıktı sunar. Uyarlanabilir düşünme her zaman açıktır ve varsayılan effort medium seviyesindedir.

Standart fiyatlandırma milyon giriş belirteci başına 4 ABD doları ve milyon çıkış belirteci başına 20 ABD dolarıdır. Beş dakikalık önbellek yazımları milyon başına 5 ABD doları ve önbellek okumaları 0,20 ABD dolarıdır. İstem önbellekleme etkin olduğunda, eşleşen önekler bu daha düşük önbellek okuma oranından ücretlendirilir.

Claude Opus 5'ten ne değişti?

Şu geçiş kılavuzundan dört nokta bu projede doğrudan karşımıza çıkıyor.

• Zorunlu tool_choice değerinin any ya da adlandırılmış bir araçla kullanılması 400 hatası döndürür.

• Varsayılan effort, Claude Opus 5'teki high seviyesinden medium seviyesine düştü.

• Düşünme kapatılamaz ve thinking blokları, araç döngüsü içinde değiştirilmeden geri gönderilmelidir.

• Araç çağrıları arasında modelin yazdığı notlar thinking blokları içinde gelir ve varsayılan olarak boştur.

Claude Opus 5.5 ile Ne İnşa Edeceğiz?

Aracı yalnızca araştırma yapar. Okuma yetkili kanıt araçlarına sahiptir ve üretim kimlik bilgileri yoktur. Kanıt toplamanın ardından, ayrı planlama istekleri karşıolgusal testler önerir ve Python orta effort planını doğrular ve çalıştırır.

Tüm kod, kanıt üretici ve web uygulaması dahil, şu GitHub deposunda.

HarborCart ödeme adımında ne oldu?

HarborCart kurgusal bir mağazadır. checkout-api sepet sayfalarına, sipariş durumuna ve üçüncü taraf bir ödeme ağ geçidini tahsil eden POST /checkout uç noktasına hizmet verir. Bu uç noktaların hepsi, örnek başına 15 bağlantıdan oluşan tek bir PostgreSQL havuzunu paylaşır.

Bir dağıtım yapılır ve beş dakika sonra ağ geçidi yaklaşık 90 saniye boyunca 503 döndürür. Ödeme gecikmesi 30 saniyeyi aşarken havuz 15'te 15 dolu kalır. Ödeme sağlayıcısını suçlamak kolaydır ve ağ geçidi gerçekten de başarısız olmuştur.

Gizli neden bir adım daha içeridedir. Dağıtım, başarısız POST tahsilatların üç kez yeniden denenmesine, yani toplam dört tahsil denemesine ve işleyici veritabanı bağlantısını elinde tutarken bekleme olmadan izin verdi. Artık yavaş başarısız olan tahsilatlar 30 saniye veya daha uzun süre bağlantıları elde tutuyor, havuz tükenene kadar ve ağ geçidini hiç çağırmayan sepet sayfaları da başarısız oluyor.

Buradan itibaren üç terimi tutarlı biçimde kullanıyorum. Burada tetikleyici geçici ağ geçidi hatasıdır. Kıt veritabanı bağlantılarını elde tutarken ödeme POST'larını yeniden denemek büyütme mekanizmasıdır; paylaşılan bağlantı havuzunun tükenmesi ise sistem arızasıdır.

Aracı hangi kanıtları inceleyebilir?

Aracı uyarıyla, bir izleme ekran görüntüsüyle ve bir mimari diyagramla başlar. Diğer her şey araçlar üzerinden gelir: günlükler, izler, beş metrik, dağıtım metaverisi, Git diff ve bir runbook. Kanıtların içine üç rakip açıklama tohumlanmıştır: bir stok uyarısı, bir frontend uyarısı ve olası CPU doygunluğu.

HarborCart ödeme yolu ve paylaşılan havuz. Görsel: Yazar.

Diyagram, bağlantının tüm istek boyunca elde tutulduğunu söylüyor. Bunun bir sorun olduğunu söylemiyor; araştırmanın bunu ortaya çıkarması gerekiyor.

Teşhisin doğru olduğunu nasıl bileceğiz?

Aracıyı oluşturmadan önce başarıyı tanımlayın. Doğru bir rapor şunları yapmalıdır:

• POST yeniden denemelerine izin veren yeniden deneme değişikliğini adlandırmak
• Veritabanı bağlantısının ağ geçidi çağrısı boyunca elde tutulduğunu belirtmek
• Daha uzun elde tutmaların havuzu nasıl tükettiğini açıklamak
• Ağ geçidi patlamasını büyütme mekanizması değil tetikleyici olarak ele almak
• Üç alternatif açıklamadan en az ikisini reddetmek
• Diff ve bir metrik dahil somut kanıtlar belirtmek
• Kararın sonuçla eşleştiği bir karşıolgusal yeniden oynatma içermek

Claude Opus 5.5 API’sini Python’da Nasıl Kullanılır

Python 3.10 veya daha yenisine ve claude-opus-5-5 erişimi olan bir Anthropic API anahtarına ihtiyacınız var. Bu PowerShell komutları projeyi klonlar ve sabitlenmiş bağımlılıkları, anthropic 1.8.0 dahil, kurar. Amazon Bedrock kullanıyorsanız, birkaç özelliğin taşınmayacağı için önce SSS’leri okuyun.

git clone https://github.com/KhalidAbdelaty/opus-5-5-api-tutorial.git
cd opus-5-5-api-tutorial
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

macOS veya Linux’ta, source .venv/bin/activate ile etkinleştirin ve cp .env.example .env ile kopyalayın. Anahtarınızı .env dosyasına ekleyin; python-dotenv bunu SDK için yükler; ortam değişkenleri rehberimiz deseni açıklar. Python’dan daha önce Claude çağırdıysanız, yalnızca kurulumu doğruladığı için bir sonraki alt bölümü atlayın.

İlk Claude Opus 5.5 API çağrınızı yapın

En küçük faydalı istek anahtarı doğrular ve geri gelenleri gösterir.

import anthropic
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "A checkout API returns HTTP 503 right after a deploy. Name the first two things to check."}],
)
print([block.type for block in response.content])
text = "".join(block.text for block in response.content if block.type == "text")

Bu istekte, yanıt thinking ve text blokları içerir. response.content[0] okumak yerine blokları türüne göre seçin.

Claude Opus 5.5 Araç Çağıran Bir Aracı Nasıl İnşa Edilir

Araç çağıran aracılar, Claude’un Messages API’sini veri erişimini denetleyen Python işlevleriyle eşleştirir. Uygulama tek bir kuralı takip eder: Claude hangi kanıta ihtiyaç duyduğuna karar verir, Python ise neye erişebileceğine karar verir.

Daha geniş araç sınırları ve döngülerini aracı harness mühendisliği rehberimiz kapsar; HarborCart araçlarını yalnızca okuma amaçlı ve bu olaya sınırlı tutar.

Yalnızca okuma olay araçlarını tanımlayın

Her araç sabit bir kanıt kümesini okur ve sınırlı bir JSON sonucu döndürür. Günlük ve iz sorguları en fazla 200 satır artı bir sayı döndürür ve metrik sorguları en fazla 60 nokta döndürür.

Programatik araç çağrımı strict: true desteklemez, bu yüzden araçları ikiye bölün. Kanıt kontrollerini ve araştırmayı bitirme aracını katı ve yalnızca doğrudan çağrılabilir tutun. Günlükler, izler ve metrikler yalnızca kod yürütme kullanır; bu da büyük kanıt sorguları için Claude’a tek bir açık yol verir.

{"name": "finish_investigation", "strict": True,
 "allowed_callers": ["direct"],
 "input_schema": {"type": "object",
                  "properties": {"summary": {"type": "string"}},
                  "required": ["summary"],
                  "additionalProperties": False}},
{"name": "query_traces",
 "allowed_callers": ["code_execution_20260120"],
 "input_schema": {...}},

allowed_callers modeli yönlendirir ancak bir güvenlik sınırı değildir. Python, her aracı çalıştırmadan önce çağıranı kontrol eder ve doğrudan bir sorgu çağrısını reddeder. Programatik çağrılar katı doğrulamayı da atlar, bu nedenle sorgu işlevleri yine de kendi argümanlarını doğrular.

Uygulama, kabul edilen her araç sonucunu etiketler, eksik kanıtları alıntılayan bulguları reddeder ve yalnızca web araması tarafından döndürüldüğünde dokümantasyon URL’lerini kabul eder. Model değil, Python yeniden oynatma çıktıları kaydeder.

Zorunlu araç seçimi yerine katı şemalar kullanın

Geçiş bölümünde belirtildiği gibi, tool_choice değerini auto olarak tutun. Bir aracın ne zaman uygulanacağını istemde söyleyin ve argümanların tam olması gerektiği yerlerde katı şemalar kullanın.

Çok turlu araştırma döngüsünü oluşturun

Döngü, konuşmayı gönderir, varsa tool_use bloklarını çalıştırır, sonuçları ekler ve tekrarlar. Yardımcının bloklarını, düşünme dahil, değiştirmeden ekleyin ve programatik kod duraklatılmışken yalnızca tool_result bloklarıyla container kimliğini geri iletin.

Araştırma isteği görsel, araçlar, web araması, effort ve görev bütçesini içerir, ancak çıktı şeması içermez. Bu, atıf içeren arama sonuçlarını yapılandırılmış JSON çıktıdan uzak tutarken, kararlı istek ön eki istem önbelleğini etkin tutar:

request = dict(
    model="claude-opus-5-5",
    max_tokens=16_000,
    system=[{"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    tools=investigation_tools,
    cache_control={"type": "ephemeral"},
    thinking={"type": "adaptive", "display": "updates"},
    output_config={
        "effort": "medium",
        "task_budget": {"type": "tokens", "total": 20_000},
    },
    betas=["task-budgets-2026-03-13", "thinking-display-updates-2026-08-18"],
)

Claude Opus 5.5 API’sine Görseller Nasıl Gönderilir

Gösterge panosunu ve mimari diyagramı ilk kullanıcı mesajına base64 PNG olarak ekleyin. Claude’a bir görselden okuduğu her şeyi bir hipotez olarak ele almasını ve bunu query_metrics ile doğrulamasını söyleyin.

Pano havuz doygunluğunu, CPU’nun sabit kaldığını gösteriyor. Görsel: Yazar.

Hem pano hem de metrik sorguları aynı kaynak veriyi kullanır. Havuz doluyken CPU %30 civarında kalır; bu da herhangi bir sorgu çalışmadan önce "ana makine aşırı yükte" tezine karşı bir argümandır.

Görsel gözlemleri ham metriklerle çapraz kontrol edin

Ekran görüntüsü nereye bakılacağını önerir, ancak sayısal seri gözlemin geçerli olup olmadığını belirler. Görsel bir hipotez üretir; metrikler bunu test eder.

Görsel öncelikli iş akışları için aracısal görsel eğitimi rehberimize bakın. HarborCart görseli yalnızca bir sonraki metriği seçmek için kullanır.

Claude Opus 5.5 Programatik Araç Çağrımı Nasıl Çalışır?

Programatik araç çağrımı, Claude’un bir kod yürütme konteynerinde çalışan ve araçlarınızı işlev olarak çağıran Python kodu yazmasına olanak tanır. Ham sonuçlar kum havuzunda kalır ve yalnızca kodun yazdırdığı çıktı modele ulaşır.

Günlükler ve izler arasında fan-out yapın

Aracı, başarısız izleri çeken ve yalnızca uç nokta başına sayıları yazdıran kısa betikler yazar. Tam bir araştırmada, programatik araç çağrımı modele döndürülen serileştirilmiş kanıtı %98,8 azalttı. Araç sonuçları 42,9 KB, özetler 0,5 KB idi; bu, faturalandırılan giriş belirteci tasarrufu değil bayt ölçüsüdür.

Araç çağrıları olay kanıtını daraltır. Görsel: Yazar.

Belirsiz bağımlılık davranışı için dokümantasyon araması ekleyin

Uygulama, yeniden deneme kütüphanesi semantiği için kısıtlı web araması sunar. Claude, nihai değerlendirme sırasında bunu çağırmadı; bu nedenle ölçülen teşhis diff, metrikler, günlükler ve izlere dayanır. urllib3 başvurusu bağımsız olarak allowed_methods=None değerinin herhangi bir fiili yeniden denediğini ve backoff_factor=0 beklemeyi kaldırdığını doğrular, ancak bu sayfa ölçülen kanıtın parçası değildir.

Karşıolgusal Yeniden Oynatma ile Kök Neden Nasıl Doğrulanır

Karşıolgusal yeniden oynatma, olay trafiğini şüpheli nedenlerden biri kaldırılmış şekilde yeniden çalıştırır ve hatanın ortadan kalkıp kalkmadığını kontrol eder. "Bu çizgiler birlikte yükseliyor" ifadesini bir teste dönüştürür.

Yeniden oynatmayı dürüst tutun

Yeniden oynatma aynı trafik desenini yeniden kullanır. Aşağıdaki karşılaştırmada her senaryo tek bir koşulu değiştirir ve uygulama hangi değişikliklere izin verileceğini kontrol eder.

Özet, ağ geçidi 503'lerini havuz zaman aşımlarından ve ödeme 503'lerini sepet ve sipariş okumalarından ayırır. Bu ayrım modelin tetikleyiciyi büyütenden ayırt etmesini sağlar.

Her yeniden oynatma tam olarak bir şeyi değiştirir. Görsel: Yazar.

Temel yeniden oynatma 124 adet 503 üretti: 105 havuz zaman aşımı, buna 68 okuma uç noktasındaki hata dahil, ve 19 ağ geçidi hatası. Yeniden deneme politikasını geri almak her havuz zaman aşımı ve okuma hatasını kaldırdı ancak ödeme adımında 93 ağ geçidi 503’ünü ortaya çıkardı. Ağ geçidi çağrısından önce bağlantıyı serbest bırakmak da havuz hatalarını kaldırdı ancak 33 ağ geçidi 503’ünü bıraktı ve ağ geçidi patlamasını kaldırmak hataları ortadan kaldırdı.

Yeniden oynatma değiş tokuşu ortaya koyuyor: Bir geri alma, paylaşılan havuzu korur ancak daha fazla ödeme hatasının geçmesine izin verir. Bunu geçici bir önlem olarak kullanın. Ardından bir idempotency anahtarı ekleyin ki tekrarlanan bir tahsilat iki kez faturalandıramasın ve ağ geçidi çağrısı sırasında bağlantıyı elde tutmayı bırakın.

Doğrulamayı koda kural yapın

Sistem istemi bir yeniden oynatma ister, ancak bir istem bir yaptırım mekanizması değildir. Döngü, yeniden oynatma kanıtı olup olmadığını kontrol eder ve test edilmemiş bir teşhisi reddeder.

Bu kontrolü Python’da tutun. Daha keskin bir istem uyumu artırabilir, ancak bunu garanti edemez.

Claude Opus 5.5 ile Effort ve Görev Bütçeleri Nasıl Kullanılır

Effort, Claude’un adım başına ne kadar muhakeme ettiğini belirler ve bir görev bütçesi tüm döngünün ne kadar iş yapması gerektiğini belirler. Claude Opus 5 API eğitimimiz beş effort seviyesinin tümünü karşılaştırır; burada, orta ve yüksek, yeniden oynatma öncesinde aynı kanıtı alır.

Aynı kanıt üzerinde orta ve yükseği karşılaştırın

Üretim medium seviyesinde kalır. Yeniden oynatmadan önce uygulama, orta ve yüksek efforttan aynı kanıttan nedensel bir test tasarlamasını ister. Yalnızca orta öneri yürütülür; yüksek yanıt yalnızca karşılaştırma için kullanılır.

Yüksek istek, mid-conversation-output-config-2026-07-01 arkasında mesaj başına bir output_config.effort değişikliği kullanır. Orta cevabı görmez.

Her iki effort seviyesi de aynı hipotezi ve aynı üç temel yeniden oynatma senaryosunu seçti. Yüksek seviye ortalama 2.631 çıkış belirteci kullandı; orta seviye 2.307; nedensel testi değiştirmeden yaklaşık %11 daha pahalıya mal oldu.

Tüm döngü için bir görev bütçesi belirleyin

Tahmin etmek yerine gözlemlenen kullanımdan bir görev bütçesi seçin. HarborCart’ın sınırlandırılmamış en büyük araştırması, model çıktısı ve Claude’un gördüğü araç-sonucu metni dahil, 13.322 sayılan belirteç tüketti. %25 marj eklemek 16.653 eder; bu Anthropic’in 20.000 belirteçlik asgari sınırının altındadır, bu yüzden yapılandırılan bütçe 20.000’dir.

Dönüş sayısı ve geçen süreyi uygulama sınırları olarak tutun. Deney çalıştırıcısı, kaydedilen harcama 2,50 ABD dolarına ulaştıktan sonra yeni iş başlatmayı durdurdu. Bu, devam eden bir isteğin bunun üzerinde tamamlanabileceği için katı bir üst sınır değildir.

Claude Opus 5.5 Yapılandırılmış Çıktıları Nasıl Kullanılır

Nihai yanıt, yapılandırılmış çıktılar kullanır. Düz şema, sonucu, nedeni, reddedilen hipotezleri, kanıtları ve düzeltmeyi kapsar. Maliyet ve gecikme dışarıda kalır çünkü uygulama bunları ölçer.

Araştırmayı raporlamadan ayırın

Web araması atıfları ile output_config.format aynı isteği paylaşamaz: atıflar iç içe geçmiş içerik blokları gerektirirken şema JSON ister. Bu nedenle HarborCart, bir çıktı şeması olmadan araştırır. Bulguları kaynaklarına ve yeniden oynatma sonuçlarına bağlı şekilde depolar, ardından yalnızca bu doğrulanmış kanıtları araçsız ve web aramasız ikinci bir isteğe gönderir.

import json

report_response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16_000,
    system=report_instructions,
    messages=[{"role": "user", "content": json.dumps(verified_evidence)}],
    output_config={
        "effort": "medium",
        "format": {"type": "json_schema", "schema": report_schema},
    },
)

İkinci istek yalnızca doğrulanmış kanıtlara ihtiyaç duyar, bu nedenle tam araştırma önbelleğini korumak gerekli değildir.

"inconclusive" değerine verdict alanında izin verin. Yeniden oynatma açıklamasıyla çeliştiğinde bir raporun doğrulanmış bir teşhise zorlanmaması gerekir.

Şemaya uygun olmak doğru olmak değildir

Şema, raporun biçimini doğrular; yeniden oynatma ise teşhisi doğrular. Bir reddetme de stop_reason: "refusal" ile HTTP 200 döndürür ve şemanıza uymayabilir, bu nedenle ayrıştırmadan önce durdurma nedenini kontrol edin.

Claude Opus 5.5 Gerçek Kök Nedeni Buldu mu?

Üç nihai raporun tümü temel nedensel mekanizmayı buldu ve üç alternatif açıklamayı çürüttü. İkisi sekiz kontrolün tamamını karşıladı; üçüncüsü, açık POST-yeniden deneme yapılandırma değişikliğini atladığı ve dağıtım diff’ini atıf olarak belirtmediği için 6/8 puan aldı. Bu yüzden çevrimdışı puanlama şema doğrulamasından ayrı kalır: Geçerli JSON ve doğru teşhis yine de eksik bir rapor üretebilir.

Raporlar ayrıca ikinci bir riski de belirtiyor: Bir tahsilatı yeniden denemek bir müşteriyi iki kez faturalandırabilir. RFC 9110, POST’u doğası gereği idempotent olarak tanımlamaz ve istemci işlemi güvenle tekrarlayabileceğini bilmedikçe otomatik yeniden denemeleri önermeyin der. Ödeme sağlayıcısının desteklediği bir idempotency anahtarı, bu yeniden denemeleri daha güvenli hale getirmenin yaygın bir yoludur.

Streamlit eğitimimiz arayüz kurulumunu kapsar. HarborCart’ın arayüzü, araştırma olaylarını, orta ve yüksek yeniden oynatma planlarını, yeniden oynatma sonuçlarını, nihai raporu ve maliyeti gösterir. Araç çağrıları arasında durum için, Claude Opus 5.5 başvuru rehberi display: "updates" özelliğini açıklar; uygulama ayrıca bir güncelleme bloğu boş olduğunda araç olaylarını da işler.