AI Ajan Oluşturucu

Bu sayfa, DevUtilities AI Ajan Oluşturucu ile LLM ajanları oluşturmak için kanonik kılavuzdur. Okurken yukarıdaki rehberli iş akışını kullanın veya aşağıdaki bir konuya atlayın. Schemas, MCP JSON, istemler ve token sayımları tarayıcınızda kalır — çıkarım için hiçbir şey yüklenmez.

AI Ajan Oluşturucu, üretime hazır ajan yapılandırmalarını birleştirmek için istemci tarafı bir atölyedir: OpenAI function calling için JSON Schema araçları, Cursor ve Claude Desktop için mcpServers doğrulama, system prompts, birleşik token bütçeleri ve ekip devri için dışa aktarılabilir çıktılar.

Ne elde edersiniz

• Dört iş akışı modu: tam ajan, yalnızca function calling, MCP kurulumu, yapılandırılmış yanıt
• Başlangıç şablonları: Filesystem MCP, OpenAI function calling, yapılandırılmış sınıflandırıcı
• Örnek-JSON → JSON Schema çıkarımı, isteğe bağlı katı additionalProperties: false
• JSON-pointer hataları ve uyarılarıyla yerel MCP lint
• İstem, minify edilmiş tools ve MCP JSON üzerinde birleşik token bütçesi
• Dışa aktarmalar: OpenAI tools JSON, response_format, MCP yapılandırması, markdown özeti, tam paket

Bu oluşturucuyu şu durumlarda kullanın

• OpenAI tools JSON'a ihtiyacınız var ve JSON Schema'yı elle yazmak istemiyorsunuz
• Cursor veya Claude Desktop MCP sunucularını bağlayıp yapıştırmadan önce lint istiyorsunuz
• Bir ajanın prompt + tools'unun hâlâ bir bağlam penceresine sığdığını kanıtlamanız gerekir
• schema → MCP → prompt → export zincirleyen kalıcı bir oturum istiyorsunuz

Bağımsız aracı şu durumlarda tercih edin

• Yalnızca derin encoding karşılaştırması veya maliyet hesabı → LLM Token Counter
• İstem olmadan yalnızca tek seferlik MCP lint → MCP Validator
• Yalnızca örnekten şema çıkarımı → Structured Output Generator

Araçları tanımlamadan önce bir mod seçin. Modlar alakasız adımları gizler; boş panellerle savaşmazsınız.

Tam ajan için ilk kez yürüyüş. Şablon kısayolları bu adımların birkaçını atlar.

1. Tam ajanı seçin (veya OpenAI function calling şablonunu yükleyin).
2. Araçları tanımla'da her araca net bir ad, açıklama ve temsili örnek JSON argümanları ekleyin.
3. Çıkarılan JSON Schema'yı gözden geçirin — OpenAI structured outputs / strict tool calling için katı modu açın.
4. Ajan Cursor veya Claude Desktop içinde çalışacaksa mcpServers JSON'unu yapıştırın veya düzenleyin; devam etmeden önce her hatayı düzeltin.
5. Modele hangi aracı ne zaman çağıracağını ve asla uydurmaması gerekenleri söyleyen system instructions yazın.
6. Token bütçesini açın, cl100k_base veya o200k_base seçin ve birleşik toplamın modelinize sığdığını doğrulayın.
7. API için OpenAI tools JSON, masaüstü istemci için MCP yapılandırması ve ekip için markdown özeti dışa aktarın.
8. İsteğe bağlı olarak tam paket JSON'unu dışa aktarın; başka bir mühendis aynı oturum durumunu sonra yeniden yükleyebilsin.

Sorun: OpenAI function calling ile hava durumu ve sipariş bakabilen bir müşteri destek ajanına ihtiyacınız var, ancak elle yazılmış JSON Schema katı doğrulamada başarısız olmaya devam ediyor.

Bu araç sorunu nasıl çözer

1. Function calling modunu seçin veya OpenAI function calling şablonunu (hava + sipariş arama) yükleyin.
2. Üretimde ihtiyaç duyduğunuz her alanın en az bir kez göründüğü şekilde örnek JSON'u düzenleyin — eksik anahtarlar required özellik olmaz.
3. Her nesnenin additionalProperties: false üretmesi için katı modu açın.
4. System prompt'u sıkılaştırın: sipariş kimliklerini doğrulayın, araç sonuçlarını asla uydurmayın, yanıtları kısa tutun.
5. GPT-4o'da dağıtıyorsanız o200k_base altında token bütçesini kontrol edin.
6. OpenAI tools JSON'unu dışa aktarıp Chat Completions veya Responses API istemcinize yapıştırın.

Sonuç: katı, API'ye hazır bir tools dizisi ve şemalarla eşleşen bir istem — ayrı bir şema düzenleyicisi olmadan.

