واجهة برمجة تطبيقات دردشة التدفق الحواري

نظرة عامة

تعرض التدفقات الحوارية المنشورة واجهة برمجة تطبيقات لجلسة الدردشة على عنوان URL الخاص بالأتمتة. بدلًا من تشغيل /kickoff واحد، تنشئ جلسة، وترسل رسائل المستخدم كأدوار (turns)، ويمكنك اختياريًا بث الرموز والأحداث أثناء التشغيل، واستئناف توقفات HITL عندما يحتاج الدور إلى ملاحظات بشرية.

دردشة التدفق الحواري تجريبية. تتوفر نقاط النهاية فقط عندما يُبلغ التدفق المنشور عن conversational: true وhandle_turn: true من GET /inspect.

لبناء التدفق نفسه (conversational = True وhandle_turn والموجّهات والتتبع)، راجع دليل المصادر المفتوحة Conversational Flows.

المتطلبات الأساسية

انشر أتمتة Flow تنفّذ الأدوار الحوارية (handle_turn).
انسخ رمز Bearer من علامة تبويب Status للأتمتة (نفس الرمز المستخدم مع /kickoff).
أكّد تفعيل الدردشة عبر /inspect (أدناه).

تستخدم جميع الطلبات:

Authorization: Bearer YOUR_FLOW_TOKEN

تستخدم أمثلة هذا الدليل القاعدة https://your-flow-url.crewai.com.

اكتشاف قدرة الدردشة

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect

ابحث عن flow.chat:

{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}

إذا كانت أي من العلامتين false، تُرجع نقاط نهاية الدردشة 404 مع "Conversational flow chat is not available".

حلقة الدردشة من البداية للنهاية

بدء جلسة

أنشئ جلسة دردشة. يمكنك اختياريًا تسجيل webhook لانتهاء الدور وwebhooks للأحداث طوال عمر الجلسة.

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
    "webhooks": {
      "url": "https://your-server.com/webhooks/events",
      "events": ["*"],
      "realtime": false,
      "authentication": {
        "strategy": "bearer",
        "token": "my-secret-token"
      }
    }
  }' \
  https://your-flow-url.crewai.com/chat/start

الاستجابة:

{ "session_id": "11111111-2222-3333-4444-555555555555" }

الجسم الفارغ ({} أو بدون جسم) صالح عندما لا تحتاج إلى webhooks.

إرسال رسالة مستخدم

ضع دورًا واحدًا في قائمة الانتظار للجلسة:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is my order?",
    "stream": true
  }' \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message

الاستجابة:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "queued"
}

الحقل	الوصف
`message`	مطلوب. سطر المستخدم الحالي لهذا الدور.
`stream`	الافتراضي `true`. عند `true` تُنشر إطارات الرمز/الحدث لعملاء WebSocket/SSE.
`messageHistory`	نص احتياطي اختياري (`[{ "role", "content" }, ...]`). سجل الجلسة على الخادم هو المرجع؛ يُستخدم هذا فقط عندما يكون السجل المخزّن فارغًا.

الأدوار المقبولة في messageHistory: user وassistant وsystem وtool.

انتظار انتهاء الدور

راقب الدور باستخدام kickoff_id المُعاد (نفس واجهة حالة kickoff العادية للتدفق):

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

يمكن أن يكون دور واحد فقط نشطًا لكل جلسة. طلب /message ثانٍ أثناء تعيين active_kickoff_id يُرجع 409:

