Claude API ile Python Chatbot: Adım Adım Rehber (2026)

Claude API ile Python’da chatbot yapmak düşündüğünüzden kolay. Bu rehberde SDK’yı kuracak, ilk çağrıyı yapacak, konuşma geçmişini ve streaming’i adım adım uyguladıktan sonra çalışan bir müşteri destek botuna ulaşacaksınız.

Claude API ile Python: Neden Bu Kombinasyon?

Chatbot için iki şeye ihtiyaç var: iyi bir büyük dil modeli ve onu yönetebilecek bir programlama dili. Python bu ikinci tarafta sağlam duruyor. Kütüphane seçeneği geniş, sözdizimi okunabilir, prototipten üretime geçiş hızlı.

Claude API ise konuşma kalitesi ve uzun bağlam desteğiyle öne çıkıyor. Anthropic’in resmi Python SDK’sı erişimi birkaç satıra indiriyor; aynı SDK ile hem küçük prototip hem büyük üretim sistemi kurabilirsiniz.

Gereksinimler ve Kurulum

Başlamak için şunlar gerekiyor: Python 3.8 veya üstü, Anthropic hesabı ve API anahtarı, pip.

Anthropic API anahtarı edinme:

1. console.anthropic.com adresine gidin
2. Hesap oluşturun veya giriş yapın
3. “API Keys” bölümünden yeni anahtar üretin

SDK kurulumu:

pip install anthropic

API anahtarını doğrudan koda yazmayın. Güvenlik açığı oluşturur; bunun yerine .env dosyası kullanın:

# .env dosyası
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

Python’da bu değişkeni okumak için python-dotenv ekleyin:

pip install python-dotenv

Bağımlılıkları bir requirements.txt dosyasıyla yönetin:

anthropic>=0.34.0
python-dotenv>=1.0.0

İlk API Çağrısı: Basit Mesaj Gönderme

Kurulum bitti mi? İlk mesajı gönderebilirsiniz. Aşağıdaki kod temel yapıyı gösteriyor:

import anthropic
from dotenv import load_dotenv

load_dotenv()  # .env dosyasını yükle

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY ortam değişkeninden okur

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Python'da liste ve tuple arasındaki fark nedir?"}
    ]
)

print(message.content[0].text)

messages.create() üç zorunlu parametre alıyor:

• model: Hangi Claude modelini kullandığınız
• max_tokens: Yanıttaki token üst sınırı
• messages: Sohbet geçmişi listesi

Yanıt message.content[0].text ile okunur. Harcanan token sayısını da izleyebilirsiniz:

print(f"Giriş token sayısı: {message.usage.input_tokens}")
print(f"Çıkış token sayısı: {message.usage.output_tokens}")

Token sayımı ve bağlam penceresi hakkında daha fazla bilgi için LLM tokenizasyon rehberimize bakın.

Multi-Turn Sohbet: Konuşma Geçmişi Yönetimi

Gerçek bir chatbot tek mesajla çalışmaz; önceki turları hatırlaması gerekir. Claude API durumsuzdur, yani her istekte tam geçmişi göndermeniz gerekiyor.

import anthropic
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic()

conversation_history = []

def chat(user_message: str) -> str:
    conversation_history.append({
        "role": "user",
        "content": user_message
    })

    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        system="Sen yardımcı bir Python programlama asistanısın. Kod örneklerini her zaman açıklamalı ver.",
        messages=conversation_history
    )

    assistant_message = response.content[0].text
    conversation_history.append({
        "role": "assistant",
        "content": assistant_message
    })

    return assistant_message

# Örnek sohbet
print(chat("Python'da decorator nedir?"))
print(chat("Bir örnek göster"))
print(chat("Bu örnekte ne değiştirebilirim?"))

conversation_history her turda büyür: her kullanıcı mesajının ardından asistan yanıtı eklenir. Claude bu listeyi okuyarak bağlamı kuruyor.

Bellek yönetimi: Uzun sohbetlerde token maliyeti artar. Son N mesajı tutup gerisini kırpabilirsiniz:

MAX_HISTORY = 20  # Son 20 mesajı tut

def trim_history(history: list) -> list:
    if len(history) > MAX_HISTORY:
        return history[-MAX_HISTORY:]
    return history

