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: uygulamanız 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ızı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.

Hangi araçlar gerekir

Kullanıcılarınızın Devoplus asistanına bu uygulama hakkında ne soracağını düşünün: "bekleyen izin taleplerimi göster", "bu ayki rezervasyonlarım neler". Her soru bir araç adayıdır. Bir şeyi değiştiren işlemlerde karar sizindir: asistan talep oluşturabilsin mi, yoksa yalnız göstersin mi? Cevabınız hayırsa o araç yazılmaz.

Araç tasarlama

Her araç üç yerde birlikte durur:

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 ya da 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 ve -, 2-40 karakter; en çok 20 araç.
• description modelin seçim ölçütüdür: ne yapar, ne döndürür, ne zaman kullanılmaz. "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ı) araçta da aynen uygulanır. Rol gereken araç permission alanına uygulamanın kendi izin kodunu (permission.code ya da permissions[] içinden biri) yazar. Yönetici baypası ctx.admin'dir: aracı çağıran kişi kurulumun portalının şirket yöneticisiyse true olur ve hasPermission her kodda true döner. Vekalet ya da 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 ve kişiler gibi servisleri aracı çağıran kişinin yetkisiyle kullanabilir. ⛔ Süreli onay isteyen yetki alanları araçta 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 bu kodları kendisinin 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ı ya da 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/<ad>); 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:

# <Uygulama adı>: 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ı uygulamaya yönlendirir.
• Rehber uygulamanın adresinde /.well-known/one-agent.md, araç kataloğu /.well-known/one-agent.json olarak sunulur; iskeletteki 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ı

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. Uygulamanız bu durumda da çalışmayı sürdürmelidir ("şu anda özet hazırlanamıyor").
• ⛔ Model sayı hesaplamaz ve kayıt yazmaz: tutar, toplam ve tarih farkı kodda hesaplanıp input'a hazır verilir; modelin çıktısı bir öneridir. Veritabanına yazmadan önce kodunuz doğrular, gerekirse kullanıcıya onaylatır.
• input'a sır ya da işin gerektirmediği kişisel veri konmaz.