Çalışan Bir AI Ajanı İnşa Edin: Pratik Bir Sözlük

Bir AI ajanı, bir hedef alan, bir eylem dizisi belirleyen ve o hedef karşılanana veya vazgeçene kadar araçları kullanarak bu eylemleri yürüten bir programdır. Bu, sadece mesajlara yanıt veren bir sohbet botundan farklıdır. Bir ajan planlama yapar, fonksiyonları çağırır, sonuçları kontrol eder ve ayar yapar. Eğer ChatGPT'yi sadece bir tarayıcı üzerinden kullandıysanız, ilk ajanınızı inşa etmek, modelin bir metin üreticisi olmaktan çıkıp daha geniş bir sistemin bileşeni haline geldiği noktadır.

Temel döngü

Her ajan, nasıl pazarlanırsa pazarlansın, aynı döngünün bir versiyonunu çalıştırır: gözle, düşün, harekete geç, tekrarla. Somut olarak:

1. Ajan bir görev alır ("sonraki ay Lizbon'a en ucuz uçuşu bul ve bir e-posta özeti yaz").
2. Görevi ve mevcut araçların tanımını içeren LLM'yi çağırır.
3. Model ya son bir cevap ya da search_flights(destination="Lisbon", month="2025-06") gibi bir araç çağrısı döndürür.
4. Kodunuz o fonksiyonu yürütür, gerçek bir sonuç alır ve bunu modelin bağlamına geri besler.
5. Model sonra ne yapacağını karar verir: başka bir aracı çağırır, açıklama ister veya bitirir.

Bu desene genellikle ReAct döngüsü (akıl plus harekete geç) denir ve LangChain'in ajan yürütücüleri, LlamaIndex ajanları ve OpenAI'nin function-calling API'si gibi çerçevelerin omurgasıdır. Bunu sadece bir LLM API'si ve bir while döngüsü ile Python'da 100 satırdan az kod ile kendiniz uygulayabilirsiniz — çerçeveler kolaylık ekler, sihir değil.

Araçlar onu bir ajan yapan şeydir

Araçsız bir model sadece konuşabilir. Ona fonksiyonlar verin, harekete geçebilir. Araçlar tipik olarak adını, parametrelerini ve amacını açıklayan bir şema ile sarılmış sade Python fonksiyonlarıdır, böylece model onları ne zaman ve nasıl çağıracağını bilir. Örnek:

def get_weather(city: str) -> str:
    """Return current weather for a given city."""
    resp = requests.get(f"https://api.weather.example/v1/{city}")
    return resp.json()["summary"]

OpenAI'nin function-calling ile, bu fonksiyonun yanında bir JSON şeması iletirsiniz ve model serbest metin yerine {"name": "get_weather", "arguments": {"city": "Lisbon"}} gibi yapılandırılmış bir çağrı çıktısı verir. Kodunuz bunu ayrıştırır, gerçek fonksiyonu çalıştırır ve sonucu konuşmada yeni bir mesaj olarak döndürür. Model cevaplamak için yeterli bilgiye sahip olana kadar tekrarlayın.

Bellek ve durum

Tek bir API çağrısının bağlam penceresi dışında bellekleri yoktur. Ajanlar açık duruma ihtiyaç duyar: mesajların çalışan listesi (konuşma geçmişi) ve sıklıkla daha uzun vadeli gerçekler için ayrı bir depo. Kısa görevler için, konuşmayı temsil eden sözlüklerin bir Python listesi yeterlidir. Oturumlar arasında şeyleri hatırlaması gereken ajanlar için, gömülümleri aracılığıyla ilgili geçmiş bilgileri depolamak ve almak için bir vektör veritabanı (Chroma, Pinecone, Qdrant) kullanırsınız.

Bu noktada aşırı mühendislik yapmayın. Şaşırtıcı şekilde çok sayıda "ajan" projesi LLM zayıf olduğundan değil, durum yönetimi dağınık olduğundan başarısız olur: yinelenen mesajlar, sınırlandırılmamış bağlam büyümesi veya hangi araç çağrısının hangi sonuca ait olduğunu kaybetmek.

Minimal çalışan örnek

OpenAI'nin API'sini kullanan, hiçbir çerçevesi olmayan yalın bir ajanın şekli:

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=[weather_tool_schema],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            result = get_weather(**json.loads(call.function.arguments))
            messages.append(msg)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    else:
        print(msg.content)
        break

Bu gerçek, işleyen bir ajandır. Başka her şey — planlama stratejileri, çok ajanlar koordinasyonu, alım işlem hatları — bu döngü üzerine inşa edilir.

Nerede kırılır

Ajanlar tahmin edilebilir şekillerde başarısız olur: model başarı olduğunu söyleyemediğinde sonsuz araç çağrısı döngüleri, varsayılan fonksiyon argümanları ve pahalı araçları yeniden çağırmaktan kaynaklanan kaçan maliyetler. Döngülere karşı hard bir yineleme sınırı (diyelim, 10 adım) ile ve geliştirme sırasında her araç çağrısını günlükle koruma altına alın. Gerçek bir sisteme dokunan herhangi bir şeyi yürütmeden önce argümanları doğrulayın — e-posta gönderebilen veya kabuk komutlarını çalıştırabilen bir ajan, bu girdileri üreten LLM etkili bir şekilde güvenilmeyen bir kullanıcı olduğu için kullanıcıya açık kodlara uygulayacağınız aynı giriş sanitizasyonuna ihtiyaç duyar.

Sonra nereye

Döngü çalıştığında, ilginç sorunlar başlar: tek ajan ve çok ajanlar tasarımları arasında seçim yapmak, ne kadar özerklik vereceğine karar vermek ve çıktısı deterministik olmadığında ajanları güvenilir şekilde test etmek. Buradan daha derinlemesine inşa etmeye devam etmek istiyorsanız Korra Studio'nun AI ve Python izleri alım-artırılmış oluşturma, komut tasarımı ve araç çağrısı desenleri konusunu kapsar.