Uygulamanıza yapay zeka ajanı nasıl eklenir: mimari ve maliyet

Codixus Ekibi1 Temmuz 2026

Tek bir soruyu cevaplamaktan fazlasını yapan bir yapay zeka özelliği istiyorsunuz. Kullanıcının verisini okusun, API'nizi çağırsın, bir işlem yapsın ve sonucu döndürsün. İşte buna ajan diyoruz. Yayındaki bir mobil uygulamaya ajan eklemek, bir chatbot bağlamaktan farklı bir iş. Bu yazı bir kurulum ve maliyet rehberi: yayına alacağınız mimari, onun altında çalışan döngü ve işe girişmeden önce aylık faturayı gerçekçi bir rakamla tahmin etmenin yolu.

Bu yazının ne olmadığını da söyleyelim. Ajanların neden önemli olduğunu anlatan bir motivasyon yazısı değil, prompt tasarımı üzerine bir ders de değil; ikisini zaten yazdık. Son denemeniz yarıda kaldıysa önce yapay zeka ajanı projeniz neden başarısız oldu yazısını okuyun. Modele tam olarak ne vereceğinizle uğraşıyorsanız context engineering ve prompt engineering yazısı o konuyu anlatıyor. Bu yazıda kurulumun kendisine odaklanıyoruz.

Uygulama içi ajan aslında nedir?

Pazarlama söylemini bir kenara bırakırsanız ajan basit bir fikir: araçları döngü içinde kullanan bir dil modeli. Ajanları canlı ortamda yayınlayan Anthropic ekibi bunları sade bir dille "LLM'lerin kendi süreçlerini ve araç kullanımını dinamik olarak yönlendirdiği sistemler" diye tanımlıyor; ayrıca "ortamdan gelen geri bildirime göre döngü içinde araç kullanan LLM'lerden ibaret" olduklarını söylüyor.

Bunu düz bir chat completion çağrısıyla karşılaştırın: metin girer, metin çıkar, tek tur, iş biter. Ajanda ise model daha fazla bilgiye ihtiyacı olduğuna karar verip kodunuzdan bir fonksiyon çalıştırmasını isteyebilir, sonucu okuyup yeniden karar verebilir. İşin sırrı bu karar verip harekete geçme döngüsünde; göreve göre istek başına iki ila on kez döner. Her tur, parasını ödediğiniz tam bir model çağrısıdır.

Anthropic ekibi şunu da net söylüyor: "çok adımlı ajan sistemlerini yalnızca daha basit çözümler yetmediğinde ekleyin." Doğru bağlamla yapılan tek bir model çağrısı soruyu cevaplıyorsa onu yayına alın. Döngüye ancak görev, modelin başta elinde olmayan bilgiyi toplamasını gerçekten gerektiriyorsa başvurun.

Referans mimari

İşe yarayan ve bizim de üzerine kurduğumuz yapı şu: telefon sizin sunucu tarafınızla (backend) konuşur, modelle ve araçlarla yalnızca backend'iniz konuşur. İstemci, yani Expo uygulamanız, kullanıcının mesajını ve bağlamı size ait bir endpoint'e gönderir. Backend'iniz (bizim teknoloji yığınımızda bir Bun servisi) system prompt'u tutar, araçları tanımlar, döngüyü çalıştırır, her araç çağrısını yürütür ve cevabı akış halinde geri gönderir. Model sağlayıcısı (Claude ya da OpenAI) akıl yürütme katmanıdır. Supabase ise uygulama durumunu (state), kimlik doğrulamayı ve araçlarınızın okuyup yazdığı verileri tutar.

API anahtarı neden asla uygulamanın içinde olmamalı

Model API anahtarınızı mobil uygulama paketinin (binary) içine koyarsanız anahtarı herkese dağıtmış olursunuz: yayındaki bir uygulamanın içindeki metinleri herkes çıkarabilir, sızan bir anahtar da bir yabancının faturanızı şişirmesi demektir. Anahtarın yeri sunucudur, nokta. Uygulama kullanıcının kimliğini backend'inizde doğrular, backend de modele kendi kimliğiyle bağlanır. Bu düzen size tek bir kontrol noktası da kazandırır: istek sınırı (rate limit) koyabilir, kullanımı kullanıcı bazında kaydedebilir ve uygulama güncellemesi çıkarmadan model değiştirebilirsiniz.

Orkestrasyon katmanı

Döngüyü backend yönetir: konuşmayı ve araç tanımlarını modele gönderir, bir araç isteği alır, eşleşen fonksiyonu veritabanınızda ya da üçüncü taraf bir API üzerinde çalıştırır, sonucu modele geri verir ve model nihai cevabı döndürene kadar bunu tekrarlar. Her şey sunucuda olduğu için bir aracı değiştirmek, bir koruma kuralını sıkılaştırmak ya da daha ucuz bir modele geçmek aynı gün içinde mümkün; araya App Store incelemesi girmez.

Kod yazmadan önce ajan mimarinize bir de dışarıdan bakılsın mı istiyorsunuz? 30 dakikalık görüşme planlayın; döngüyü, araçları ve maliyeti sizinle birlikte netleştirelim.

