Aksiyonlar ve risk seviyeleri

Aksiyon, kodda kaydettiğiniz tiplendirilmiş bir yetenektir: ad, açıklama, parametre şeması, risk seviyesi ve uygulamanızın içinde çalışan bir işleyici. Uygulamanızda kaydedilen bir aksiyon bize hiçbir kimlik bilgisi ve yükseltilmiş yetki vermez: işleyiciniz, uygulamanızın geri kalanının kullandığı aynı oturumu ve arka uç çağrılarını kullanır. Yönetim panelinde eklediğiniz aksiyonlar ise farklıdır. Sunucu, API'nizi ya ona verdiğiniz bir anahtar veya hesapla (salt okunur) ya da giriş yapmış kişinin kendi token'ı ile bizzat çağırır. Bkz. yönetim panelinden aksiyonlar.

Risk seviyeleri

Yönetim paneli bir aksiyonun riskini bildirilen değerden daha katı hâle getirebilir, asla daha gevşek yapamaz ve herhangi bir aksiyonu anında devre dışı bırakabilir.

Varsayılan olarak cihaz, sunucuya kullanıcının onayladığını bildirir. Settings → Security → Request verification → Record confirmations on the server ayarını açtığınızda SDK, işleyiciniz çalışmadan önce dokunmayı POST /v1/invocations/:id/confirm adresinde kaydeder; sunucu daha sonra cihazın kendi beyanını yok sayar. Bkz. Security. Bir write veya destructive aksiyonu her zaman tek başına önerilir: onu gösteren sayfayla aynı turu paylaşabilse de hiçbir zaman başka bir aksiyonla aynı turda önerilmez.

Kullanıcının kart üzerinde değiştirebileceği değerler

Bir write veya destructive aksiyonu, kullanıcının onaylamadan önce onay kartı üzerinde değiştirebileceği parametreleri belirtebilir: Flutter ve Web SDK'larındaki aksiyonda editable veya bir yönetim paneli aksiyonunun parametresinin yanındaki Changeable on the card seçeneği. Model “2 bilet” önerir, kullanıcı 3 bilet ister: tekrar sormak yerine kart üzerinden değiştirir.

Kart her birini kendi tipine uygun bir denetim olarak çizer: bir sayı için artırıcı (stepper) veya sayı alanı, metin için metin alanı, bir listeden biri için seçici (picker), evet veya hayır için bir anahtar (switch). Değiştirilen değer sunucuya gider; sunucu bunu tıpkı modelin önerisini denetlediği gibi denetler (tip, enum, sınırlar, uzunluk) ve kartı bu değerle yeniden çizer, böylece karttaki soru her zaman neyin çalışacağını gösterir. Doğrulamadan geçemeyen bir değer, nedeni belirtilerek reddedilir. İşleyiciniz veya uç noktanız değerleri onaylandığı şekliyle alır.

Kullanıcının makul olarak değiştirebileceği şeyleri işaretleyin: bir miktar, yeniden ifade edebileceği bir not veya mesaj, birkaç seçenekten biri (iadenin nereye aktarılacağı), evet ya da hayır işareti. Asla bir kimlik (id) veya fiyat ya da toplam gibi uygulamanızın hesapladığı bir tutar olmamalıdır: kart, kullanıcının ne istediğini söylemesi için son şansıdır; uygulamanın neye karar verdiğini değiştirmenin bir yolu değildir.

Kayıt

Bir aksiyon; bir ad, bir açıklama, bir parametre şeması, bir risk seviyesi ve bir işleyicidir. Bir uç noktanın uygulamanızda çalışması gerektiğinde yapay zekâ kodlama aracınız bunu yazar (Bir uç nokta bağlayın); API, Flutter SDK ve Web SDK referanslarında yer alır.

• Açıklama modeli yönlendirir. İsimler, açıklamalar ve parametre tipleri arasından seçim yapar; bu yüzden aksiyonun ne zaman doğru tercih olduğunu kullanıcılarınızın kelimeleriyle belirtin.
• Herhangi bir şey çalışmadan önce parametreler kontrol edilir: tipler, enum'lar, sınırlar ve zorunlu anahtarlar denetlenir, tanımlanmamış her şey reddedilir. Başarısız olan bir öneri düzeltme olarak modele geri döner, asla handler'ınıza iletilmez.
• confirmTemplate, write ve destructive aksiyonları için sunucunun oluşturduğu onay kartının metnini belirler.
• İsimler snake_case formatındadır. Sunucu tek bir hatalı isim yüzünden tüm manifesti reddeder; bu yüzden SDK, yazdığınız yerde bunu doğrular.
• Bir handler'ın varsayılan olarak on beş saniyesi vardır. Bu süre aşıldığında, modele aksiyonun başarısız olduğu bildirilir.
• İki kez çalıştırmanın hiç çalıştırmamaktan daha kötü olacağı durumlarda, handler invocation'ın tamamını alır ve yeniden denenen bir tur boyunca sabit kalan id değerini bir idempotency key olarak kullanır (RendelInvocation).

