عامل الذكاء الاصطناعي القابل للنقل runtime

ثلاث حزم منشورة—اختر منها ما يناسب بنية مشروعك.

# Embed the runtime in your own app
npm install @agentmug/runtime

# Use the CLI (humans + agent-driven)
npm install -g @agentmug/cli

# Expose AgentMug agents to Claude Code / Cursor (configured, not installed)
# See "Use from Claude Code / Cursor" below

هذا هو الحد الأدنى في 10 أسطر: مرّر ملف .agent بعد تحليله، مع تعليمة ومفتاح Anthropic. quickRun يوصل محوّلات تعمل في الذاكرة، فلا تحتاج إلى قاعدة بيانات للبدء.

import { quickRun, parseAgentFile } from "@agentmug/runtime";
import { readFileSync } from "node:fs";

const agentFile = parseAgentFile(JSON.parse(readFileSync("./hello.agent", "utf8")));

const result = await quickRun({
  agentFile,
  userInput: "Say hi in 5 words.",
  llm: { anthropicApiKey: process.env.ANTHROPIC_API_KEY! },
  onEvent: (e) => e.type === "token" && process.stdout.write(e.content),
});

console.log("\n→", result.totalTokens, "tokens");

تجد نسخة كاملة قابلة للتشغيل في examples/hello-agent.

A .agent هو مستند JSON تصريحي يضم الاسم والوصف وتعليمة النظام والنموذج وقائمة الأدوات وأشكال الإدخال والإخراج والمعاملات. قابل للنقل وإدارة الإصدارات والنسخ.

{
  "$schema": "https://agentmug.com/schemas/agent.v1.json",
  "id": "email-triage",
  "name": "Email Triage",
  "description": "Sorts unread Gmail and drafts replies.",
  "blueprint": {
    "primaryModel": "claude-sonnet-4-6",
    "systemPrompt": "You triage emails...",
    "tools": ["gmail.send", "memory.save", "ask_user"]
  },
  "parameters": [{
    "name": "source_file_1",
    "label": "Source table 1",
    "type": "file",
    "required": true,
    "artifact": {
      "kind": "table",
      "accepts": [".csv", ".xlsx"],
      "structure": ["Sheet \"Invoices\" columns: invoice_id, amount, due_date"]
    }
  }],
  "inputs": { "accepts": ["text"] },
  "outputs": { "shape": "text" }
}

حمّل الملف وتحقق منه باستخدام parseAgentFile(json). ثم مرّر النتيجة إلى quickRun() أو runAgent().

A type: "file" يحمل المعامل عقد صيغة وبنية خاليًا من الأسرار فقط. يربط كل مضيف البديل الخاص بمالكه ويمكنه استدعاء checkArtifactCompatibility(parameter, candidate) قبل استيعاب أي شيء. لا مكان لأسماء الملفات أو الصفوف أو النصوص أو بيانات الصور أو بيانات الاعتماد أو الذكريات أو القيم المرتبطة في ملف مشترك.

راجع صفحة المواصفة للاطلاع على المخطط المرجعي الكامل بجميع الحقول الاختيارية.

يعلن عقد المصدر عن الأدلة التي يحتاجها الوكيل. يحمل .agent ذلك المتطلب الخالي من الأسرار؛ ويربط كل مالك بشكل خاص ملفه أو مجلده أو عنصر المزوّد أو لقطة الذاكرة المحفوظة ويتحقق منها قبل أن يتمكن الوكيل من العمل.

عندما ترفق ملف .klypix في أداة البناء على الويب، ينشئ AgentMug استنادًا واعيًا بالتصحيحات من تلك اللقطة المحفوظة. ويستبعد سجل الأرشيف والبطاقات التي عكستها حواف دورة الحياة المحفوظة أو طبقة تصحيح KLYPIX صالحة. تفشل الإسقاطات غير المكتملة في وضع آمن مغلق.

يحسب المتصفح الموثق بصمة محتوى الملف المحدد بدقة؛ ويصف الإيصال تلك المراجعة الخام بأنها عميل المالك. تحسب سحابة AgentMug بشكل مستقل بصمة إسقاط البطاقات الحالية المفهرس، لكنها لا ترفع محتوى الأرشيف الأصلي أو تعيد تحليله. يسجّل الإيصال تصديق مراجعة الملف الخام وملخص الأدلة، إضافة إلى معرّفات البطاقات ووقت القراءة الفعلي.