Araç çağırma (tool calling): döngü kodda nasıl çalışır

Araçlar ajanın elleridir. Modele bir fonksiyonu üç parçayla tanıtırsınız: bir ad, sade dilde bir açıklama ve girdileri için bir JSON şeması. Hangisinin uygun olduğuna model karar verir. OpenAI akışı beş adımda anlatıyor: modelin çağırabileceği araçlarla birlikte isteği gönderin, bir araç çağrısı alın, kodu kendi tarafınızda çalıştırın, araç çıktısıyla ikinci bir istek gönderin ve nihai cevabı ya da yeni bir araç çağrısını alın.

Claude'un araç kullanımı da aynı şekilde çalışır. Model, durma nedeni olarak tool_use ve bir ya da birkaç tool_use bloğu döndürür; dokümanlara göre "kodunuz işlemi yürütür ve bir tool_result geri gönderir", model de buna bakarak devam eder. Terimler sağlayıcıya göre değişse de mekanizma aynı. Araç açıklamalarını net yazın, çünkü model karar verirken açıklamayı okur. Belirsiz bir açıklama, ajanın yanlış aracı çağırmasının ya da hiçbirini çağırmamasının en yaygın nedenidir.

Yavaş hissettirmemek için akış (streaming)

Düşünen, iki araç çağıran ve bir paragraf yazan bir ajanın işi birkaç saniye sürer. Ekran bu sürenin tamamında boş kalırsa kullanıcılar uygulamanın bozulduğunu düşünür. Bunun yerine cevabı akış halinde gönderin: model token ürettikçe bunları uygulamaya iletin, araçlar çalışırken ara adımları gösterin. Toplam süre aynı kalır, ama algılanan bekleme çok daha kısa olur. İstemci tarafında bu, Expo uygulamanızın parça parça okuduğu akışlı bir HTTP cevabı demek; backend tarafında ise modelin akışını olduğu gibi aktarmak ve araç çağrılarının arasına kendi durum olaylarınızı eklemek.

Koruma kuralları ve eval

İşlem yapabilen bir ajanın sınırlara ihtiyacı vardır. Burada iki alan öne çıkıyor.

Birincisi, araç çıktısını güvenilmez sayın. Anthropic dokümanları lafı dolandırmıyor: araç sonuçları "çoğu zaman kontrolünüz dışındaki kaynaklardan içerik taşır: web sayfaları, gelen e-postalar, kullanıcı yüklemeleri, üçüncü taraf API'ler". Bu içeriği kontrol eden bir saldırgan modeli ele geçirmeye çalışan talimatlar gömebilir; bu tekniğe dolaylı prompt injection denir. Bu içeriği tool_result blokları içinde tutun, asla system prompt'a koymayın. Ayrıca karttan ödeme almak ya da veri silmek gibi geri alınamaz bir işlemi, kullanıcının gördüğü bir onay olmadan hiçbir aracın yapmasına izin vermeyin.

İkincisi, ölçeklemeden önce bir eval seti (değerlendirme seti) kurun. Yirmi ila elli gerçek istek toplayın, her biri için doğru sonucu yazın ve prompt'u, bir aracı ya da modeli her değiştirdiğinizde bunları yeniden çalıştırın. Bu set olmadan, bir değişikliğin işe yarayıp yaramadığını ya da sessizce bir şeyi bozup bozmadığını ancak tahmin edebilirsiniz. Yukarıda bağlantısını verdiğimiz iki yazı tam burada işinize yarar: gördüğümüz hataların çoğu model hatası değil, bağlam ve kapsam hatası; eval seti bunları erken yakalar.

Maliyeti belirleyen gerçek etkenler

Model API'leri token başına faturalandırır: girdi (system prompt'tan ve araç tanımlarından geçmişe ve her araç sonucuna kadar gönderdiğiniz her şey) ve çıktı (modelin yazdığı her şey). Faturanızı dört şey belirler.

Model seçimi. En büyük kaldıraç bu. Sağlayıcı fiyatları kademelidir: aynı token miktarı için küçük ve hızlı bir modelin ücreti, üst seviye bir modelinkinin küçük bir kısmı kadar olabilir. Anthropic'in yayımladığı fiyatlarda hafif Haiku kademesi, en üst Opus kademesinin çok altında fiyatlanıyor ve aynı tablo diğer sağlayıcılarda da geçerli. Ucuz modeli yönlendirme ve basit adımlar için kullanın, pahalı olanı ise ona ihtiyaç duyan akıl yürütme adımlarına saklayın.
Token hacmi. Ajan döngüsü büyüyen konuşmayı her turda yeniden gönderir; beş adımlı bir görev system prompt'unuzu ve geçmişi beş kez gönderebilir. Bağlamı kısaltın, eski turları özetleyin ve tüm veritabanınızı prompt'a doldurmayın.
Önbellekleme (caching). System prompt'unuz ve araç tanımlarınız değişmiyorsa prompt caching sayesinde sağlayıcı bunları her çağrıda baştan işlemek yerine önbellekten kullanır. Anthropic önbellekten okumayı temel girdi fiyatının 0,1 katı olarak fiyatlıyor; bu, yeni bir okumanın kabaca onda biri demek. Diğer sağlayıcılar da önbellekteki girdiye benzer şekilde indirim uyguluyor. Büyük ve sabit bir system prompt'u olan bir ajan için bu hissedilir bir tasarruftur.
Yeniden denemeler. Yeniden denediğiniz her başarısız çağrı ve modelin toparlamak zorunda kaldığı her araç hatası daha fazla token demek. Her şeyin yolunda gittiği senaryoya göre yaptığınız tahminin 1,2 ila 1,5 katını hesaba katmak gerçekçi olur.