{
  "detail": {
    "code": "session_busy",
    "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

انتظر حتى يُظهر السجل active_kickoff_id: null (أو يصل الدور إلى حالة نهائية / توقف) قبل إرسال الرسالة التالية.

قراءة سجل الجلسة

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "messages": [
    { "role": "user", "content": "Where is my order?" },
    { "role": "assistant", "content": "Your order is on the way." }
  ],
  "active_kickoff_id": null
}

بث دور

البث اختياري. استخدمه عندما تحتاج الواجهة إلى رموز أو أحداث runtime أثناء تشغيل الدور. تتضمن الإطارات دائمًا أنواع دورة الحياة (turn_started وturn_completed وturn_failed وtoken وerror). يمكن تصفية إطارات event الإضافية بمعلمة الاستعلام events (* أو قائمة مفصولة بفواصل).

الخيار أ: رسالة HTTP + إرفاق SSE

POST /chat/{session_id}/message مع "stream": true.
اربط بالدور النشط:

curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"

يُرجع SSE إطارات JSON من نوع text/event-stream (data: {...}) مع تعليقات keepalive. ينتهي البث عند turn_completed أو turn_failed. إذا لم يكن هناك دور نشط، تُرجع هذه النقطة 409 (No active chat turn).

الخيار ب: WebSocket (إرفاق أو إرسال)

wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0

المصادقة: مرّر رمز Bearer كمعامل استعلام token، أو كترويسة Authorization: Bearer ... عندما يدعم عميلك ترويسات WebSocket. السلوك:

دور نشط قيد التشغيل بالفعل — يتصل المقبس ويُرسل أولًا turn_started مع data.status: "attached"، ثم يبث الإطارات حتى نوع نهائي.
لا يوجد دور نشط — أرسل رسالة JSON لوضع دور في قائمة الانتظار ثم استهلك البث:

{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}

يستجيب الخادم بـ turn_started (status: "queued") ثم إطارات البث لذلك kickoff_id. استخدم last_event_id / lastEventId للاستئناف بعد انقطاع الاتصال.

أمثلة على إطارات البث

{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}

{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}

{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}

HITL داخل جلسة دردشة

إذا توقف دور لانتظار ملاحظات بشرية (status / الحالة PAUSED)، استأنفه بنفس نقطة استئناف Flow المستخدمة في التشغيلات غير الحوارية:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback

ثم راقب kickoff_id الخاص بالاستئناف من الاستجابة. انتظر حتى يُظهر /history القيمة active_kickoff_id: null قبل إرسال رسالة الدردشة التالية. راجع سير عمل HITL وإدارة HITL للتدفقات لواجهة المراجعة على المنصة.

مرجع واجهة البرمجة

الطريقة	المسار	الغرض
`GET`	`/inspect`	اكتشاف ما إذا كانت الدردشة الحوارية مفعّلة
`POST`	`/chat/start`	إنشاء جلسة دردشة
`POST`	`/chat/{session_id}/message`	وضع دور مستخدم في قائمة الانتظار
`GET`	`/chat/{session_id}/history`	قراءة الرسائل ومعرّف الدور النشط
`GET`	`/chat/{session_id}/stream/events`	بث SSE للدور النشط
`WS`	`/chat/{session_id}/stream`	بث WebSocket (إرفاق أو إرسال + بث)
`GET`	`/status/{kickoff_id}`	مراقبة حالة تنفيذ الدور (أو الاستئناف)
`POST`	`/resume_feedback`	استئناف دور HITL متوقف

أخطاء شائعة

الحالة	متى
`400`	`message` فارغ
`404`	الدردشة غير مفعّلة على هذا النشر، أو `session_id` غير معروف
`409`	الجلسة لديها دور نشط بالفعل (`session_busy`)، أو إرفاق SSE بدون دور نشط
`422`	`session_id` ليس UUID صالحًا
`503`	تخزين جلسة الدردشة أو البث غير متاح

Conversational Flows

ابنِ تدفقات متعددة الأدوار باستخدام handle_turn والموجّهات والتتبع.

Kickoff Crew / Flow

تشغيل kickoff واحد ومراقبة الحالة على عنوان URL للنشر.

Webhook Streaming

شكل حمولة webhook للأحداث وخيارات المصادقة.

إدارة HITL للتدفقات

مراجعة بشرية بالبريد الإلكتروني أولًا لخطوات التدفق المتوقفة.

البدء

البناء

العمليات

الإدارة

التكاملات

How-To Guides

المشغّلات

موارد التعلّم

واجهة برمجة تطبيقات دردشة التدفق الحواري

نظرة عامة

المتطلبات الأساسية

اكتشاف قدرة الدردشة

حلقة الدردشة من البداية للنهاية

بث دور

الخيار أ: رسالة HTTP + إرفاق SSE

الخيار ب: WebSocket (إرفاق أو إرسال)

أمثلة على إطارات البث

HITL داخل جلسة دردشة

مرجع واجهة البرمجة

أخطاء شائعة

ذات صلة

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

إدارة HITL للتدفقات

​نظرة عامة

​المتطلبات الأساسية

​اكتشاف قدرة الدردشة

​حلقة الدردشة من البداية للنهاية

​بث دور

​الخيار أ: رسالة HTTP + إرفاق SSE

​الخيار ب: WebSocket (إرفاق أو إرسال)

​أمثلة على إطارات البث

​HITL داخل جلسة دردشة

​مرجع واجهة البرمجة

​أخطاء شائعة

​ذات صلة

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

إدارة HITL للتدفقات

نظرة عامة

المتطلبات الأساسية

اكتشاف قدرة الدردشة

حلقة الدردشة من البداية للنهاية

بث دور

الخيار أ: رسالة HTTP + إرفاق SSE

الخيار ب: WebSocket (إرفاق أو إرسال)

أمثلة على إطارات البث

HITL داخل جلسة دردشة

مرجع واجهة البرمجة

أخطاء شائعة

ذات صلة