Sorun: Cursor veya Claude Desktop mcp.json'unuzu reddediyor ya da filesystem sunucusu yanlış dizinle başlayıp diskin fazlaını görebiliyor.

Bu araç sorunu nasıl çözer

1. MCP kurulumu modunu seçin veya Filesystem MCP şablonunu yükleyin.
2. /path/to/allowed/dir yolunu ajanın dokunabileceği tek dizinin mutlak yoluyla değiştirin.
3. Doğrulamayı çalıştırın — eksik command/args, geçersiz URL'ler ve string olmayan env değerlerini düzeltin.
4. Tarayıcıda lint yaparken yer tutucu env değerleri kullanın (üretim gizlileri değil).
5. Doğrulanmış mcpServers JSON'unu Cursor veya Claude Desktop yapılandırmanıza dışa aktarın.
6. Yıkıcı dosya işlemlerinden önce onay isteyen system instructions ekleyin.

Sonuç: lint edilmiş bir MCP istemci yapılandırması ve masaüstü uygulamasını yeniden başlatmadan önce sunucu yetenekleriyle eşleşen bir istem.

Sorun: modelin duygu, güven, konular ve kısa bir özeti JSON olarak döndürmesi gerekir — serbest biçimli yanıtlar aşağı akış ayrıştırıcınızı bozar.

Bu araç sorunu nasıl çözer

1. Yapılandırılmış yanıt modunu seçin veya yapılandırılmış sınıflandırıcı şablonunu yükleyin.
2. Örnek JSON'u boru hattınızın beklediği tam şekle uyacak şekilde düzenleyin.
3. Bildirilmemiş anahtarların doğrulamada reddedilmesi için katı modu açın.
4. JSON nesnesi dışında düzyazıyı yasaklayan bir system prompt yazın.
5. OpenAI structured outputs için response_format json_schema dışa aktarın.
6. Token bütçesinin sınıflandıracağınız girdi belgesi için hâlâ yer bıraktığını doğrulayın.

Sonuç: eşleşen talimatlarla structured-output API'lerine bırakabileceğiniz tek bir çıktı şeması.

Sorun: üç araç ve uzun bir MCP yapılandırması ekledikten sonra, sohbet geçmişi dahil edildiğinde ajanın birleşik istemi GPT-4o'nun pratik bütçesine sığmıyor.

Bu araç sorunu nasıl çözer

1. Token bütçesi adımını açın ve prompt + minify edilmiş tools + MCP JSON birleşik toplamını not edin.
2. Araç açıklamalarını kısaltın ve required şemaları şişiren kullanılmayan örnek alanları kaldırın.
3. Her zaman açık system prompt'taki ayrıntılı politika metnini isteğe bağlı getirmeye taşıyın.
4. Yalnızca daha derin encoding matematiği gerekiyorsa, birleştirilmiş yükü LLM Token Counter'a kopyalayın.
5. Bütçe geçmiş ve completions için rahat pay gösterdikten sonra yeniden dışa aktarın.

Sonuç: taşmayı üretimdeki ilk 400 hatasından sonra değil, oluşturucuda yakalarsınız.

Örnek JSON katı JSON olmalıdır. Yalnızca örnekte bulunan anahtarlar required özellik olur. İç içe nesneler ve diziler örnek değerlerden tür çıkarır.

Pratik kurallar

• Modelin göndermesine izin verilmesi gereken her alanı ekleyin — atlamak “required değil” demektir, “default'lu isteğe bağlı” değil.
• Gerçekçi enum'ları string örnek olarak kullanın; açık bir enum dizisi gerekiyorsa şemayı elle düzenleyin.
• Her nesnede additionalProperties: false üretmek için katı modu açın — OpenAI structured outputs ve strict tool calling için önerilir.
• Boş diziler zayıf öğe türleri çıkarır — en az bir temsili öğe ekleyin.

Stdio sunucuları command ve genellikle args gerektirir. Uzak sunucular geçerli bir http veya https url gerektirir. Env değerleri string olmalıdır. Hatalar dışa aktarma güvenini engeller; uyarılar manuel bir geçişi hak eder.

Yaygın istemci zarfları

• Üst düzey anahtar Cursor ve Claude Desktop kurallarına göre "mcpServers" olmalıdır
• Filesystem sunucuları mutlak allow-list yolları kullanmalıdır
• Tarayıcıda düzenlerken env yer tutucularını tercih edin; gerçek gizlileri yalnızca yerel makinede enjekte edin

Token sayımları system prompt, minify edilmiş araç şemaları ve MCP JSON'u birleştirir. GPT-4 / Claude yaklaşımı için cl100k_base veya GPT-4o için o200k_base seçin. Sayımlar yerel tiktoken tablolarını kullanır — API çağrısı yok.

