انتقل إلى المحتوى
وكلاء من أوكال

جارٍ تحميل دليل الاستخدام…

وكلاء من أوكال
للوكلاءالتواصل
وكلاء من أوكال
مسار دليل الاستخدام
دليل الاستخدام

ابدأ هنا

  • شغّل وكيلك الأول

بناء التكامل

  • بثّ الرسائل والأدوات والنتائج
  • أبقِ خادمك الخلفي متحكّمًا

الأدوات والسلوك

  • عرّف الأدوات داخل خادمك الخلفي
  • ربط خادم MCP بعيد
  • إضافة مهارات وتعليمات قابلة لإعادة الاستخدام
  • التعامل مع الموافقات والأسئلة والنماذج

التشغيل الموثوق

  • الأخطاء والتعافي
  • فهم الاستخدام والحدود
فهرس دليل الاستخدام للوكلاءدليل الاستخدام الكامل للوكلاء

التشغيل الموثوق

الأخطاء والتعافي

تعامل مع الأخطاء وأعد الاتصال بأمان وافحص إمكانات بيئة النشر دون تكرار العمل.

عرض Markdown

احفظ هوية طلب العمل

خزّن مفتاحًا ثابتًا لعدم تكرار الأثر مع عملية تطبيقك قبل إرسال العمل. إذا انتهت مهلة قبول الطلب، فأعد المحاولة بالجلسة ومتن الطلب والمفتاح نفسها. تعيد الخدمة التشغيل الذي قُبل أصلًا، أو تبلغ عن تعارض إذا اختلف متن الطلب.

python
run = await session.send(
    persisted_message,
    idempotency_key=persisted_request_id,
    subject={"id": authenticated_user_id},
)

تحافظ أخطاء النقل وقبول الطلب في SDK على مفتاح عدم تكرار الأثر. قد يؤدي إنشاء مفتاح جديد بعد استجابة غير مؤكدة إلى تكرار عمل التطبيق. ولا تُعاد تلقائيًا دون تحقق محاولات إنشاء الموارد العادية التي لا تضمن عدم تكرار الأثر.

فضّل التدفق عالي المستوى

تُحمّل run.stream() وuseSession() في React الحالة من لقطة، وتتعافيان تلقائيًا من الفجوات في تسلسل الأحداث. تحل اللقطة محل العرض السابق. قد يمثّل تحديث النص استبدالًا بعد التعافي. فلا تُلحق سلسلة تراكمية كاملة كما لو كانت إضافة من رموز نصية جديدة.

لبناء مستهلك أحداث يحفظ حالته بصورة دائمة، احفظ الحدث ومؤشر الموضع ضمن معاملة واحدة في التطبيق:

python
async with session.events(after=last_committed_cursor) as events:
    async for event in events:
        await persist_event_and_cursor(event)

تمثّل دالة حفظ الحدث ومؤشر الموضع المعاملة التي ينفّذها تطبيقك. يتحقق SDK منخفض المستوى من التسلسل قبل تصفية الأحداث بحسب التشغيل. تطلق الفجوة الاستثناء RecoveryRequired. احصل على لقطة جديدة بدلًا من المتابعة من حالة ناقصة. يمكن لأنواع الأحداث المستقبلية غير المعروفة تقديم مؤشر الموضع المتحقق منه دون اختلاق سجلات تخص مجال التطبيق.

ميّز بين حالات الإخفاق

الحالةالإجراء المناسب
انقطاع الشبكةاستأنف المراقبة. لا ترسل الطلب إلى الوكيل مجددًا
عدم التأكد من قبول الطلبأعد المحاولة بمتن الطلب ومفتاح عدم تكرار الأثر الأصليين
الحاجة إلى إدخالاعرض التفاعل المعلّق نفسه بخياراته الدقيقة
تغيّر إعدادات الجلسةأنشئ جلسة جديدة وفق التعيين الحالي
إخفاق التشغيل أو انقطاعهافحص النتيجة المحفوظة والآثار الجانبية على عمليات التطبيق
عملية خلفية غير مؤكدةسوِّ الحالة باستخدام إيصال عملية التطبيق. لا تفترض أن الإخفاق يعني عدم حدوث أثر جانبي
استخدام غير معروفأبقِ الحجز حتى إجراء تسوية موثّقة للتدقيق