Uygulama kodunda veya sunucuda

Her aksiyon iki yerden birinde çalışır ve yönetim panelinin Actions sayfası her ikisini de tek bir listenin iki sekmesinde listeler: In app code (uygulamanızın en son derlemesinin bildirdiği şekliyle registerAction ile kaydettiği şeyler) ve On server (Rendel'in sunucusunun çağırdığı uç noktalar). Her satır nereden geldiğini taşır: AI setup, Import veya Manual.

Çağrının izin verdiği her yerde on server seçeneğini tercih edin: yeni bir sürüm çıkarmadan yönetim panelinde düzenlenebilir ve oradaki bir yazma aksiyonu aşağıda açıklanan sunucuya kaydedilen onaydan geçer. Koda yalnızca bir sunucunun çağıramayacağı şeyleri kaydedin. Bir yapay zekâ kodlama aracının izlediği kural da budur:

Sunucuda oturum açmış kullanıcı olarak çalışan bir aksiyon, uygulamanızdan bu kullanıcının belirtecine ihtiyaç duyar: Flutter'da RendelConfig.userToken, web'de setUserToken.

Yönetim panelinden aksiyonlar

Bir aksiyonun kod olması gerekmez. On server sekmesinde yer alan Connect an API, tarayıcıda zaten çalışan tek bir adresi alır veya API'nizin dokümantasyonunu (bir Swagger ya da OpenAPI sayfası, bir YAML spesifikasyonu, referansın bir PDF'i veya bir Postman koleksiyonu (v2.1 .json)) okur, uç noktaları listeler ve ekibiniz Rendel'in kullanabileceği olanları işaretler. Sunucu bunları çağırır; uygulamada hiçbir şey kaydedilmez.

Bir parametre metin, sayı, evet ya da hayır, bir listeden biri (yalnızca sizin belirttiğiniz değerler) veya metin ya da sayılardan oluşan bir liste olabilir. Bir liste, sorgu dizesine (query string) yinelenen anahtar olarak (tag=a&tag=b) ve gövdeye (body) bir JSON dizisi olarak gider. Modele izin verilen değerler bildirilir ve sunucu, uç noktanız çağrılmadan önce bunların dışındaki her şeyi reddeder.

Paylaşılan bir anahtar isteyen ve henüz anahtarı olmayan bir uç nokta, Add key seçeneğiyle birlikte kapalı olarak gösterilir. Bir yapay zekâ kodlama aracı bunu böyle bırakır: nereye ne tür bir anahtarın gideceğini söyleyebilir, ancak asla anahtarın kendisini söylemez. Anahtarı girin; aksiyon artık açılabilir. Buraya girilen bir anahtar, kurulum veya bir senkronizasyon aksiyonu tekrar gönderdiğinde korunur.

Paylaşılan API anahtarları

Aynı sekmedeki API keys for your APIs altında, bir anahtar tek bir ana makine (api.example.com) için bir kez saklanır ve bir üstbilgide (header), bir sorgu parametresinde veya Bearer belirteci olarak gönderilir. O ana makinedeki her uç nokta bunu kullanabilir ve Replace key seçeneği hepsi için aynı anda değiştirir. Bekleyen bir uç noktanın altında Add key ile girilen bir anahtar da burada saklanır ve aynı API'de aynı anahtarı bekleyen bir sonraki uç nokta bunu tek bir dokunuşla alır.

Bir uç nokta, paylaşılan bir anahtarı ya kendi anahtarı yerine tek başına ya da oturum açmış kullanıcının belirtecinin yanında gönderir: belirteç Authorization: Bearer olarak (veya auth_name değerinin belirttiği yerde), anahtar ise kendi üstbilgisinde veya parametresinde yer alır. Uygulamanızın anahtarını ve kullanıcının oturumunu birlikte isteyen bir API'nin yapısı böyledir. Uç noktanın düzenleyicisinde bunu Also send a shared key altında seçin.

