خطوات الوكيل والتحويلات

قسّم الوكيل إلى خطوات لها تعليماتها وأدواتها وقيمها المجمّعة، ومرّر المكالمات بين الوكلاء أثناء المكالمة.

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

يبدأ كل وكيل بموجّه واحد. لا يتغير فيه شيء حتى تضيف خطوات أو عمليات تسليم.

الخطوات أم موجّه واحد؟#

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

كيفية إنشاء وكيل يعتمد على خطوات#

عندما يحتوي الوكيل على خطوات، يحتفظ prompt بـ التعليمات المشتركة: الشخصية والقواعد التي تنطبق في كل خطوة. تضيف كل خطوة تعليماتها الخاصة فوق ذلك. في كل دور، يرى النموذج التعليمات المشتركة، واسم الخطوة الحالية وتعليماتها، والقيم التي جُمعت حتى الآن.

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

عبر واجهة API، يمثل steps وhandoffs حقلين في الوكيل. مثل كل حقل في الوكيل، يضعهما PATCH في المسودة؛ ويجعل POST /v1/agents/{agent_id}/deploy التغييرات منشورة. يؤدي إرسال "steps": null إلى إعادة الوكيل إلى موجّه واحد. تعمل مكالمات الاختبار وتحدث على المسودة.

حقول الخطوة#

المخطط نفسه هو {"start_step": "<step id>", "steps": [...]}. تبدأ المكالمة في start_step.

الانتقالات#

يحتوي كل انتقال على to، وهو معرّف خطوة، وعلى واحد مما يلي فقط:

• when: بلغة واضحة، ويقرر النموذج. يحصل الوكيل على أداة go_to_step مدمجة تسرد الخطوات التي يمكنه الانتقال إليها، مع استخدام كل when سببًا لاختيارها.
• condition: قاعدة على القيم المجمعة، ويقرر الكود. لا يستطيع النموذج تخطيها أو التحايل عليها بالكلام.
• "always": true: الانتقال دون تحقق. يقرر الكود أولًا: بمجرد دخول خطوة ما، أو عند جمع قيمها المطلوبة، يفوز أول انتقال مطابق من نوع condition أو always قبل أن يتمكن النموذج من اختيار when. لذا ضع always بعد الشروط بوصفه بديلها الاحتياطي، أو بمفرده لربط خطوة مباشرة بالخطوة التالية. لا تنتظر خطوة تحتوي على always اختيار when مطلقًا.

تكون condition بالشكل {"value": <collected name or dotted path>, "op": <op>, "target": <literal>}:

تقارن eq وne وin وnot_in النصوص من دون حساسية لحالة الأحرف بعد إزالة المسافات. تُقارن الأرقام بوصفها أرقامًا والتواريخ بوصفها سلاسل YYYY-MM-DD. القيمة التي لم تُجمع مطلقًا تجعل كل عملية خاطئة باستثناء missing.

اكتب when وglobal_when بوصفهما شرطًا، مثل "يريد المتصل حجز موعد"، وليس بوصفهما شيئًا يُقال. يراهما الوكيل كملاحظات توجيه داخلية ويُوجَّه إلى عدم قراءتهما بصوت عالٍ أو ذكر أنه يغيّر الخطوات.

عندما يستدعي النموذج go_to_step:

1. يجب أن تكون كل قيمة required في الخطوة موجودة. إذا كانت إحداها مفقودة، يُخبَر النموذج بها ويطلبها من المتصل.
2. تُخزَّن القيم.
3. تُفحَص انتقالات condition وalways بالترتيب. يفوز أول تطابق.
4. بخلاف ذلك، ينتقل الوكيل إلى الخطوة التي اختارها النموذج.
5. إذا لم يطابق شيء ولم يسمِّ النموذج أي خطوة، يبقى الوكيل في مكانه.

الانتقال إلى خطوة عامة هو الاستثناء: فقد غيّر المتصل الموضوع، لذا يُنفَّذ الانتقال حتى عندما تظل في الخطوة الحالية قيم مطلوبة مفقودة، وقبل فحص شروط تلك الخطوة.