تحتوي الخدمة الحالية على منسّق تنفيذ نشط واحد لكل قاعدة بيانات، تحميه آلية تأجير في قاعدة البيانات وحواجز تمنع المنسّق السابق من مواصلة العمل بعد فقدان صلاحيته. تستعيد الخدمة الحالة غير المؤكدة عند إعادة التشغيل دون إعادة إرسال الطلبات التي أُرسلت إلى الوكيل بالفعل تلقائيًا. لا يتضمن هذا الإصدار عمّال تنفيذ موزّعين أفقيًا ولا تفريعات جلسات أصلية تحتفظ بالحالة.

مهلات الطلبات، ومهلات خمول التدفق، ومهلات المراقبة، والمواعيد النهائية للتنفيذ ضوابط منفصلة. قد ينقطع اتصال المتصفح بينما يظل الوكيل قيد التشغيل.

الأخطاء والإمكانات

تستخدم أخطاء HTTP بنية ثابتة تحتوي على code وmessage وrequest_id وحقل details الاختياري. تميّز أخطاء SDK بين التفويض والتحقق من الصحة والتعارض وإخفاق النقل وإخفاق البروتوكول والحاجة إلى إدخال وانتهاء مهلة المراقبة. احتفظ بمعرّف الطلب في التقارير التشغيلية. ولا تسجّل مفاتيح API أو بيانات اعتماد المزوّد.

python
from wkala import APIError, TransportError, InputRequired, ObservationTimeout

try:
    run = await session.send(
        message,
        idempotency_key=persisted_request_id,
    )
    result = await run.wait(timeout=120)
except InputRequired as required:
    print("Present these interactions:", required.interactions)
except ObservationTimeout:
    print("The observer stopped waiting. The run may still be active.")
except TransportError as error:
    print("Admission may be uncertain:", error.idempotency_key)
except APIError as error:
    print(error.status_code, error.code, error.request_id)

إخفاق التنفيذ يختلف عن إخفاق قبول الطلب عبر HTTP. تظل نتائج التشغيل المنتهي متاحة للفحص. تحقّق من حالة التنفيذ وسبب التوقف معًا: فقد تتضمن جولة مكتملة رفضًا، أو تكون قد بلغت حدًا.

استعلم من بيئة النشر عن الإمكانات المدعومة

python
capabilities = await agents.capabilities.get()
print(capabilities.agent.streaming)
print(capabilities.agent.tool_events)
print(capabilities.agent.session_operations)

يوفّر SDK واجهة API ثابتة عبر بيئات النشر، لكن وجود دالة لا يضمن تفعيل كل إمكانية اختيارية. تعيد العمليات غير المدعومة capability_unavailable.

يدعم هذا الإصدار التنفيذ المتدفق، والأدوات ونتائجها، وخوادم MCP المملوكة للتطبيق، وحزم التعليمات، والأذونات الصريحة، والأسئلة، ولقطات التعافي، وبيانات الاستخدام. تظل إمكانات الصدفة والملفات والشبكة والتفويض إلى وكلاء آخرين على المضيف محظورة. لا تتوفر سكربتات المهارات القابلة للتنفيذ، ولا التصدير الأصلي للملفات الناتجة، ولا تفريعات الجلسات التي تحتفظ بالحالة. قد تتضمن نتائج الأدوات روابط إلى موارد يصرّح تطبيقك بالوصول إليها. وهذا لا يحوّل ملفات محلية عشوائية إلى تنزيلات مستضافة.

ينبغي لطبقة التجريد عالية المستوى أن تحافظ على هذه الفروق. لا تفعل ما يلي:

  • تحويل تكلفة غير معروفة إلى صفر.
  • تحويل ملف ناتج غير متاح إلى تنزيل وهمي.
  • اعتبار نسخة من سجل المحادثة تفريعًا للجلسة.
  • اعتبار انقطاع الاتصال إلغاءً.
التعامل مع الموافقات والأسئلة والنماذجفهم الاستخدام والحدود