المطورون / الوكلاء
عرض جولة اختبار
https://api.echonova.ai/v1/agents/{agentId}/test-runs/{testRunId}تعيد جولة اختبار واحدة للوكيل مع حالتها والمحادثة حتى الآن. يظل الاختبار المكتوب مسبقًا `running` إلى أن يُجاب عن كل رسالة، ثم يصبح `passed` أو `failed` أو `incomplete`. يحتاج المفتاح إلى النطاق `agents:read`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات المسار
معرّف الوكيل كما أعادته `GET /v1/agents`.
معرّف الاختبار كما أعادته `GET /v1/agents/{agentId}/test-runs`.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
معرّف الاختبار.
اختبار دردشة أو اختبار صوتي.
`running` أو `passed` أو `failed` أو `incomplete`: توقف الاختبار قبل الرد على كل الرسائل، أو لم يتحدث أحد.
وقت بدئها، بصيغة ISO 8601 للتاريخ والوقت.
وقت انتهائه؛ يغيب أثناء التشغيل.
متوسط زمن الرد بالمللي ثانية؛ يغيب حتى أول رد.
الوسيط لزمن الرد بالمللي ثانية.
المئين 95 لزمن الرد بالمللي ثانية.
عدد الأدوار التي استغرقها.
عدد استدعاءات الأدوات التي أجراها الوكيل.
عدد الأدوات المفعّلة للوكيل.
عدد الرسائل التي طُلب من اختبار مكتوب مسبقًا إرسالها؛ يغيب في الاختبارات الأخرى.
المحادثة حتى الآن، من الأقدم: رسائلك وردود الوكيل. تبقى فارغة حتى تصل أول جولة.
معرّف الرسالة.
`inbound` من العميل، و`outbound` من الوكيل.
من كتبها.
نص الرسالة.
وقت إرسالها، بصيغة ISO 8601 للتاريخ والوقت.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `agentId` أو `testRunId` ليست معرّفًا سداسي عشريًا من 24 حرفًا.
الحل. استخدم المعرّفين كما أعادتهما `GET /v1/agents` وطلب البدء تمامًا.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل من هذه البيئة.
متى يحدث. مساحة العمل المالكة للمفتاح ليس لها اشتراك.
الحل. راجع خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة أو تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `agents:read`. الوصول إلى الكلام وتذاكر أداة الموقع لا يمنحه هذا النطاق.
الحل. عدّل المفتاح وامنحه النطاق `agents:read`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك صلاحيتي عرض الوكلاء وإدارة واجهة المطورين معًا. يُفحص ذلك في كل طلب.
الحل. امنح ذلك العضو الصلاحيتين من جديد، أو أنشئ المفتاح بعضو يملكهما.
متى يحدث. معرّف الوكيل غير معروف، أو الوكيل يتبع مساحة عمل أخرى.
الحل. استخدم معرّفًا من `GET /v1/agents` بمفتاح من مساحة عمل الوكيل.
متى يحدث. معرّف الاختبار غير معروف، أو يتبع وكيلًا آخر، أو أن الوكيل يخص مساحة عمل أخرى.
الحل. استخدم المعرّف الذي أعادته مكالمة البدء، مع معرّف الوكيل نفسه.
متى يحدث. أرسل المفتاح أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أرسل عنوان IP واحد أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يردّ بلا مفتاح أصلًا)؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl "https://api.echonova.ai/v1/agents/{agentId}/test-runs/{testRunId}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"id": "6655a1b2c3d4e5f6a7b8c9d0",
"kind": "chat",
"status": "passed",
"startedAt": "2026-11-03T10:00:00.000Z",
"endedAt": "2026-11-03T10:01:00.000Z",
"latencyMs": 800,
"replyP50Ms": 700,
"replyP95Ms": 1200,
"turns": 4,
"toolsTriggered": 1,
"toolsTotal": 2,
"plannedTurns": 2,
"messages": [
{
"id": "6652a1b2c3d4e5f6a7b8c9d0",
"direction": "inbound",
"sender": "customer",
"text": "How much is the Pro plan?",
"createdAt": "2026-11-02T10:00:01.000Z"
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}