المواصفات · agent.v1 / agent.v2

تتيح أداة .agent تنسيق الملفات

يجمع ملف JSON واحد كل ما تحتاجه بيئة التشغيل لتنفيذ وكيل ذكاء اصطناعي. يعمل الملف نفسه في السحابة أو على حاسوبك أو من نص برمجي لسطر الأوامر. لا يحتوي الملف على أسرار مطلقًا؛ بل يعلن بيانات الاعتماد التي يحتاجها الوكيل وتطلبها بيئة التشغيل من المستخدم.

Registered IANA media typeapplication/vnd.agentmug.agent+json

المخطط

يتوفر مخطط JSON المعتمد على رابط ثابت، ويمكن لأدوات التحقق والتحليل والمحررات جلبه مباشرةً.

https://agentmug.com/schemas/agent.v1.json
https://agentmug.com/schemas/agent.v2.json

The written specification, referenced by the IANA registration:

https://agentmug.com/spec/agent-v1.md
https://agentmug.com/spec/agent-v2.md

كل ملف .agent يشير إلى هذا الرابط في حقل $schema . وتظل الملفات التي تشير إلى رابط agentlit.dahshanlabs.com يظل الرابط صالحًا للتحقق. والتوافق مع الإصدارات السابقة دائم.

يظل v1 خاليًا من الشيفرة دائمًا. ولا يُستخدم v2 إلا عندما يحمل العامل حزمة قدرة تنفيذية صريحة مثبّتة بملخص تشفيري. ترفض المضيفات القديمة v2 وفق علامة المخطط؛ وتعزل المضيفات الحالية كل حزمة حتى تتحقق منها بصورة مستقلة وتوفّر بيئة معزولة بلا شبكة.

محتويات الملف

الهوية: المعرّف والاسم والوصف والإصدار ووقت التصدير. تبقى عند النسخ.
مخطط العمل: النموذج الأساسي وموجه النظام الكامل وقائمة الأدوات المسموح للوكيل باستخدامها.
الأدوات: four kinds: builtin (تُنفّذ مباشرةً داخل بيئة التشغيل)، mcp (تُفوّض إلى خادم MCP باستخدام بيانات اعتماد المستخدم)، و webhook (arbitrary HTTP), and nango (a third-party API called through a credential broker that injects the user's OAuth token). Tools that need user OAuth declare it upfront. The runtime renders a Connect button if one is missing.
المدخلات والمخرجات: تعلن الأنماط (نص / صوت / صورة) وبنية المخرج (نص / json / دون قيمة). تستخدم بيئات التشغيل ذلك لعرض الواجهة المناسبة.
المشغّلات: يدوي أو مجدول (cron) أو webhook أو API. تُظهر بيئة التشغيل خطأ واضحًا إذا تعذر عليها تنفيذ المشغّل المعلن.
الاتصالات: الهويات والمصادر وقنوات التسليم المطلوبة لعمل الوكيل. يحتوي العقد على الأدوار والمراجع، ولا يحتوي مطلقًا على بيانات اعتماد أو أرقام هواتف فعلية.

مثال

{
  "$schema": "https://agentmug.com/schemas/agent.v1.json",
  "id": "agent_morning_brief_01",
  "name": "Morning Brief",
  "description": "Reads overnight Outlook messages and sends a 5-bullet summary to WhatsApp every weekday at 7am.",
  "version": "1.0.0",
  "exportedAt": "2026-05-19T07:00:00Z",
  "blueprint": {
    "primaryModel": "claude-sonnet-4-6",
    "systemPrompt": "You are a morning briefing assistant ...",
    "tools": [
      "nango:outlook:list_messages",
      "twilio.send_whatsapp"
    ]
  },
  "inputs": { "accepts": ["text"] },
  "outputs": { "shape": "void", "description": "Sends the brief silently via WhatsApp." },
  "triggers": [
    {
      "type": "schedule",
      "cron": "0 7 * * 1-5",
      "prompt": "Send my morning brief.",
      "timezone": "Asia/Riyadh",
      "label": "Weekday morning brief"
    }
  ],
  "connectivity": {
    "identities": [{ "role": "owner", "channel": "phone" }],
    "reads": [{ "provider": "microsoft-outlook", "resource": "outlook-inbox" }],
    "delivers": [
      { "channel": "whatsapp", "to": "owner", "via": "twilio.send_whatsapp" }
    ]
  }
}

ملاحظات التنفيذ

تتوفر اليوم ثلاث بيئات تشغيل، وجميعها تحمّل ملف .agent نفسه:

  • السحابة: بيئة التشغيل المستضافة على agentmug.com. تُحفظ الرموز على بنية AgentMug التحتية.
  • سطح المكتب: غلاف Tauri لأنظمة macOS وWindows وLinux. تبقى الرموز على حاسوب المستخدم.
  • CLI: agentmug run my.agent . استدعه من مهام cron أو CI أو وكلاء أخرى.

بيئة التشغيل المرجعية منشورة على npm. ويجري إعداد مستودع مصدرها المرخص بـ Apache-2.0 للنشر العام. نرحب ببيئات التشغيل المخصصة. نفّذ المخطط أعلاه لتتمكن من تشغيل كل وكيل متوافق في السوق.

إدارة الإصدارات

تتيح أداة $schema هو علامة الإصدار. ويصدر أي تغيير غير متوافق في التنسيق عبر رابط جديد (agent.v2.json)؛ تقبل بيئات التشغيل الإصدارات التي تعرفها وترفض غيرها برسالة خطأ محددة. الإصدار v1 هو الإصدار المنشور الوحيد حاليًا.