Aylık maliyeti kabaca hesaplamak

Faturanın büyüklüğünü kestirmek için tabloya gerek yok. Önce, döngünün bütün turlarını sayarak tek bir tam isteğin harcadığı token'ı (girdi artı çıktı) tahmin edin. Bunu modelinizin girdi ve çıktı fiyatlarıyla, sonra kullanıcı başına aylık istek sayısıyla, sonra aktif kullanıcı sayısıyla çarpın. Üstüne yeniden deneme çarpanını ekleyin, önbelleğin prompt'unuzun sabit kısmında sağladığı tasarrufu da toplamdan çıkarın.

Somut bir örnek: bir görev üç tur çalışıyorsa ve her tur ortalama birkaç bin girdi token'ı ile birkaç yüz çıktı token'ı harcıyorsa, tamamlanan tek bir istek kabaca on binin üzerinde token harcar. Orta kademe bir modelin fiyatıyla bu, istek başına bir sentin altında kalır; üst seviye bir modelde bunun birkaç katı tutar. Burada tek bir rakamdan çok formül önemli, çünkü yayımlanan fiyatlar sık değişiyor. Maliyeti bugünkü fiyatlarla hesaplayın ve sistemi basit adımlarda daha ucuz bir modele geçebilecek şekilde tasarlayın.

Sık sorulan sorular

Yapay zeka ajanı ile chatbot arasındaki fark nedir?

Chatbot tek turda cevap verir: metin girer, metin çıkar. Ajan ise bir döngü çalıştırır; cevap vermeden önce ne zaman araç çağıracağına, sonuçları okuyacağına ve harekete geçeceğine karar verir. Veri arayabilir, API'nize istek atabilir, kullanıcı adına işlem yapabilir; chatbot ise yalnızca konuşur. Başarısız olan ajan özelliklerinin çoğu aslında ya tek bir araç çağrısına ihtiyacı olan chatbot'lardır ya da basit kalması gerekirken ajan kılığına sokulmuş chatbot'lar.

Model API anahtarını mobil uygulamamın içine koymalı mıyım?

Hayır. Yayınlanmış bir uygulama paketindeki anahtar çıkarılabilir ve faturanızı şişirmek için kullanılabilir. Her model çağrısını kontrolünüzdeki bir backend üzerinden geçirin, kullanıcının kimliğini o backend'de doğrulayın ve anahtarı sunucuda tutun. Kullanıcı başına istek sınırı koymanın ve kullanımı kaydetmenin düzgünce yapılabildiği tek yer de burası.

Claude mu OpenAI mı: hangi modeli kullanmalıyım?

İkisi de aynı araç çağırma döngüsünü destekler; birine göre geliştirip sonra diğerine geçebilirsiniz. Asıl soru, her adımda hangi model kademesini kullanacağınız. Yönlendirme ve basit veri çıkarma için küçük, ucuz bir model; yalnızca zor akıl yürütme için daha güçlü bir model kullanın. Canlı ortamdaki birçok ajan, kaliteyi yüksek, maliyeti düşük tutmak için tek bir istekte farklı sağlayıcıları ve kademeleri bir arada kullanır.

Bir ajan kurmak ne kadar sürer?

Birkaç araç, akışlı cevap (streaming) ve koruma kurallarıyla donatılmış, tek işe odaklı bir uygulama içi ajan, modern bir teknoloji yığınıyla aylar değil haftalar içinde hazır olur. Zaman, model çağrısının kendisine değil; araç tasarımına, eval setine ve koruma kurallarına harcanır. Kapsamı tek ve net bir işle sınırlayın, yayına alın, işe yaradığını ölçebildiğinizde genişletin.

İlk seferde doğru kurun

Uygulama içi ajan beş parçadan oluşur: bir modeli döngü içinde çalıştıran bir backend, iyi tanımlanmış birkaç araç, akışlı cevap, koruma kuralları ve ölçeklemeden önce anladığınız bir maliyet modeli. Bu beşini doğru kurarsanız gerisi adım adım iyileştirmedir. Yapay zeka mobil uygulama geliştirme hizmetinde yaptığımız iş tam olarak bu; kendi uygulamalarımızı yayınladığımız teknoloji yığınının aynısıyla çalışıyoruz.

Kaynaklar

Bunu sizin için kurmamızı ister misiniz? 30 dakikalık görüşme planlayın.