Paylaşılan bir anahtar yalnızca kaydedildiği ana makineye ve yalnızca https üzerinden gider. Sunucu, her değer doldurulduktan sonra çağırmak üzere olduğu adresi denetler; başka bir ana makinede, düz http üzerinden veya anahtar ile kullanıcının belirtecinin aynı üstbilgiye gideceği durumlarda çağrı yapılmaz ve Rendel'e nedeni bildirilir. Anahtar şifrelenmiş olarak saklanır, kaydettikten sonra bir daha asla gösterilmez ve hiçbir yönetim paneli oturumu bunu geri okuyamaz. Bir anahtarı kaldırmak, onu kullanan uç noktaları kapatır ve yeniden anahtar ister.

Çağrının kimin adına yapıldığı, neler yapabileceğini belirler:

Yönetim panelindeki bir yazma aksiyonu her zaman onay gerektirir ve bunun gerçekleşip gerçekleşmediğine cihaz değil, sunucu karar verir: kart aksiyonun onay sorusundan çizilir, dokunmayı sohbetin sahibi olan cihaz için onay uç noktası kaydeder ve sunucu ancak bundan sonra dokunan kişinin belirteciyle uç noktanızı bir kez çağırır. Bir devam işlemini yeniden denemek bunu asla iki kez göndermez; dönüş yolunda bir yanıt kaybolursa Rendel tekrar denemek yerine değişikliğin gerçekleşip gerçekleşmediğini bilmediğini söyler. Yazma aksiyonları siz içe aktarırken veya önizlerken çağrılmaz ve yalnızca bunları onaylayabilen derlemelere sunulur (Flutter 0.27.0 ve web 0.5.0 veya üzeri).

Bir yazma aksiyonunun kimin için olduğunu da bilmesi gerekir. Yalnızca uygulamanızın oturum açmış kişiyi identify ile adlandırdığı bir turda sunulur ve kart bu kişiyi hatırlar. Sunucu bunu yalnızca onaylayan istek aynı kişiyi adlandırıyorsa çalıştırır; böylece reset() çağrısı yapmadan hesap değiştiren bir telefon, bir kişinin onayını başka bir kişinin hesabında harcayamaz; aynı kişi için yenilenen bir belirteç çalışmaya devam eder. Kimlik doğrulamayı (arka ucunuzdan gelen bir userHmac) açtıysanız onaylayan istek kişiyi bununla kanıtlamalıdır. Doğrulama olmadan eşleme, uygulamanızın identify işlevine ilettiği kimlik (id) kadar güvenilirdir.

Bir dokunmanın aksiyon olmadan yapabilecekleri

Bir sayfadaki butonlar altı türden birini taşır ve her biri yalnızca onu yerine getiren bir derlemeye sunulur: reply (bir sonraki soruyu sorar), open_url (yalnızca https; external yalnızca harita bağlantısı için), navigate (sunucunun rotaya göre denetlediği parametrelerle registerRoute ile kaydettiğiniz bir ekranın open işlevini çağırır), call (numara doldurulmuş şekilde arama ekranını açar), copy ve add_to_calendar (cihazın kendi düzenleyicisini açar). Kullanıcı her birini bizzat tamamladığı için hiçbiri bir aksiyon işleyicisi çalıştırmaz veya bir onay kartına ihtiyaç duymaz. Numaranın, değerin, saatlerin ve herhangi bir fromActions parametresinin aksiyonlarınızın sonuçlarından gelmek zorunda olmasının nedeni de budur (bkz. Sunucunun denetlediği değerler).

Manifest

Başlangıçta SDK, aksiyon kümenizi standartlaştırır ve değişmez, karma (hashed) bir manifest olarak senkronize eder. Sahadaki farklı uygulama sürümleri çakışmadan bir arada bulunur; her sohbet tam olarak hangi manifest altında çalıştığını kaydeder. Manifest MCP araç yapısını kullanır; bu nedenle aksiyonlarınızı daha sonra diğer yapay zekâ araçlarına açmak, kodu yeniden yazmayı değil, yalnızca bir serileştiriciyi gerektirir.

Başarısızlık bir çökme değil, bir mesajdır

Hata fırlatan veya zaman aşımına uğrayan bir işleyici, modelin okuyabileceği bir hata sonucuna dönüşür. Model özür diler, ayarlarını düzenler veya yeniden dener; uygulamanız çalışmaya devam eder.