تُفحَص انتقالات condition وalways أيضًا كلما تم الدخول إلى خطوة، لذا يُنفَّذ تسلسل الخطوات التي يقررها الكود دفعة واحدة. يتوقف التسلسل:

• عند خطوة زارها بالفعل خلال هذا التنفيذ؛
• بعد 8 انتقالات؛
• عند خطوة لا تزال تتطلب جمع قيم مطلوبة، ما لم تكن الخطوة تحتوي على on_enter_tool (توجّه خطوة webhook دائمًا بناءً على نتيجتها).

يُنطق فقط سطر say الخاص بالخطوة التي يتوقف عندها التسلسل.

الخطوة التي لا تحتوي على انتقالات تكون نهائية. ينهي الوكيل عمله فيها وينهي المكالمة أو يحولها باستخدام إجراءاته المدمجة المعتادة.

جمع القيم#

أدرج ما تحتاجه الخطوة في collect. يمرر النموذج القيم عند استدعاء go_to_step، وتظل متاحة لبقية المكالمة.

القيم المجمعة هي محتوى المكالمة. تظهر في المكالمة بجانب النص المفرغ وتتبع قواعد الاحتفاظ والحذف والتنقيح نفسها. عند إيقاف تسجيل مكالمات الوكيل، لا تُخزَّن القيم المجمعة ولا تُرسل في webhooks؛ بينما يبقى المخطط الزمني للخطوة. راجع مكان رؤيتها في المكالمة.

أسطر النطق#

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

يكون say في خطوة البدء هو السطر الافتتاحي للوكيل عندما يتحدث أولًا، بعد أي إعلان للموافقة. عندما يتحدث المتصل أولًا، فإنه يفتتح أول رد للوكيل على شخص، وليس على قائمة هاتفية آلية أو تحية بريد صوتي.

لا يُنطَق say الخاص بالخطوة مرة أخرى عندما تعود المكالمة إليها عبر __previous__ أو عبر تسليم راجع. اكتبه بالطريقة التي ينبغي أن يبدو عليها: اكتب أي شيء قد يسيء الصوت قراءته كتابةً كاملة. تدعم أسطر النطق متغيرات المكالمة {{var}}، لكنها لا تدعم القيم المجمعة.

خطوات Webhook#

عيّن on_enter_tool إلى إحدى أدوات الوكيل لتعمل فور دخول الخطوة، من دون انتظار النموذج. تكون وسيطاتها هي القيم المجمعة التي تطابق أسماؤها أسماء معلمات الأداة. تُخزَّن النتيجة كقيمة مجمعة باسم <tool>_result، وتُقتطع إلى 4 كيلوبايت، وتُفحَص انتقالات condition وalways الخاصة بالخطوة مباشرةً، بحيث يمكن لعملية البحث توجيه المكالمة بناءً على نتيجتها الخاصة.

تحتوي القيمة المخزنة على حقلين:

وجّه بناءً على حقل في النص باستخدام lookup_account_result.response.<field>، وبناءً على رمز الحالة باستخدام lookup_account_result.status.

تعمل عملية البحث لمدة تصل إلى 8 ثوانٍ، أو مهلة الأداة نفسها إذا كانت أقصر. إذا استغرقت أكثر من 3 ثوانٍ، يقول الوكيل سطرًا قصيرًا كي لا يُترك المتصل في صمت. إذا أعادت نقطة النهاية لديك حالة 400 أو أعلى، أو لم تستجب في الوقت المحدد، يخبر الوكيل المتصل بأنه لم يتمكن من التحقق من ذلك الآن ويواصل بما يستطيع فعله.

الخطوات العامة#

يمكن الوصول إلى خطوة تتضمن global_when من أي خطوة كلما انطبق ذلك الوصف. يقرر النموذج ذلك، كما في when. استخدمها للمواضيع التي قد يطرحها المتصل في أي وقت: أسئلة الفوترة، أو طلب التحدث إلى شخص، أو شكوى.

يعيد انتقال يتضمن "to": "__previous__" في خطوة عامة المكالمة إلى الخطوة التي كانت نشطة قبلها، لكي يواصل المتصل من حيث توقف. تُستأنف الخطوة: لا تعمل on_enter_tool الخاصة بها مرة أخرى، ولا يتكرر say الخاص بها، ويواصلها الوكيل من دون البدء من جديد.

