بناء تطبيقات وكيلة باستخدام AceDataCloud AI Chat v2

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

ذلك هو الفرق العملي وراء AceDataCloud AI Chat v2. تحافظ نقطة النهاية في POST https://api.acedata.cloud/aichat2/conversations على نمط الطلب البسيط لواجهة برمجة تطبيقات المحادثة الأصلية، مع إضافة كتل محتوى متعددة الوسائط، واستخدام أدوات مستقلة متعددة الجولات، واتصالات MCP، وأحداث بث منظمة، ومحادثات قابلة للاستئناف، وإجراءات CRUD للمحادثات.

بنية AI Chat v2: مدخلات متعددة الوسائط، وأدوات وكيل، وأحداث منظمة

يركز هذا الدليل على قرارات التكامل المهمة عند الانتقال من روبوت دردشة أساسي إلى تجربة وكيل للإنتاج.

ما الذي يتغير في AI Chat v2؟

يُعد AI Chat v2 ترقية شاملة لواجهة /aichat/conversations الأصلية. قدراته الرئيسية هي:

  • إدخال متعدد الوسائط: أرسل كتل text وimage_url وfile_url مرتبة ضمن مصفوفة message واحدة.
  • استخدام أدوات مستقل: يمكن للنموذج استدعاء الأدوات المضمنة وخوادم MCP المصرح بها من المستخدم عبر جولات متعددة.
  • بث محدد الأنواع: اعرض النص، ونشاط الأدوات، والاستشهادات، والبطاقات، والمخرجات، والأخطاء، وبيانات الإكمال كأحداث منفصلة.
  • إيقاف واستئناف: تعامل مع حدث ask_user_question وتابع المحادثة نفسها باستخدام نتيجة أداة.
  • إدارة المحادثات: استرجع، واسترجع على دفعات، وحدّث، واحذف عبر إجراءات على نقطة النهاية نفسها.
  • طلبات متوافقة مع الإصدارات السابقة: يمكن لعملاء model + question الحاليين الترحيل عبر تغيير مسار نقطة النهاية.

التحول المعماري المهم هو أن واجهتك الأمامية لم تعد مضطرة إلى التعامل مع الاستجابة كسلسلة نصية واحدة معتمة. يمكن أن تصبح مساحة عمل مدفوعة بالأحداث.

ابدأ بالمسار المتوافق مع الإصدارات السابقة

إن الترحيل الأقل خطورة صغير عمدًا. احتفظ بنص الطلب الحالي وغيّر نقطة النهاية فقط:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "Summarize the three most important points in this request.",
    "stateful": true
  }'

في وضع JSON، تحتفظ الاستجابة بالبنية المألوفة:

{
  "answer": "...",
  "id": "conversation-uuid"
}

احتفظ بالقيمة المعادة id. إن إرسالها في الطلب التالي يتابع المحادثة المُدارة دون أن يطلب من عميلك إعادة إرسال سجل الرسائل الكامل.

تكون القيمة الافتراضية لـ stateful هي true. اضبطها صراحةً على false عندما لا ينبغي تخزين جولة.

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

استخدم message عندما يكون الترتيب ونوع الوسائط مهمين

يكون الحقل question الأقدم مناسبًا للمطالبات النصية فقط. بالنسبة للنص المختلط بالصور أو الملفات، استخدم مصفوفة message مرتبة:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

كتل المحتوى المدعومة هي:

الكتلة القيمة المطلوبة أفضل استخدام
text text التعليمات، والسياق، والأسئلة
image_url image_url.url لقطات الشاشة، والمخططات، وصور المنتجات
file_url file_url.url ملفات PDF وCSV وTXT والملفات الأخرى

لا يزال AI Chat v2 يتعرف على مصفوفة references الأقدم. تُحوَّل امتدادات الصور إلى كتل صور، بينما تصبح عناوين URL الأخرى كتل ملفات. هذا التوافق مفيد أثناء الترحيل، لكن message هو العقد الأفضل على المدى الطويل عندما يكون ترتيب المحتوى مهمًا.

صمم العميل حول الأحداث، وليس الرموز فقط

اختر تنسيق الاستجابة باستخدام ترويسة accept:

العميل الترويسة التنسيق
واجهة المتصفح text/event-stream أحداث مرسلة من الخادم
Node أو Python أو CLI أو عامل application/x-ndjson حدث JSON واحد لكل سطر
طلب خلفي بسيط application/json كائن {answer, id} نهائي

يمكن لمستهلك Python بسيط لـ NDJSON تجميع النص مع الحفاظ على أنواع الأحداث الأخرى:

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "Research the topic, cite sources, and return a concise brief.",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers, stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []

    for raw_line in response.iter_lines():
        if not raw_line:
            continue

        event = json.loads(raw_line)
        event_type = event.get("type")

        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

ينبغي أن تعرّف واجهات الإنتاج عارضًا أو معالجًا لكل عائلة من الأحداث:

  • يحدّث text_delta منطقة الإجابة.
  • يدعم tool_use وtool_result حالات النشاط وعروض التدقيق.
  • يربط citation المصادر بالمخرجات ذات الصلة.
  • يعرض card معاينات منظمة.
  • يكشف artifact عن تسليم مُنشأ منفصل.
  • ينبغي التعامل مع thinking فقط عندما يكشفه النموذج المختار.
  • ينهي error الجولة الحالية أو يستعيدها.
  • يغلق done البث ويسجل استخدام الرموز بالإضافة إلى سبب الإنهاء.

