اختر بيانات الاعتماد حسب صاحب العملية
لا يحتاج عرض كتالوج عام إلى بيانات اعتماد. أما «حجوزاتي» فتحتاج إلى Token المستخدم المسجّل. وقد يحتاج استعلام بين خادمك وخدمة شريكة إلى Service API Key. اختر النوع الذي يملك صلاحية العملية المطلوبة؛ هذه الأنواع ليست بدائل متكافئة.
في مثال الحجز، يمرّر التطبيق auth.token. وعند ضبط request.auth.type: session، يضيف AGENTO الـ Bearer Token إلى Header عند التنفيذ. إذا غاب الـ Token، قد يُرسل الـ Request دون هذا الـ Header، وتبقى مسؤولية رفضه على الـ API. لذلك تحقّق من تسجيل الدخول داخل تطبيقك قبل العمليات المحمية.
لمفاتيح الخدمات، ضع اسم الـ Environment Variable تحت env؛ تغيير اسم header يغيّر الترويسة، وليس الصلاحيات التي يمنحها المفتاح. غياب مفتاح خدمة مطلوب يفشل compilation.
اختبر الحدود مع API لديك
جرّب العملية نفسها باستخدام Token صحيحة، وأخرى منتهية، وID لمورد يخص مستخدمًا آخر، ودون Token. يجب أن تتحقق API من الملكية، وأن تتعامل مع 401 و403 عبر AUTH_REJECTED. ثم اختبر تبديل الحساب؛ أنشئ محادثة مصرّحًا بها جديدة أو امسح الـ Session القديمة بدل نقل موافقة معلّقة إلى هوية أخرى.
أبقِ بيانات الاعتماد خارج Config الذي يكتبه المتصفح، وقيم Input الـ AI Model، وmapped headers، وcontext العادي. يدعم redaction ضوابط الوصول في تطبيقك، ولا يحل محلها.
AGENTO ليس خادم Auth لديك
لا يفك Runtime الحالي ترميز JWTs الخاصة بالمستخدمين، ولا يجلب مفاتيح JWKS، ولا يتحقق من issuers أو audiences، ولا يقرّر صلاحيات العمل. هذا الفصل مقصود.
تبقى API المستقبِلة هي المرجع في:
- صلاحية Token وانتهاء مدته.
- حالة تسجيل الدخول.
- الأدوار وscopes.
- حدود tenants.
- ملكية الموارد.
- صلاحيات إجراءات العمل.
Tools تتطلب مصادقة المستخدم
request:
auth:
type: session
يمرّر التطبيق المضيف الموثوق Token الخاص بالمتصل:
const result = await runtime.invoke({
sessionId: serverOwnedSessionId,
tool: "my-bookings",
auth: { token: userAccessToken },
});
وعند التنفيذ، يرسل AGENTO:
Authorization: Bearer <opaque-token>
لا يُفترض إدراج Token في prompts أو Schemas التي يراها الـ AI Model، أو سياق الـ Session العادي، أو النتائج، أو hooks.
Responses 401 و403
تظهر Responses الخدمة المستقبِلة 401 و403 على هيئة AUTH_REJECTED، مع رمز الحالة ضمن تفاصيل الخطأ المحدودة. ويقرر التطبيق المضيف إن كان المطلوب تسجيل الدخول مجددًا، أو تجديد الـ Session، أو إبلاغ المستخدم بأنه لا يملك الصلاحية.
Session ID لا يثبت هوية المستخدم
قاعدة أساسية في Production:
يحدد
sessionIdالمحادثة أو العملية التي تريد متابعتها، ولا يثبت هوية المستخدم.
يجب أن يربط التطبيق المضيف قيم Session ID التي يديرها الخادم بالمتصلين. لا تسمح للعميل باختيار Session مستخدم آخر عشوائيًا، أو ربط Token لمستخدم مختلف بـ Session قائمة.
عند تبديل الحساب، امسح الـ Session السابقة أو أنشئ Session ID جديدًا يديره الخادم.
Tools تستخدم API key
لبيانات الاعتماد بين الخوادم:
request:
auth:
type: api-key
env: SERVICE_KEY
header: X-API-Key
يتوقع compiler وجود Environment Variable. لا تضع مفاتيح الخدمات في URLs أو Input المستخدم أو prompts.
الـ Tools العامة
request:
auth:
type: none
استخدم هذا النوع فقط عندما تكون REST Endpoint عامة فعلًا.
إعادة استخدام بيانات اعتماد الـ Session
يمكن لـAGENTO الاحتفاظ بـ Token دون تفسير محتواه للـ Session لتستخدمه استدعاءات select() وconfirm() اللاحقة. تدعم واجهة Auth المصدّرة SessionTokenStore مخصصًا؛ وتُشفّر قيم Tokens قبل وصولها إلى المخزن.
عند استخدام مخزن مخصص، وفّر مفتاح تشفير مشتركًا بطول 32 بايت للـworkers التي تحتاج إلى استخدام بيانات الاعتماد نفسها عبر عدة instances.
حجب البيانات الحساسة
يحمي Runtime البيانات الحساسة المعروفة والحقول الحساسة في النتائج والسجل وhooks والبيانات المتجهة إلى الـ AI Model. هذه حماية أثناء النقل، وليست مصنّفًا شاملًا للبيانات الشخصية PII.
يجب أن تظل API مسؤولة عن إعادة البيانات المناسبة للمتصل فقط، وتقليل البيانات وفق طبيعة مجالك.
ضوابط النقل
- الطلبات التي تحمل بيانات اعتماد تتطلب HTTPS، إلا عند تعطيل ذلك صراحةً للتطوير المحلي.
- تُحظر redirects.
- يتحقق Runtime من تطابق origin النهائي للطلب مع الـ Origin المحدد في الـ Config.
- يوجد حد أقصى لحجم Response Body بالبايت.
- البيانات المقتطعة للعرض على الـ AI Model محدودة الحجم.
- لا يمكن تعريف بيانات الاعتماد كحقول Input عادية للـ AI Model.