Artifacts

تتيح Artifacts للوكلاء إرسال محتوى منظّم وتفاعلي للمستخدمين عبر بروتوكول A2H (وكيل إلى إنسان، الإصدار 0.3). بدلاً من وصف نموذج بنص، ترسل نموذجاً فعلياً يمكن للمستخدم ملؤه.

إرسال Artifact

await agent.sendArtifact(conversationId, {
  artifact: {
    a2h: "0.3",
    subtype: "form",
    blocks: [
      {
        tag: "input",
        key: "name",
        variant: "text",
        label: "Project name",
        required: true,
      },
      {
        tag: "input",
        key: "description",
        variant: "textarea",
        label: "Description",
      },
      {
        tag: "action",
        key: "submit",
        label: "Create Project",
        variant: "primary",
      },
    ],
  },
  title: "New Project Form",
  summary: "Fill in the project details",
  forwardable: false,
});

تحديث Artifact

حدّث artifact مُرسل سابقاً ليعكس التقدم أو حالة جديدة:

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // Must be greater than the current revision
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

استقبال ردود المستخدم

عندما يتفاعل مستخدم مع artifact (يرسل نموذجاً، يضغط زراً)، يصل الرد عبر onEvent:

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values contains the form data submitted by the user
  }
});

أنواع الكتل

Artifacts تتكون من كتل. كل كتلة لها tag يحدد نوعها:

Tag	الوصف	مثال الاستخدام
input	إدخال نص، textarea، رقم، تاريخ	حقول النماذج
select	قائمة منسدلة أو اختيار راديو	قوائم خيارات
checkbox	تبديل منطقي	تأكيدات
action	زر (رئيسي، ثانوي، خطر)	إرسال، إلغاء، موافقة/رفض
text	نص عرض ثابت	تعليمات، أوصاف
status	مؤشر تقدم	أشرطة تقدم المهام
table	عرض بيانات جدولية	نتائج بحث، جداول بيانات
code	كود مُميّز الصياغة	مقتطفات أكواد
image	صورة مضمّنة	مخططات، رسوم بيانية
divider	فاصل مرئي	فواصل أقسام

الأنواع الفرعية لـ Artifact

النوع الفرعي	الغرض
form	جمع مدخلات المستخدم
status	عرض تقدم المهام
result	عرض المخرجات النهائية
error	عرض معلومات الأخطاء
table	عرض بيانات منظّمة
code	عرض أكواد مع تمييز الصياغة

الحدود

القيد	القيمة
الحد الأقصى للكتل لكل artifact	16
الحد الأقصى لحمولة A2H	64KB
الحد الأقصى للحمولة الكلية (مع التغليف)	200KB
الحد الأقصى للتحديثات لكل دورة حياة artifact	100
قابل لإعادة التوجيه افتراضياً	لا

ما يتعامل معه SDK

• تشفير حمولات artifact قبل الإرسال
• إنشاء نص معاينة للإشعارات
• التوجيه عبر WebSocket أو الرجوع إلى REST
• التحقق من بنية الحمولة

الخطوات التالية

• إرسال الرسائل — رسائل النص والوسائط
• البث — بث الردود في الوقت الحقيقي
• تفويضات البيانات — اطلب الوصول إلى بيانات المستخدم