إحالات المكالمات#

يسرد handoffs الوكلاء الآخرين في مؤسستك الذين يمكنهم تولي المكالمة:

[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]

يحصل الوكيل على أداة hand_off مدمجة تتضمن هؤلاء الوكلاء والأسباب. وكما هو الحال مع الانتقالات، يكون كل when ملاحظة توجيه داخلية ولا يُنطق أبداً.

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

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

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

go_to_step وhand_off اسمان محجوزان للوكلاء ذوي الخطوات أو الإحالات، لذا لا يمكن لأدواتك الخاصة استخدام هذين الاسمين.

أين تراها في مكالمة#

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

يحمل كائن المكالمة وخطاف الويب عند اكتمال المكالمة (telephony.complete / web.complete) البيانات نفسها ضمن steps_trace وcollected_values. وكلاهما غير موجود في المكالمات من دون خطوات.

"steps_trace": [
  {"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
  {"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
  {"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}

agent هو a متبوعاً بمعرّف الوكيل. يوضّح via ما الذي نقل المكالمة:

أين تعمل الخطوات#

تعمل الخطوات محلياً على Spark وBolt وكل منتجات Storm، في المكالمات الواردة والصادرة ومكالمات الحملات ومكالمات الاختبار ومكالمات الويب والودجات.

في كل مكان آخر، يستمر الوكيل في العمل ولكن من دون البنية: يشغّل موجّهاً مسطحاً يدمج التعليمات المشتركة وكل خطوة بالترتيب. يشمل ذلك:

• منتجات Bolt التجريبية؛
• جلسات Realtime، بما في ذلك الجلسات الخاصة بوكيل محفوظ؛
• الإعدادات المضمنة التي يعيدها خطاف ويب لـإعداد مكالمة ديناميكي. يستخدم خطاف الويب الذي يعيد agent_id خطوات ذلك الوكيل.

الحدود#

يؤدي الحفظ الذي يخالف قاعدة إلى إرجاع 400 مع مسار الحقل غير الصحيح، مثل steps.steps[2].transitions[0].to. يجب أن تكون أسماء الأدوات في tools و on_enter_tool أدوات مرتبطة بالوكيل.

لا تُدعم اللغات لكل خطوة، أو الخطوات المبرمجة التي تتجاوز النموذج، أو القيم المجمعة داخل أسطر say.

الوكلاء المستوردون#

يؤدي الاستيراد من Retell أو Bland أو Vapi أو ElevenLabs إلى نقل الوكلاء متعددي الموجّهات والتدفقات والمسارات ومسارات العمل كخطوات، ونقل الفرق وتحويلات الوكلاء كعمليات تحويل بين الوكلاء المستوردين. تعرض صفحة المراجعة كلاهما قبل الاستيراد.

مثال: استقبال مرضى الأسنان#

ثلاث خطوات بالترتيب: رحّب، اجمع تفاصيل المريض، احجز.

{
  "prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
  "steps": {
    "start_step": "greet",
    "steps": [
      {
        "id": "greet",
        "name": "Greeting",
        "instructions": "Greet the caller and ask how you can help.",
        "say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
        "tools": null,
        "collect": [],
        "transitions": [
          {"to": "details", "when": "The caller wants to book an appointment"}
        ]
      },
      {
        "id": "details",
        "name": "Patient details",
        "instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
        "tools": null,
        "collect": [
          {"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
          {"name": "dob", "type": "date", "description": "Date of birth", "required": true},
          {"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
          {"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
        ],
        "transitions": [
          {"to": "book", "when": "The caller has confirmed their details"}
        ]
      },
      {
        "id": "book",
        "name": "Book",
        "instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
        "tools": ["book_slot"],
        "collect": [],
        "transitions": []
      }
    ]
  }
}

جهّزه تجريبيًا باستخدام PATCH /v1/agents/{agent_id}، وجرّبه باستخدام تحدث، ثم انشره. لا يمكن لخطوة details التحويل إلى الحجز حتى تُجمع الاسم وتاريخ الميلاد والسبب؛ أما new_patient فهو اختياري.

مثال: فرع مقيّد بالعمر#

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

{
  "id": "verify",
  "name": "Verify age",
  "instructions": "Ask for the caller's age.",
  "tools": null,
  "collect": [
    {"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
  ],
  "transitions": [
    {"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
    {"to": "book", "when": "The caller has given their age"}
  ]
}

ينتقل المتصل الذي يقول خمسة عشر إلى guardian، مهما قرر النموذج. وينتقل الجميع الآخرون إلى book. كلاهما خطوتان عاديتان في موضع آخر من الرسم البياني.

مثال: خطوة خطاف ويب للبحث عن الحساب#

يقدّم المتصل رقم حساب، ويجري البحث عند الدخول إلى الخطوة التالية، وتحدد نتيجته المسار. حُذفت خطوات not_found وcollections وsupport للاختصار.

[
  {
    "id": "identify",
    "name": "Identify",
    "instructions": "Ask for the caller's account number and read it back digit by digit.",
    "tools": null,
    "collect": [
      {"name": "account_number", "type": "string", "description": "Account number", "required": true}
    ],
    "transitions": [
      {"to": "lookup", "when": "The caller has confirmed their account number"}
    ]
  },
  {
    "id": "lookup",
    "name": "Look up account",
    "instructions": "Tell the caller what you found on their account and ask how you can help.",
    "tools": ["lookup_account"],
    "collect": [],
    "on_enter_tool": "lookup_account",
    "transitions": [
      {"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
      {"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
      {"to": "support", "when": "The caller needs help with an active account"}
    ]
  }
]

يتلقى lookup_account قيمة account_number لأن مَعلمته تحمل هذا الاسم. إذا كان نص الاستجابة يحتوي على "found": false، تنتقل المكالمة إلى not_found. وإذا كانت قيمة account_status هي past_due أو suspended، فتنتقل إلى collections. يبقى الحساب النشط في lookup، حيث يساعد النموذج ثم ينتقل إلى support. لإرسال عملية بحث فاشلة إلى خطوتها الخاصة، أضف الشروط الخاصة بالحالة أولاً: تخزّن استجابة الخطأ رمز حالتها، لذا فإن {"value": "lookup_account_result.status", "op": "gte", "target": 400} يلتقطها، بينما يخزّن انتهاء المهلة أو عدم وجود إجابة القيمة "error"، لذا فإن {"value": "lookup_account_result.status", "op": "eq", "target": "error"} يلتقط ذلك.

مثال: من الاستقبال إلى الفوترة#

وكيلان. يجيب الاستقبال (الوكيل 412) عن كل مكالمة ويحوّل أسئلة الفوترة إلى وكيل فوترة (الوكيل 413) لديه موجّه وأدوات وصوت خاص به.

في الاستقبال:

{
  "handoffs": [
    {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
  ]
}

في وكيل الفوترة، ليتمكن من إعادة المتصل:

{
  "handoffs": [
    {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
  ]
}

يقول الاستقبال عبارة قصيرة مثل "دعني أوصلك بفريق الفوترة لدينا"، ويعرّف وكيل الفوترة بنفسه ويتابع المحادثة من حيث انتهى الاستقبال. عند إعادة التحويل من الفوترة، يستأنف الاستقبال من حيث كان، من دون تحية المتصل مرة أخرى. يبقى منتج المكالمة ولغاتها وإعلان الموافقة وإعدادات المكالمة الأخرى مع الاستقبال، لأنه هو من أجاب.

إذا كانت الفوترة تحتاج إلى تعليماتها الخاصة فقط، وليس إلى وكيل خاص بها، فاستخدم خطوة عامة في الاستقبال بدلاً من ذلك. عند الإجابة عن السؤال، تعود المكالمة إلى أي خطوة كان المتصل فيها:

{
  "id": "billing",
  "name": "Billing questions",
  "instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
  "tools": null,
  "collect": [],
  "transitions": [
    {"to": "__previous__", "when": "The billing question is answered"}
  ],
  "global_when": "The caller asks about a bill or payment at any point"
}

الخطوات التالية#