Streaming ile Gerçek Zamanlı Yanıtlar

Normal API çağrısı tüm yanıt hazır olana kadar bekler. Streaming’de yanıt kelime kelime gelir ve kullanıcı beklemez.

import anthropic
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic()

def chat_streaming(user_message: str) -> str:
    full_response = ""

    with client.messages.stream(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": user_message}]
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
            full_response += text

    print()  # Satır sonu
    return full_response

chat_streaming("Python'da asenkron programlamayı açıkla")

stream.text_stream her token için bir parça döndürür. flush=True tamponlamayı devre dışı bırakır; çıktı anında görünür.

Web uygulamalarında Server-Sent Events (SSE) kullanmak en temiz yol. Flask ile basit bir örnek:

from flask import Flask, Response, stream_with_context, request
import anthropic
import json

app = Flask(__name__)
client = anthropic.Anthropic()

@app.route("/chat/stream")
def chat_stream():
    user_message = request.args.get("message", "")

    def generate():
        with client.messages.stream(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": user_message}]
        ) as stream:
            for text in stream.text_stream:
                yield f"data: {json.dumps({'text': text})}

"

    return Response(
        stream_with_context(generate()),
        content_type="text/event-stream"
    )

Model Seçimi: Haiku, Sonnet ve Opus

Üç model var; hız, maliyet ve kapasite açısından farklılar. Doğru modeli seçmek hem performansı hem maliyeti etkiler.

Kaynak: Anthropic resmi fiyatlandırma sayfası — Detaylı model karşılaştırması için API fiyat rehberimize bakabilirsiniz.

Gerçek maliyetinizi görmek için API maliyet hesaplayıcımızı kullanın.

Model seçimi için pratik bir yardımcı:

def get_model_for_task(task_type: str) -> str:
    model_map = {
        "classification": "claude-haiku-4-5",
        "summary": "claude-haiku-4-5",
        "chat": "claude-sonnet-4-5",
        "code": "claude-sonnet-4-5",
        "analysis": "claude-opus-4-5",
        "creative": "claude-opus-4-5"
    }
    return model_map.get(task_type, "claude-sonnet-4-5")

model = get_model_for_task("chat")

API Maliyetini Optimize Etme

Token sayısını düşürmenin birkaç pratik yolu var. Kısa sistem promptları ve prompt caching işe yarayan iki yöntem.

Sistem promptunu kısa tut:

# Fazla uzun — gereksiz token harcar
system_verbose = """
Sen bir yapay zeka asistanısın. Kullanıcılara yardım etmek için buradasın.
Her zaman kibar ve yardımsever olmaya çalış. Soruları dikkatli oku...
"""

# Yeterli
system_concise = "Python uzmanı asistan. Net, kod örnekli yanıtlar ver."

max_tokens değerini göreve göre ayarla:

def create_message(prompt: str, task_type: str = "chat"):
    max_tokens_map = {
        "classification": 50,
        "summary": 300,
        "chat": 1024,
        "code": 2048,
        "analysis": 4096
    }

    return client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=max_tokens_map.get(task_type, 1024),
        messages=[{"role": "user", "content": prompt}]
    )

Aynı sistem promptunu tekrar tekrar gönderiyorsanız, prompt caching maliyeti %90’a kadar kesiyor. Tam mekanizma prompt caching rehberimizde:

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Uzun sistem promptunuz buraya...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_input}]
)

Hata Yönetimi ve Rate Limiting

Üretim ortamında API çağrıları her zaman çalışmaz. Sağlam hata yönetimi chatbotu kararlı tutar.

import anthropic
import time
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic()

def chat_with_retry(
    user_message: str,
    max_retries: int = 3,
    retry_delay: float = 1.0
) -> str | None:

    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model="claude-sonnet-4-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": user_message}]
            )
            return response.content[0].text

        except anthropic.RateLimitError:
            if attempt < max_retries - 1:
                wait_time = retry_delay * (2 ** attempt)  # Exponential backoff
                print(f"Rate limit aşıldı. {wait_time:.1f}s bekleniyor...")
                time.sleep(wait_time)
            else:
                raise

        except anthropic.APITimeoutError:
            print(f"Zaman aşımı (deneme {attempt + 1}/{max_retries})")
            if attempt == max_retries - 1:
                raise

        except anthropic.BadRequestError as e:
            print(f"Geçersiz istek: {e}")
            return None

        except anthropic.AuthenticationError:
            print("API anahtarı geçersiz. .env dosyasını kontrol edin.")
            raise

    return None

