# Devoplus yapay zekasıyla çalışma: iki yön Bir Devoplus One uygulaması Devoplus yapay zekasıyla **iki yönde** çalışır: 1. **Uygulamadan yapay zekaya:** uygulama metni özetletir, sınıflandırır, metinden alan çıkarır ya da metin ürettirir (SDK `completeAi`). 2. **Yapay zekadan uygulamaya:** kullanıcı Devoplus'ta bir soru sorduğunda Devoplus yapay zekası uygulamanın verisine ve işlemlerine, uygulamanın beyan ettiği **araçlarla** ve kullanıcının kendi yetkisiyle ulaşır. İkinci yön **zorunlu bir geliştirme adımıdır**: veri ya da işlem sunan her uygulama araçlarını beyan eder ve `AGENT_GUIDE.md` yazar. Yayın kapısı araç beyan eden uygulamada rehberi arar ve eksikse yayını durdurur; araç beyanı olmayan uygulama için "Devoplus yapay zekası bu uygulamaya erişemez" uyarısı verir. ## Teknik olmayan kullanıcıyla - Kullanıcıya araç adı, şema, JSON ya da "yetki alanı" **sorulmaz**. Hangi soruların bu uygulamaya ait olduğunu keşif görüşmesindeki iş listesinden **siz** çıkarırsınız: "Kullanıcı Devoplus'a bu uygulama hakkında ne sorar?" Her cevap bir araç adayıdır. - Kullanıcıya iş diliyle doğrulatın: "Devoplus asistanına 'bekleyen izin taleplerimi göster' dediğinizde bu uygulamadan yanıt gelsin mi? Asistan talep **oluşturabilsin** mi, yoksa yalnız göstersin mi?" Değiştiren işlemler için cevap hayırsa araç yazılmaz. ## Araç tasarlama Her araç üç yerde birlikte durur: | Yer | Ne yazılır | |---|---| | `one.manifest.json` içinde `agent.tools[]` | `name`, TR/EN `title` + `description`, `readOnly`, gerekiyorsa `permission`, `input` şeması | | `src/agent.ts` | `defineAgentTools({ '': { handler: async ({ input, ctx, env }) => { ... } } })` | | `AGENT_GUIDE.md` | aracın ne zaman, hangi girdiyle kullanılacağı, ne döndürdüğü, örnek istek | Kurallar: - **Önce salt okunur araçlar:** listeleme, arama, tek kaydı getirme, özet. Bir şeyi değiştiren araç `readOnly: false` beyan edilir; Devoplus yapay zekası her çağrıdan önce kullanıcıya onay sorar ve bu araçlar Vekalet / Yerine Görüntüle oturumunda çalışmaz. Silme gibi geri alınamaz işler araç yapılmaz. - **Tek iş, açık ad:** `list-requests`, `get-request`, `approve-request`. Ad küçük harf/rakam/`-`, 2-40 karakter; en çok 20 araç. - **`description` modelin seçim ölçütüdür:** ne yapar, ne döndürür, NE ZAMAN KULLANILMAZ. "Talepleri getirir" yetmez; "Kullanıcının kendi izin taleplerini, en yenisi önce döndürür; başka kişinin talebi için kullanılmaz" yazın. - **Girdi küçük ve sınırlı:** `input` bir JSON şemasıdır ama yalnız şu anahtarlar kullanılabilir: `type`, `properties`, `required`, `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, `items` ve `description`. Kök her zaman `"type": "object"`; her düğümde `type` yazılır; dizide `items` zorunludur. Şemada olmayan alan çalışma anında **reddedilir**. Sayfa boyu gibi değerlere `maximum` koyun. - **Yetki ekranla aynıdır:** işleyici kullanıcının kendi kimliğiyle çalışır (`ctx.user.sub`); ekrandaki süzgeç (ör. yalnız kendi kayıtları) aynen uygulanır. Rol gereken araç `permission` alanına uygulamanın kendi izin kodunu (`permission.code` ya da `permissions[]`'tan biri) yazar. Yönetici baypası `ctx.admin`'dir: aracı çağıran kişi kurulumun portalının şirket yöneticisiyse `true`, `hasPermission` her kodda `true` döner. Vekalet / Yerine Görüntüle oturumunda `ctx.actor` doludur (değiştiren araç o oturumda zaten çağrılamaz). - **Devoplus servisleri kişi adına çağrılır:** işleyici yapay zeka, DEXA okuma, kişiler gibi servisleri aracı çağıran kişinin yetkisiyle kullanabilir. ⛔ **Süreli onay gerektiren scope'lar ajan aracında kullanılamaz:** e-posta (`mail.execute`), SMS (`sms.execute`), mobil bildirim (`push.execute`) ve DEXA'ya yazma (`dexa.write`). Kişi bu çağrıda onay ekranını göremez; bu işleri uygulamanın ekranına bırakın ve rehbere yazın. - **DEXA bağlam kodları:** araçta DEXA okuma sorgusunun `UserCode`, `CompanyCode` ve `CostCenterCode` değerleri gönderilmezse aracı çağıran kişiden çözülür. Uygulamanın kendisi göndermesi kurulumda yöneticinin **"kodları uygulama belirler"** onayını ister; gönderilen kod portala karşı doğrulanır, boş değer ERP'ye gitmez. `LangCode` gönderilmez. - **Yanıt sade JSON'dur:** yapay zekanın cevaplaması için gereken alanlar; kimlik numarası, telefon gibi işin gerektirmediği kişisel veri döndürülmez. - Araç çağrısı yalnız platformun imzalı yolundan gelir (`/__one/agent/`); tarayıcıdan çağrılamaz. Bu yolu ekranda kullanmayın. ## `AGENT_GUIDE.md` yazma (ZORUNLU) Rehber, Devoplus yapay zekasının bu uygulama hakkında bildiği tek şeydir. Dört başlık zorunludur: ```markdown # : Devoplus yapay zekası için rehber ## Uygulama ne yapar Hangi iş sorularının bu uygulamaya ait olduğu, hangilerinin OLMADIĞI. ## Veri Kayıt türleri, önemli alanlar, kimin neyi görebildiği. ## Araçlar Her araç için: ne zaman, girdi, çıktı (örnek JSON), izin, değiştiriyor mu. ## Örnek istekler "Kullanıcının cümlesi", hangi araç (girdi) ve nasıl yanıtlanır. ``` - Her aracın adı rehberde geçmelidir (yayın kapısı arar). Araç eklendiğinde, değiştiğinde ya da kaldırıldığında rehber **aynı değişiklikte** güncellenir. - Araçla yapılamayan işleri de yazın ("talep silmek için araç yok; uygulamayı Portal'da açın"); yapay zeka olmayan bir aracı uydurmaz, kullanıcıyı yönlendirir. - Rehber uygulamanın adresinde `/.well-known/one-agent.md`, araç kataloğu `/.well-known/one-agent.json` olarak sunulur; `create-devoplus-one-app` iskeletindeki `src/index.ts` başındaki iki satır bunu yapar. Bu adresler oturum istemez; rehbere kullanıcı verisi, sır ya da iç adres yazmayın. ## Uygulamanın yapay zekayı kullanması ```ts import { completeAi } from '@devoplus/one-sdk' const { output } = await completeAi(api, ctx, { task: 'summarize', input: metin, lang: 'tr' }) ``` - Manifest `scopes` içinde `ai.use` olmalıdır (kullanıcıdan ayrıca onay istenmez). - İşler: `summarize`, `classify` (`labels` ile, 2-50 etiket), `extract` (`schema` ile), `generate` ve `chat` (`messages` ile, en çok 20). Metin en çok 24.000, talimat en çok 4.000 karakter. - Model, kota ve portalda yapay zekanın açık olup olmadığı Devoplus'tadır: kapalı portalda 503, kota dolunca 429 döner. Uygulama bu durumda da çalışmayı sürdürür ("şu anda özet hazırlanamıyor"). - ⛔ Model **sayı hesaplamaz** ve **kayıt yazmaz**: tutar, toplam, tarih farkı kodda hesaplanıp `input`'a hazır verilir; modelin çıktısı bir öneridir. Veritabanına yazmadan önce kod doğrular, gerekirse kullanıcıya onaylatır. - `input`'a sır ya da işin gerektirmediği kişisel veri konmaz.