• Sayıyı taban kabul edin: sohbet geçmişi ve araç sonuçları çalışma zamanında daha fazla ekler
• Her şema veya istem düzenlemesinden sonra yeniden kontrol edin
• Özel bir yükte sınır haritaları veya aylık maliyet kartları gerektiğinde LLM Token Counter kullanın

Belirtiler: OpenAI tools yükünü reddeder veya model uygulamanızın gerçekten ihtiyaç duyduğu argümanları geçiremez.

Neden olur

Katı şemalar bildirilmemiş anahtarları reddeder. Örnek JSON bir alanı atladıysa özellik olmaz. Katı mod kapalıysa OpenAI structured-output sınırları açık nesneleri yine reddedebilir.

Teşhis

Çıkarılan şema properties'ini uygulamanızın gönderdiği argümanlarla karşılaştırın. OpenAI structured outputs hedeflerken katı modun açık olduğunu kontrol edin.

Düzeltmeler

1. Eksik anahtarları örnek JSON'a ekleyip şemayı yeniden oluşturun.
2. İç içe nesnelerde additionalProperties: false tutarlı olsun diye katı modu açın.
3. OpenAI'nin structured output sınırlarına göre desteklenmeyen yapıları (derin iç içe oneOf, egzotik türler) kısaltın.
4. Tools JSON'unu yeniden dışa aktarıp bilinen geçerli bir argüman yüküyle yeniden test edin.

Belirtiler: command/url üzerinde doğrulama hataları, istemci sunucuyu başlatamaz veya uzak taşıma hiç bağlanmaz.

Neden olur

Command'sız stdio, http(s) URL'siz uzak girdiler, sayısal env değerleri veya yanlış üst düzey anahtarlar istemci ayrıştırıcılarını bozar.

Teşhis

Her lint hatasının JSON pointer'ını okuyun. Zarftın mcpServers kullandığını ve her sunucunun ya stdio (command) ya da uzak (url) olduğunu, bozuk bir hibrit olmadığını doğrulayın.

Düzeltmeler

1. Stdio sunucuları için command ve args ekleyin; tüm env değerlerini string olarak tırnaklayın.
2. Uzak MCP taşımaları için http:// veya https:// URL kullanın.
3. Üst düzey anahtar adını mcpServers olarak düzeltin.
4. Hatalar bitene kadar yeniden doğrulayın; göndermeden önce uyarıları önceliklendirin.

Belirtiler: API anahtarları dışa aktarılan JSON'da, git farklarında veya oluşturucu ekran görüntülerinde görünür.

Neden olur

MCP env blokları düz JSON'dur. Üretim gizlilerini — yerel bile olsa — bir tarayıcı aracına yapıştırmak panoya, ekran paylaşımına ve yanlışlıkla commit'lere bağlı sızıntı riskini artırır.

Teşhis

Dışa aktarmalarda ve MCP panelinde sk-, Bearer veya satıcı anahtar kalıplarını arayın. Commit edilen yapılandırmaların yalnızca yer tutucu içerdiğini kontrol edin.

Düzeltmeler

1. Oluşturucuda gizlileri ${ENV_VAR} tarzı yer tutucularla değiştirin.
2. Gerçek değerleri yalnızca yerel masaüstü istemcide veya dağıtım gizli deposunda enjekte edin.
3. Sohbete, biletlerine veya paylaşılan ekranlara yapıştırılan her anahtarı döndürün.
4. mcp.json ve ajan paket dosyaları için pre-commit gizli taraması ekleyin.

Bu çalışma alanı yapılandırmanızı yüklemez — ancak pano ve git yine de sızdırabilir.

• MCP env bloklarında asla API anahtarı commit etmeyin — ortam değişkeni yer tutucuları kullanın
• Filesystem MCP sunucuları için mutlak, en az ayrıcalıklı yollar kullanın
• Üretim istemlerine büyük few-shot örnekleri eklemeden önce token bütçesini gözden geçirin
• Araçların beklenmeyen anahtarları kabul etmemesi için katı şemaları tercih edin
• İç araç adları veya altyapı ana bilgisayarları içeriyorsa dışa aktarılan paketleri hassas sayın

• Bir şablondan başlayıp ihtiyacınız olmayan araçları silin — daha küçük şemalar daha ucuz ve güvenlidir
• Araçları system-prompt talimatlarıyla eşleşen net fiillerle adlandırın (lookup_order, get_weather)
• Tek bir doğruluk kaynağı tutun: ayrışan şema kopyaları yerine bu oluşturucudan dışa aktarın
• Her yol veya command değişikliğinden sonra MCP'yi yeniden doğrulayın
• Markdown dışa aktarmada token bütçesini belgelendirin; gözden geçirenler PR'larda maliyet etkisini görsün
• Derin encoding farkları için LLM Token Counter; birleştirilmiş ajan için bu oluşturucuyu kullanın