Yaygın hata kodları:

Tam Chatbot Örneği: Müşteri Destek Botu

Şimdiye kadar işlediğiniz her şeyi içeren tam bir bot. Streaming, hata yönetimi ve konuşma geçmişi bu örnekte birlikte çalışıyor:

import anthropic
from dotenv import load_dotenv
import time

load_dotenv()

SYSTEM_PROMPT = """Sen bir yazılım şirketinin müşteri destek asistanısın.
Görevlerin:
- Teknik soruları net ve adım adım yanıtlamak
- Kullanıcıyı ürünün dokümantasyonuna yönlendirmek
- Çözülemeyen sorunları insan temsilciye aktarmayı önermek
- Her zaman nazik ve sabırlı olmak

Yanıtlarını kısa tut (maks. 3 paragraf). Gerektiğinde kod örnekleri ekle."""

class CustomerSupportBot:
    def __init__(self):
        self.client = anthropic.Anthropic()
        self.conversation_history = []
        self.model = "claude-sonnet-4-5"

    def chat(self, user_input: str, max_retries: int = 3) -> str:
        self.conversation_history.append({
            "role": "user",
            "content": user_input
        })

        # Geçmişi kırp (son 20 mesaj)
        if len(self.conversation_history) > 20:
            self.conversation_history = self.conversation_history[-20:]

        for attempt in range(max_retries):
            try:
                full_response = ""

                with self.client.messages.stream(
                    model=self.model,
                    max_tokens=1024,
                    system=SYSTEM_PROMPT,
                    messages=self.conversation_history
                ) as stream:
                    for text in stream.text_stream:
                        print(text, end="", flush=True)
                        full_response += text

                print()

                self.conversation_history.append({
                    "role": "assistant",
                    "content": full_response
                })

                return full_response

            except anthropic.RateLimitError:
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    print(f"
Rate limit. {wait_time}s bekleniyor...")
                    time.sleep(wait_time)
                else:
                    return "Şu an çok yoğunuz, lütfen birkaç dakika sonra tekrar deneyin."

            except Exception as e:
                return f"Bir hata oluştu: {str(e)}"

        return "İsteğiniz işlenemedi."

    def reset(self):
        self.conversation_history = []
        print("Sohbet geçmişi temizlendi.")

def main():
    bot = CustomerSupportBot()
    print("Müşteri Destek Botu aktif. Çıkmak için 'quit' yazın.
")

    while True:
        user_input = input("Siz: ").strip()

        if not user_input:
            continue
        if user_input.lower() in ("quit", "exit", "çıkış"):
            print("Görüşmek üzere!")
            break
        if user_input.lower() == "reset":
            bot.reset()
            continue

        print("
Bot: ", end="")
        bot.chat(user_input)
        print()

if __name__ == "__main__":
    main()

Bot üç komut tanıyor: normal metin soru sormak için, reset geçmişi temizlemek için, quit veya çıkış programı kapatmak için.

Sonraki Adımlar

Temel bot hazır. Birkaç yönde ilerliyebilirsiniz.

Araç kullanımı (Tool Use): Claude’a veritabanı sorgusu veya harici API çağrısı yetkisi verin:

tools = [
    {
        "name": "get_order_status",
        "description": "Sipariş durumunu sorgular",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "Sipariş numarası"}
            },
            "required": ["order_id"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "12345 numaralı siparişim nerede?"}]
)

Yapılandırılmış çıktı: Yanıtları JSON formatında almak için yapılandırılmış çıktı tekniklerini inceleyebilirsiniz.

Sistem promptu kaliteyi doğrudan belirler. Prompt mühendisliği rehberimiz bunu derinlemesine ele alıyor.

Claude API ile Python, prototipten üretime ölçekleniyor. Kod örneklerini kendi projenize uyarlayarak başlayın.