للاستناد إلى الأدلة فقط — وليس للتنسيق. ارتباط لقطة KLYPIX لا يستدعي أو ينضم إلى brain_sync للتنسيق أو حضور النظراء أو الرسائل أو اكتشاف تداخل الملفات. لا يؤدي حفظ الذاكرة الأصلية مجددًا إلى تحديث المرفق؛ أرفق المراجعة المحفوظة الجديدة وتحقق منها.

الاستناد إلى الأدلة خاص وليس محليًا فقط: يُرسل محتوى البطاقات المحددة ومعرّفاتها وأدلة المراجعة إلى معالجات التضمين أو النماذج المضبوطة في AgentMug من أجل التشغيل. ولا تُضاف إلى الملف القابل للمشاركة .agent ولا تُكشف كبيانات مصدر عامة.

بالنسبة لهذا المصدر، قديم تعني أن مراجعة اللقطة أو الملف ابتعدت عن تثبيت التحقق، أو أن التحقق انتهت صلاحيته، قبل أول طلب إلى النموذج. ولا تعني أن البطاقة قديمة، ولا تُستمد من brain_doctor.

لا تفترض بيئة التشغيل شيئًا عن مكان عملها. كل ما يتصل بالعالم الخارجي يمر عبر محوّل تقدمه إلى runAgent():

استبدل أي طبقة؛ فالمحرك يتعامل معها جميعًا عبر الواجهة نفسها.

الأدوات فئات عادية تطبّق الواجهة ToolExecutor. سجّلها في InMemoryToolRegistry ثم مرّرها إلى runAgent() أو quickRun().

import {
  InMemoryToolRegistry,
  gmailSendDefinition,
} from "@agentmug/runtime";

const tools = new InMemoryToolRegistry();
tools.register(gmailSendDefinition, new YourGmailExecutor());

تتضمن بيئة التشغيل تعريفات الأدوات المدمجة لإرسال Gmail وإنشاء أحداث التقويم وإرسال Slack وإنشاء مشكلات GitHub وتنفيذ الشفرة والبحث والتصفح على الويب وweb.fetch_json لطلبات HTTP العامة وask_user للإيقاف والاستئناف وحفظ الذاكرة واستدعائها ونسيانها وimage.generate وinvoke_agent وcreate_reminder وshell.execute على سطح المكتب واستيراد المهارات.

تتيح أداة web.fetch_json تحويل أي واجهة HTTP API إلى قدرة من دون كتابة منفّذ مخصص. راجع examples/web-research.

Enabled cloud schedules are accepted only when AgentMug can confirm its Redis producer and at least one fleet scheduler worker are ready. Disabled drafts can still be saved, but remain visibly paused instead of appearing active and silently missing their run.

يمكن لحزم npm الخارجية تقديم مجموعات متكاملة من الأدوات والمحوّلات عبر واجهة الإضافات. definePlugin() ينشئ الحزمة، بينما registry.loadPlugin() يوصلها ببيئة التشغيل.

// In your plugin package — e.g. @agentmug-plugins/hackernews
import { definePlugin } from "@agentmug/runtime";

export default definePlugin({
  name: "hackernews",
  version: "1.0.0",
  tools: [
    {
      definition: hnSearchDefinition,
      executor: new HnSearchExecutor(),
    },
  ],
});

// In the consumer
import { InMemoryToolRegistry } from "@agentmug/runtime";
import hnPlugin from "@agentmug-plugins/hackernews";

const tools = new InMemoryToolRegistry();
tools.loadPlugin(hnPlugin);
// every tool the plugin defines is now registered

يمكن للإضافات أيضًا توفير تطبيقات للمحوّلات (مثل تطبيق مخصص لـ LlmClient, PersistenceAdapter, TracingAdapter) — راجع حزمة محوّل OpenTelemetry أدناه كمثال مرجعي.

@agentmug/otel توفّر محوّل TracingAdapter يُصدر امتدادات لاستدعاءات النماذج والنسخ الصوتي إلى مسار OTel الحالي لديك، مثل Honeycomb وDatadog وTempo وJaeger وSentry وأي نظام يستهلك OpenTelemetry.

npm install @agentmug/otel @opentelemetry/api

import { runAgent, noSourcePlan } from "@agentmug/runtime";
import { OtelTracingAdapter } from "@agentmug/otel";

const result = await runAgent({
  agentId: "...", userId: "...", userInput: "...",
  adapters: {
    persistence: yourPersistence,
    llm: yourLlmClient,
    tracing: new OtelTracingAdapter(),   // ← that's it
  },
  onEvent: () => {},
});

