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

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

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

ابدأ هنا

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

بناء التكامل

  • بثّ الرسائل والأدوات والنتائج
  • أبقِ خادمك الخلفي متحكّمًا
  • بناء واجهة React تفاعلية مباشرة
  • ربط تطبيق Next.js

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

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

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

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

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

فهم الاستخدام والحدود

تتبّع رسوم العملاء والحجوزات والحالات غير المؤكدة وسياسات الحساب المطبّقة على كل تشغيل.

عرض Markdown

لتكامل Next.js ومتطلبات الواجهة الخلفية Python، راجع Next.js.

دلالات الأسعار

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

يعرض SDK المبلغ المسجّل على العميل؛ ولا يحسب الرسوم في المتصفح. تبقى المبالغ التي قُبلت بالفعل مرتبطة بتشغيلها طوال التسوية والمطابقة.

تُمثَّل الأموال بأعداد صحيحة بوحدة الميكرو دولار أمريكي: 1,000,000 وحدة = دولار أمريكي واحد. تمثّل usage.cost_microusd العامة، والحدود القصوى للتشغيل، والميزانيات الشهرية للحسابات، والحجوزات مبالغ تخص العميل.

اقرأ النتيجة بعد وصول التشغيل إلى حالة نهائية. ترفض run.result() الطلب ما دام التشغيل نشطًا.

typescript
const result = await run.result()
const usage = result.usage
if (usage.cost_microusd === null) {
  console.log("Cost is unresolved; do not display zero.")
} else {
  console.log("Customer micro-USD:", usage.cost_microusd)
}
console.log("Source:", usage.source, "Settlement:", usage.status)

المصدر والتسوية

تكون قيمة source إحدى القيم provider_reported أو estimated أو simulated أو unknown. يُحسب المبلغ التقديري من بيانات وقت التشغيل والكتالوج المتاحة؛ وليس فاتورة مورّد متحققًا منها. اكتشاف الكتالوج وحده لا يثبت أن المزوّد أكّد تلك الأسعار حديثًا.

تكون قيمة status إحدى القيم reserved أو settled أو pending_reconciliation. عند غياب الاستخدام النهائي، يبقى الاستخدام غير معروف ويُحتفظ بحجزه. تبقى المبالغ المحاكاة منفصلة عن الرسوم الفعلية. يمكن للمشغّل تسوية مبلغ نهائي مع ذكر السبب؛ وتسجّل الخدمة تسوية غير قابلة للتعديل.

سياسات الحساب

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

يحدّد ملف التعريف هذا حدًا أقصى على العميل قدره 0.30 دولار لكل تشغيل.

typescript
const profile = await agents.profiles.create({
  name: "Bounded reviewer",
  instructions: "Review the supplied content concisely.",
  max_cost_microusd: 300_000,
  timeout_seconds: 120,
})

العتبات ضوابط لقبول الطلب والحجز والإيقاف. قد تتجاوز الطلبات الخارجية قيد التنفيذ عتبة الإيقاف؛ فهي لا تضمن أن تتوقف فاتورة المورّد عند مبلغ دقيق. تُحتفظ الحجوزات غير المعروفة بدلًا من إخفائها.

الإتاحة

يتطلب العمل الجديد هوية متحققًا منها، وحسابًا نشطًا، ومزوّدًا معيّنًا ومفعّلًا، ونموذجًا مسموحًا، وتسعيرًا معروفًا، واستيفاء الحدود. يستطيع صاحب الحساب المعلّق أو الموقوف أو المرفوض الاطلاع على الحالة والسجل. يَحظر الإيقاف العمل الجديد؛ أما إلغاء العمل المقبول مسبقًا فيتطلب إجراءً صريحًا.

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

الدقة العددية

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

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