المطورون / الوكلاء
إنشاء وكيل
https://api.echonova.ai/v1/agentsتُنشئ وكيلًا نشطًا في مساحة العمل الخاصة بهذا المفتاح، باسم وتعليمات و1 إلى 4 أصوات ونموذج لغة. ليس للوكيل قناة بعد، لذلك لا يستقبل مكالمات حتى تربطه بقناة. أرسل `Idempotency-Key` لإعادة المحاولة بأمان. مجانًا. يحتاج المفتاح إلى النطاق `agents:write`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
اختياري. كرّر المفتاح نفسه خلال 24 ساعة لإعادة المحاولة بأمان: تعود النتيجة الأولى، ولا يُنشأ شيء مرتين. الطلب الجديد يحتاج إلى مفتاح جديد.
متن الطلب
application/json
اسم الوكيل.
الغرض من الوكيل.
التعليمات التي يتبعها الوكيل في كل محادثة.
ما يقوله الوكيل أولًا عند بدء المحادثة.
الأصوات التي يتحدث بها الوكيل، من 1 إلى 4.
معرّف نموذج من `GET /v1/llm/models`.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
معرّف الوكيل.
اسم الوكيل.
الغرض من الوكيل، أو `null`.
`active`، أو `archived` بعد حذفه من البوابة.
الصوت الافتراضي للوكيل، أو `null` إن لم يكن له صوت.
معرّف الصوت كما يعرضه `GET /v1/text-to-speech/voices`.
اسم الصوت بالإنجليزية، أو `null` إن لم يعد الصوت متاحًا.
لهجة الصوت الافتراضي، أو `null`.
نموذج اللغة الذي يفكّر به الوكيل.
الجهة التي تقدّم نموذج اللغة.
معرّف النموذج. مرّره كقيمة لـ `model` في `GET /v1/llm/estimate` لمعرفة سعره.
عدد القنوات المتصل بها الوكيل.
عدد المحادثات التي أجراها الوكيل.
وقت آخر تعديل على الوكيل، بصيغة ISO 8601 للتاريخ والوقت.
ما يقوله الوكيل أولًا، أو `null` إذا كان المتصل يتكلم أولًا.
تعليمات الوكيل.
إعدادات المكالمة.
هل تُسجَّل المكالمات الصوتية.
هل تُنطق الأرقام والتواريخ والمبالغ كما تنطقها اللهجة.
عدد مجلدات قاعدة المعرفة ومصادرها التي يستخدمها الوكيل.
عدد أدوات مساحة العمل المرفقة بالوكيل.
وقت إنشاء الوكيل بصيغة ISO 8601 للتاريخ والوقت.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `name` أطول من 100 حرف.
الحل. أرسل اسمًا أقصر.
متى يحدث. قيمة `name` نص فارغ.
الحل. أرسل اسمًا، أو احذف الحقل حيثما كان اختياريًا.
متى يحدث. قيمة `description` أطول من 500 حرف.
الحل. أرسل وصفًا أقصر.
متى يحدث. قيمة `systemPrompt` أطول من 8000 حرف.
الحل. اختصر التعليمات؛ النصوص المرجعية الطويلة تُضاف إلى قاعدة المعرفة.
متى يحدث. قيمة `firstMessage` أطول من 500 حرف.
الحل. أرسل رسالة افتتاحية أقصر.
متى يحدث. قيمة `voices` قائمة فارغة.
الحل. أرسل من 1 إلى 4 أصوات.
متى يحدث. قائمة `voices` تحتوي على أكثر من 4 أصوات.
الحل. أرسل من 1 إلى 4 أصوات.
متى يحدث. قيمة `voiceId` ليست معرّفًا سداسي عشريًا من 24 حرفًا؛ تذكر الرسالة موضعه في `voices`.
الحل. استخدم معرّفًا من `GET /v1/agent-voices`.
متى يحدث. لغة الصوت ليست `ar` أو `en`؛ تذكر الرسالة موضعه في `voices`.
الحل. أرسل `ar` أو `en`.
متى يحدث. قيمة `llmModel` أطول من 100 حرف.
الحل. أرسل معرّف نموذج من `GET /v1/llm/models`.
متى يحدث. قيمة `voiceId` الجديدة تشير إلى صوت تم سحبه.
الحل. اختر صوتًا آخر من `GET /v1/agent-voices`.
متى يحدث. قائمة `voices` تكرر `voiceId` نفسه مرتين؛ تذكر الرسالة المعرّف.
الحل. اذكر كل صوت مرة واحدة.
متى يحدث. أكثر من صوت واحد قيمة `isDefault` فيه `true`.
الحل. اجعل صوتًا واحدًا على الأكثر افتراضيًا.
متى يحدث. قيمة `llmModel` ليست نموذجًا تستطيع مساحة العمل استخدامه.
الحل. استخدم معرّف نموذج من `GET /v1/llm/models`.
متى يحدث. قيمة `llmModel` غير موجودة عند الإنشاء، فتفشل كل قواعد الحقل معًا.
الحل. أرسل معرّف نموذج من `GET /v1/llm/models`.
متى يحدث. مساحة العمل بلغت عدد الوكلاء النشطين الذي تسمح به خطتها. الإنشاء والنسخ والاستعادة تتحقق من ذلك.
الحل. أرشِف وكيلًا عبر `POST /v1/agents/{agentId}/archive`، أو رقِّ الخطة.
متى يحدث. ترويسة `Idempotency-Key` أطول من 200 حرف، أو تحتوي على مسافة أو على حرف خارج ASCII القابل للطباعة.
الحل. أرسل من 1 إلى 200 حرف ASCII قابل للطباعة، مثل UUID.
متى يحدث. الجسم أو معلمات الاستعلام تحتوي على حقل لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل من هذه البيئة.
متى يحدث. مساحة العمل المالكة للمفتاح ليس لها اشتراك.
الحل. راجع خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة أو تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `agents:write`.
الحل. عدّل المفتاح وامنحه النطاق `agents:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك صلاحيتي إدارة الوكلاء وإدارة واجهة المطورين معًا. يُفحص ذلك في كل طلب.
الحل. امنح ذلك العضو الصلاحيتين من جديد، أو أنشئ المفتاح بعضو يملكهما.
متى يحدث. قيمة `voiceId` غير معروفة، أو هي صوت مستنسخ من مساحة عمل أخرى.
الحل. استخدم معرّفًا من `GET /v1/agent-voices`.
متى يحدث. أرسل هذا المفتاح `Idempotency-Key` نفسه خلال آخر 24 ساعة، مع جسم طلب مختلف أو وكيل مختلف.
الحل. استخدم `Idempotency-Key` جديدًا لطلب جديد.
متى يحدث. الطلب الأول بهذا `Idempotency-Key` لم ينتهِ بعد.
الحل. انتظر قليلًا، ثم أعد المحاولة بالمفتاح نفسه لتحصل على نتيجته.
متى يحدث. جسم JSON لكتابة الوكيل أكبر من 512 كيلوبايت؛ يُرفض الطلب قبل فحص مفتاح الواجهة، لذلك لا يظهر له سجل في النشاط.
الحل. أرسل جسمًا أصغر، وقسّم النص الطويل في قاعدة المعرفة إلى عدة مصادر.
متى يحدث. للطلب جسم، وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أرسل عنوان IP واحد أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يردّ بلا مفتاح أصلًا)؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl -X POST "https://api.echonova.ai/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Sales assistant","systemPrompt":"You are a friendly sales assistant. Answer in the caller language.","voices":"string","llmModel":"gpt-4o"}'{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Sales assistant",
"description": "Answers questions about plans and prices.",
"status": "active",
"voice": {
"id": "6640a1b2c3d4e5f6a7b8c9d0",
"name": "Huda"
},
"dialect": "emirati",
"llm": {
"provider": "openai",
"model": "gpt-4o"
},
"channelsCount": 2,
"sessionsCount": 128,
"updatedAt": "2026-11-01T10:00:00.000Z",
"firstMessage": "Hello, how can I help you today?",
"systemPrompt": "You are a friendly sales assistant for EchoNova.",
"settings": {
"recordCalls": true,
"normalizeNumbers": true
},
"knowledgeCount": 3,
"toolsCount": 2,
"createdAt": "2026-10-01T10:00:00.000Z"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}