يتحول كل استدعاء لنموذج لغوي إلى امتداد بخصائص مثل agentmug.llm.provider, agentmug.llm.model, agentmug.llm.tokens, agentmug.llm.cost_cents, agentmug.llm.latency_ms. أوصل حزمة OTel SDK والمُصدّر بالطريقة المعتادة لتظهر التشغيلات في لوحات الرصد لديك.

@agentmug/mcp-bridge يتيح أي عامل، سواء كان مستضافًا على agentmug.com أو في واجهتك الخلفية، كخادم Model Context Protocol. أضفه إلى إعداد عميل MCP:

{
  "mcpServers": {
    "email-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "@agentmug/mcp-bridge",
        "https://agentmug.com/api/external/agents/<AGENT_ID>"
      ],
      "env": { "AGENTMUG_API_KEY": "am_agent_..." }
    }
  }
}

أنشئ معرّف العامل ومفتاح API من تبويب النشر ← الوصول الخارجي . يعمل مع Claude Desktop وClaude Code وCursor في وضع الأوامر وContinue وCline.

تتيح أداة agentmug واجهة الأوامر تشغّل ملفات .agent محليًا، وتتصل أيضًا بـagentmug.com لإنشاء العمال ونسخهم واستدعائهم عن بُعد. صُممت ليستخدمها البشر أو عمال آخرون؛ إذ يستطيع نموذج لغوي لديه وصول إلى الطرفية استخدامها.

# Local — uses your Anthropic key
export ANTHROPIC_API_KEY=sk-ant-...
agentmug run path/to/my.agent --input "Hello"

# Cloud — uses your AgentMug user key
export AGENTMUG_API_KEY=am_user_...    # mint at /settings/api-keys
agentmug create --prompt "Triage my Gmail and draft replies"
agentmug list
agentmug invoke email-triage --input "Summarize unread" --stream
agentmug fork email-triage --as personal-email
agentmug key new --agent email-triage

تتصل أوامر السحابة الفرعية بـ /api/agents/* و /api/external/agents/:id/invoke. تتم المصادقة باستخدام متغير البيئة AGENTMUG_API_KEY الذي يحمل مفتاحًا على مستوى المستخدم يبدأ بـam_user_… ).

إذا كنت تستدعي Claude مباشرةً عبر @anthropic-ai/sdk باستخدام تعليمة نظام وحلقة أدوات، فالانتقال إلى AgentMug هو في معظمه إعادة تنظيم للشفرة. يحل المحرك وسجل الأدوات محل حلقة الرسائل اليدوية، وتصبح تطبيقات أدواتك الحالية فئات ToolExecutor .

// Before — raw SDK
const anthropic = new Anthropic({ apiKey });
const messages = [{ role: "user", content: input }];
while (true) {
  const r = await anthropic.messages.create({
    model, system, messages, tools, max_tokens: 4096,
  });
  // hand-write: tool_use detection, executor dispatch,
  // tool_result formatting, stop_reason loop, etc.
}

// After — @agentmug/runtime
const tools = new InMemoryToolRegistry();
tools.register(gmailSendDefinition, new MyGmailExecutor());

const result = await quickRun({
  agentFile: parseAgentFile(myAgentJson),
  userInput: input,
  llm: { anthropicApiKey: apiKey },
  tools,
  onEvent: (e) => { /* streaming tokens + tool events */ },
});

ما الذي تحصل عليه عند الانتقال:

• حلقة أدوات تدعم الإيقاف المؤقت والاستئناف والإلغاء وبث الأحداث.
• محايد تجاه المزود—استخدم المسارات البرمجية نفسها مع Anthropic أوOpenAI أوGemini بتغيير عميل النموذج فقط.
• محمول .agent JSON قابلة للنقل، بحيث يمكن إدارة إصدار تعريف العامل أو نسخه أو نقله إلى بيئة تشغيل أخرى (السحابة أو سطح المكتب أو واجهة الأوامر أو MCP).
• دليل أدوات مدمج لا تحتاج إلى صيانته بنفسك.
• مهايئ خادم MCP يجعل عمالك قابلين للاستدعاء من أي عميل متوافق مع MCP دون شيفرة إضافية.

أمثلة قابلة للتشغيل داخل المستودع:

• hello-agent

  The 25-line minimum. quickRun + .agent file + token streaming.

• web-research

  Agent using web.fetch_json to call public APIs (HN, exchange rates) and summarize.

• mcp-server

  Configuration recipes for exposing an agent to Claude Code / Cursor / Continue / Cline via @agentmug/mcp-bridge.