وثائق Make Agent Fast

وصفات API

أتمتة مسارات العمل الكاملة للموقع والوكيل والمعرفة والنشر وإعداد التقارير.

نظرة سريعة

أتمتة مسارات العمل الكاملة للموقع والوكيل والمعرفة والنشر وإعداد التقارير.

مسار طلبات APIمفتاح محدد النطاق ← مورد بإصدار ← استجابة موقّعة

إنشاءالتأسيسنشر

تستخدم هذه الوصفات REST الخام، لذا تعمل قبل تثبيت SDK عام. اضبط MAF_API_KEY في بيئة الخادم، واستبدل المعرّفات بالقيم التي أعادتها الخطوات السابقة.

وصفة: إنشاء ونشر وكيل مستند إلى مصادر موثوقة#

أنشئ مفتاح API واحدًا بالصلاحيات sites:write وagents:write وknowledge:write. أضف sites:read إذا كانت الأتمتة تعرض المواقع أو تتحقق منها أيضًا.

1. إنشاء الموقع#

curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

الاستجابة الناجحة هي 201 Created، وتتضمن الموقع ضمن data، وتعيد مسار المورد القياسي في ترويسة Location. احفظ data.id باسم SITE_ID.

2. إعداد الوكيل وسياسة التضمين#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'

المصادر المسموح بها (origins) هي مصادر مطابقة تمامًا: المخطط (scheme) واسم المضيف ومنفذ اختياري. لا تُضمّن مسارًا ولا حرفًا بديلًا (wildcard) في النهاية.

3. إضافة مصدر معرفة نصي#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'

يجب أن يتراوح طول النص الملصوق بين 5 و200,000 حرف. يمكن لنقطة النهاية نفسها أيضًا الزحف إلى موقع ويب باستخدام { "url", "max_pages", "refresh_hours" } (بحد أقصى 40 لـ max_pages)، أو استيراد { "kind": "youtube" | "podcast" | "feed", "url" }؛ وتتطلب مصادر الوسائط هذه باقة Operate أو Scale، وتعيد 409 على باقة Launch. أما رفع الملفات فيبقى متاحًا في لوحة التحكم.

4. إضافة سؤال شائع منظَّم#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'

5. النشر#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'

يجب أن تحتوي الاستجابة على {"data":{"id":"...","status":"published"}}. افتح تضمينًا حقيقيًا واطرح سؤالًا تظهر إجابته في المصدر. يثبت النشر أن حالة الوكيل قد تغيّرت، لكنه لا يثبت أن جودة المصدر أو مصدر التضمين (origin) صحيحان.

وصفة: تصفّح العملاء المحتملين (Leads) صفحةً بعد صفحة بأمان#

استخدم مفتاحًا يملك الصلاحية leads:read. تعامل مع next_cursor على أنه قيمة معتمة (opaque) وقم بترميزه بصيغة URL.

const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);

لا تفكّ ترميز المؤشر (cursor) ولا تعدّله ولا تفرزه ولا تعِد استخدامه مع مجموعة بيانات مختلفة.

وصفة: تعطيل التضمين أثناء حادث#

استخدم الصلاحية agents:write وأبقِ مفتاح idempotency نفسه عبر إعادات المحاولة الناتجة عن مشكلات الشبكة:

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'

بعد نجاح الاستجابة، تحقق من أن أيقونة فتح المحادثة (launcher) لم تعد تعمل على مضيف مسموح به. أعد تفعيله بمفتاح جديد لحل الحادث بعد تصحيح مشكلة المصدر (origin) أو المحتوى أو بيانات الاعتماد.

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

استخدم مفتاحًا منفصلًا لكل خدمة ولكل بيئة.
احفظ معرّفات الموارد ومفاتيح idempotency قبل إرسال أي عملية تعديل.
حدّد مهلات للاتصال وللاستجابة.
التزم بـ Retry-After وضع حدًا أقصى لإعادات المحاولة.
سجّل اسم العملية ورمز حالة HTTP ومعرّف الطلب دون تسجيل الأسرار أو البيانات الشخصية.
اختبر على موقع غير إنتاجي قبل منح صلاحيات الكتابة للإنتاج.