إذا كانت واجهتك تحتاج فقط إلى الإجابة النهائية، فاجمع content من كل text_delta. وهذا يعادل answer المعاد في وضع JSON.

دع الوكيل يستخدم الأدوات — لكن اجعل النشاط مرئيًا

يكون استدعاء الأدوات مفعّلًا افتراضيًا. يمكن لـ AI Chat v2 استخدام قدرات مضمنة مثل البحث على الويب، واستخراج الصفحات، وقراءة الملفات. كما يمكنه تحميل اتصالات MCP المصرح بها من المستخدم مثل Google Drive وNotion وSlack وGitHub.

يكشف البث الحد الفاصل بوضوح:

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

اربط بين tool_use وtool_result بواسطة tool_id. يدعم ذلك مؤشرات التقدم، وقياسات زمن الاستجابة، ومعالجة الأخطاء، ومسار تدقيق قابل للقراءة للمشغّل.

استخدم max_turns لتقييد عدد جولات الأدوات المستقلة التي يمكن أن تحدث في طلب واحد. النطاق المقبول هو 1–500؛ والقيمة الافتراضية الموثقة هي 500. تقلل القيمة الأقل من التنفيذ مفتوح النهاية. يؤدي ضبط max_turns: 1 إلى فرض استجابة واحدة ومنع استدعاءات الأدوات.

نمط طرح عملي هو:

  1. ابدأ في وضع JSON دون أدوات في واجهة المنتج.
  2. أضف NDJSON أو SSE واعرض text_delta بالإضافة إلى done.
  3. أظهر نشاط الأدوات كمخطط زمني مطوي.
  4. أضف الاستشهادات وعرض المخرجات.
  5. اضبط max_turns مقصودًا بناءً على تعقيد المهمة وتحمّل التكلفة.
  6. فعّل الاتصالات القادرة على الكتابة فقط بعد مراجعة نموذج التأكيد الخاص بها.

تعامل مع الأسئلة كآلة حالات قابلة للاستئناف

يحتاج الوكيل أحيانًا إلى توضيح. في تلك الحالة، يمكن أن يصدر البث ask_user_question، وتدخل المحادثة في حالة awaiting_user_input.

ينبغي لعميلك:

  1. حفظ id وtool_id الخاصين بالمحادثة.
  2. عرض السؤال وخياراته.
  3. جمع استجابة المستخدم.
  4. إرسال طلب آخر باستخدام id المحادثة نفسها.
  5. إعادة الإجابة عبر tool_results لاستدعاء الأداة المعلق. هذا أكثر متانة من التظاهر بأن الوكيل يمكنه الإنهاء مع وجود معلومات مفقودة. كما أنه يجعل بوابات الموافقة ممكنة للإجراءات الحساسة.

افصل بين التنفيذ التفاعلي وغير المراقَب

بالنسبة إلى webhooks، ووظائف CI/CD، وأنظمة المراقبة، يعيد async: true معرّف مهمة بينما يستمر العمل. يمكن استرداد النتيجة لاحقًا أو تسليمها إلى عنوان URL لرد اتصال HTTP(S).

يجب أن يكون وصول الكتابة غير المراقَب صريحًا. يدعم AI Chat v2 allowed_skills وallowed_mcp_servers أو كائن unattended_policy مكافئ. القائمة الفارغة لا تخوّل أي قدرات. لا يتجاوز التفويض المسبق آلية الأمان الخاصة بالموصل؛ إذ يجب أن تظل المهارة التي لا تدعم التأكيد غير المراقَب تُجري تشغيلًا تجريبيًا أو ترفض الكتابة.

ذلك التمييز مهم: توفر الاتصال ليس هو نفسه الإذن بالتصرف دون حضور شخص.

قائمة التحقق للإنتاج

قبل إطلاق واجهة وكيلية، تحقّق من:

  • يتم تخزين بيانات اعتماد API من جانب الخادم، وليس في كود المتصفح أبدًا.
  • تأتي أسماء النماذج من قائمة النماذج المدعومة الحالية بدلًا من افتراضات مضمّنة في الكود.
  • يتحمل محلل التدفق أجزاء الشبكة الجزئية وأنواع الأحداث غير المعروفة.
  • يتم إقران أحداث الأدوات بواسطة tool_id ويتم تسجيل الأخطاء.
  • يتم تعيين max_turns عن قصد.
  • يتم عرض عناوين URL الخاصة بالاستشهادات والقطع الأثرية بأمان.
  • يحتفظ ask_user_question بحالة كافية للاستئناف لاحقًا.
  • تحتفظ الاتصالات القادرة على الكتابة بالتأكيد أو بتفويض غير مراقَب محدود النطاق.
  • تغذي done.usage وterminal_reason قابلية المراقبة.
  • تتوافق سياسات حذف المحادثات والاحتفاظ بها مع متطلبات منتجك.

أقصر طريق من روبوت محادثة إلى وكيل

لا يفرض AI Chat v2 إعادة كتابة كاملة. ابدأ بتغيير نقطة النهاية والاحتفاظ بنص الطلب الحالي لديك. ثم انتقل إلى كتل message متعددة الوسائط، واعتمد التدفق المنظم، واعرض تقدّم الأدوات، وأضف معالجة الإيقاف والاستئناف.

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

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