پروژه‌ی پایانی: اکوسیستم ابزارهای بی‌وضعیت

در ساخت سیستم‌های چندایجنت واقعی، اشتباه رایج تیم‌ها ترکیب درهم‌تنیده‌ی قابلیت‌هاست؛ به‌طوری‌که مرز میان قراردادهای پروتکل، منطق ابزارها، بررسی‌های امنیتی و سیستم‌های ردگیری گم می‌شود. این درس با طراحی یک معماری یکپارچه برای یک جریان پژوهش و گزارش‌دهی، نشان می‌دهد چگونه قراردادهای مستقل از جمله کشف سرویس، ارسال درخواست‌های بی‌وضعیت (Stateless)، عملیات‌های طولانی و تفویض کار را به‌طور اصولی در کنار یکدیگر بچینید.

در این پروژه‌ی پایانی، یک شبیه‌سازی درون‌پرداره‌ای دقیق با ساختار پایتون پیاده می‌شود که قراردادهای نگارش جدید پروتکل MCP و تعامل با استانداردهای A2A و OpenTelemetry را نمایش می‌دهد. این رویکرد به شما یاد می‌دهد تفاوت میان یک شبیه‌سازی محلی و پیاده‌سازی واقعی تحت شبکه را تفکیک کنید و بدانید هر لایه در زمان استقرار عملیاتی دقیقاً با چه مؤلفه‌ای جایگزین خواهد شد.

یک سیستم ایجنت عملیاتی (production agent system)، مجموعه‌ای از مرزها است نه انبوهی از قابلیت‌ها. این پروژه‌ی پایانی یک شبیه‌سازی خوانا درون یک پردازه را از کلاینت‌های پروتکل، سرور مجوزدهی، محیط ایزوله (sandbox) و صادرکننده‌ی دورسنجی (telemetry exporter) که یک استقرار واقعی به آن‌ها نیاز دارد، تفکیک می‌کند.

اهداف یادگیری

• ترکیب فراخوانی‌های ابزار (tool calls)، نتایج در قالب تسک، کارهای واگذارشده، منابع رابط کاربری، خط‌مشی مجوزدهی و رکوردهای ردگیری در یک جریان واحد.
• انتقال نسخه‌ی پروتکل، هویت کلاینت و قابلیت‌ها در تمام درخواست‌های MCP به‌جای تکیه بر نشست اتصال (connection session).
• کشف سرور پیش از استفاده و پیش‌برد کارهای طولانی از طریق افزونه‌ی رسمی Tasks.
• تمایز قائل شدن میان شبیه‌سازی هم‌شکل پروتکل و پیاده‌سازی واقعی MCP، A2A، OAuth یا OpenTelemetry.
• نگاشت هر مرز شبیه‌سازی‌شده به مؤلفه‌ی عملیاتی معادلی که باید جایگزین آن شود.
• حفظ نقش دقیق AGENTS.md، مهارت ایجنت (Agent Skill)، تطبیق‌دهنده‌های محیط اجرا، ابزارها و خط‌مشی امنیتی.
• تفکیک ادعاهایی که با خروجی محلی اثبات می‌شوند از ادعاهایی که به آزمون‌های یکپارچگی زنده نیاز دارند.

صورت مسئله

طراحی یک سیستم پژوهش و گزارش‌دهی: کاربر مقالاتی درباره‌ی پروتکل‌های ایجنت می‌خواهد. سیستم کاتالوگ مقاله‌ها را جست‌وجو می‌کند، خلاصه‌سازی را واگذار می‌کند، گزارشی می‌سازد، یک منبع رابط کاربری بازمی‌گرداند و مسیر طی‌شده در سامانه را ثبت می‌کند.

همین یک جمله چندین قرارداد مستقل را در خود پنهان کرده است:

• اسکیمای ابزار در تعامل با مدل؛
• پاکت درخواست بی‌وضعیت و قرارداد کشف سرور؛
• تصمیم‌گیری درگاه برای کنشگر، دامنه و هویت ابزار؛
• قرارداد عملیات‌های زمان‌بر؛
• پروتکل واگذاری؛
• پل ارتباطی میزبان با برنامه؛
• انتشار و صدور ردگیری؛
• یک رویه‌ی عملیاتی با قابلیت استفاده‌ی مجدد.

فایل code/main.py این مرزها را با توابع و دیکشنری‌های معمولی پایتون شفاف نگه می‌دارد. این کد هیچ بستر انتقالی باز نمی‌کند، با arXiv ارتباطی نمی‌گیرد، احراز هویت OAuth انجام نمی‌دهد، سرور A2A را فرا نمی‌خواند، هیچ برنامه‌ی MCPای رندر نمی‌کند و دورسنجی صادر نمی‌کند. این رویکرد، بررسی جریان کنترل را بدون جا زدن یک شبیه‌سازی به‌جای سرویسی استاندارد، آسان می‌کند.

مبانی نظری

معماری هدف

این معماری، ترکیبی مفهومی از الگوهای پروتکل‌های عمومی است و ادعایی درباره‌ی سازوکار داخلی هیچ محصول خاصی ندارد.

ردگیری هدف

در پیاده‌سازی واقعی، کانتکست ردگیری در هر گام لغزش (hop) منتقل می‌شود. نام‌ها و ویژگی‌های اسپَن (span) باید از قراردادهای معنایی OpenTelemetry منطبق با نسخه‌ی ابزار دقیق انتخابی پیروی کنند. داشتن یک شناسه‌ی ردگیری مشترک به‌تنهایی صحت ساختار والد-فرزندی، صدور داده یا ذخیره در بک‌اند را اثبات نمی‌کند.

بخش‌های فعلی پروتکل

از متدهایی استفاده کنید که در نسخه‌ی فعلی پروتکل تعریف شده‌اند، نه نام‌هایی که از پیش‌نویس‌های قدیمی‌تر در ذهن مانده است:

نام‌های پروتکل فقط لایه‌ی نخست هستند. آزمون‌های عملیاتی باید سریال‌سازی، خطاهای احراز هویت، لغو عملیات، مهلت زمانی (timeout)، تلاش مجدد و سازگاری نسخه‌ها را روی شبکه‌ی واقعی ارزیابی کنند.

تغییرات مرز یکپارچه‌سازی در MCP بی‌وضعیت

بازنگری 2026-07-28 نشست‌های پروتکل و دست‌دادن اولیه‌ی initialize / notifications/initialized را حذف می‌کند. همچنین هدر Mcp-Session-Id حذف شده است. هر درخواست این فیلدهای تفکیک‌شده با فضای نام (namespaced) را در _meta حمل می‌کند:

{
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientCapabilities": {
    "extensions": {
      "io.modelcontextprotocol/tasks": {}
    }
  },
  "io.modelcontextprotocol/clientInfo": {
    "name": "capstone-client",
    "version": "1.0.0"
  }
}

سرور باید server/discover را پیاده‌سازی کند. نتایج عادی از resultType: "complete" استفاده می‌کنند؛ هندل تسک نیز از resultType: "task" بهره می‌برد. هر نتیجه باید سرور را در _meta.io.modelcontextprotocol/serverInfo معرفی کند.

افزونه‌ی تسک متدهای tasks/get، tasks/update و tasks/cancel را شامل می‌شود. ابزار ممکن است ابتدا resultType: "task" را برگرداند؛ خود متد tasks/get خروجی resultType: "complete" می‌دهد و شیء تکمیل‌شده‌ی Task حاوی نتیجه‌ی نهایی است. متدهای قدیمی tasks/result و tasks/list جزو این افزونه‌ی فعلی نیستند. کلاینت باید io.modelcontextprotocol/tasks را در همان درخواستی اعلام کند که احتمال دریافت هندل تسک در آن وجود دارد. در غیر این صورت، سرور کد خطای -32021 را همراه با requiredCapabilities برمی‌گرداند؛ با ساختاری معادل شیء قابلیت‌های مفقود کلاینت از جمله extensions.io.modelcontextprotocol/tasks.

وضعیت امنیتی

استقرار نهایی مدنظر از دفاع چندلایه (defense in depth) بهره می‌برد:

• مجوزدهی OAuth همراه با PKCE در جاهایی که نوع کلاینت ایجاب می‌کند؛
• مقیدسازی منبع و مخاطب برای توکن‌های دسترسی صادرشده؛
• سامانه کنترل دسترسی مبتنی بر نقش (RBAC) درگاه که ابزار درخواستی و دامنه‌ی دسترسی را بررسی می‌کند؛
• نگهداری اطلاعات هویتی بالادستی خارج از کانتکست قابل‌مشاهده برای مدل؛
• مانیفستِ پین‌شده یا بازبینی‌شده از توضیحات ابزارها؛
• بازبینی با «قاعده‌ی دو نفر» (Rule of Two) برای ورودی‌های نامطمئن، داده‌های حساس و اقدامات با پیامد سنگین؛
• یک محیط ایزوله برای اجرا که محدودیت‌های فایل‌سیستم، پردازه، شبکه، اطلاعات هویتی و منابع را خارج از مهارت اعمال می‌کند.

این نسخه‌ی نمایشی صرفاً توکن‌های ایستا، بررسی دامنه‌ها و هش توضیحات را پیاده‌سازی می‌کند. بنابراین فقط برای بررسی گردش خط‌مشی مفید است، نه اعتبارسنجی امنیتی.

مهارت‌ها رویه هستند، نه بستر انتقال

یک مهارت ایجنت می‌تواند به محیط اجرا بگوید جریان پژوهش چگونه پیش برود، منتظر چه قراردادهای ابزاری باشد، چه شواهدی را ذخیره کند و چه زمانی متوقف شود. اما نمی‌تواند سرور MCP ایجاد کند، سازگاری A2A برقرار سازد، دامنه اعطا کند یا محیط ایزوله‌ای بسازد.

هرگاه رویه به فایل‌های وابسته ارجاع می‌دهد، کل پوشه‌ی مهارت را تحویل دهید. تک‌فایل مسطح این درس قدیمی‌تر، یک طرح آموزشی اولیه است، نه سندی که نشان دهد میزبان می‌تواند یک بسته‌ی کامل و قابل‌حمل را حفظ کند. در درس‌های 24 تا 27 چرخه‌ی عمر کامل بسته ساخته و ارزیابی می‌شود.

متادیتای سند دوره یک تطبیق‌دهنده‌ی محلی است

کاتالوگ دوره و ابزار نصب آن، فایل‌های تکی با نام skill-*.md را شناسایی می‌کنند، اما این صرفاً قراردادی درون همین مخزن است، نه قرارداد بسته‌ی قابل‌حمل Agent Skills. پارسر حداقلی بخش مشخصات اولیه (frontmatter) فقط کلیدهای سطح اول را می‌خواند. بنابراین این درس، فیلدهای هویتیِ قابل‌حمل و فیلدهای کاتالوگ دوره را در یک سطح نگه می‌دارد:

---
name: ecosystem-blueprint
description: Produce a full Phase 13 ecosystem architecture for a product need.
version: "1.0.0"
phase: "13"
lesson: "23"
tags: [mcp, capstone, ecosystem, architecture, a2a, otel]
---

فیلدهای name و description شناسه‌های هویتیِ قابل‌حمل هستند. فیلدهای version، phase، lesson و tags الحاقات کاتالوگ مخصوص این دوره‌اند. پارسر دوره نیازمند آن است که tags به‌صورت لیست تک‌خطی نوشته شود تا دستور --tag capstone بتواند آن را پیدا کند.

یک مهارت پوشه‌ای و قابل‌حمل می‌تواند از نگاشت اختیاری metadata برای داده‌های تکمیلی متنی استفاده کند. این موضوع باعث نمی‌شود metadata جایگزینی برای اسکیمای کاتالوگ این مخزن باشد. اگر این فایل مسطح، version یا tags را زیرمجموعه‌ی metadata بیاورد، پارسر حداقلی این کلیدهای تورفته را رد می‌کند؛ در نتیجه کاتالوگ، نسخه را خالی ثبت می‌کند و با فیلتر برچسب نمی‌توان این فایل را پیدا کرد. سیستم‌های میزبان در محیط عملیاتی باید از یک پارسر امن YAML استفاده کنند و اسکیمای مستند خود را بسنجند.

شبیه‌سازی در برابر محیط عملیاتی

این جدول، مرز تحویل سیستم است. اجرای محلی بدون خطا صرفاً شبیه‌سازی را تایید می‌کند و بس.

نقشه‌ی فاز 13

پیاده‌سازی گام‌به‌گام

بستر آزمون درون‌پردازه‌ای را اجرا کنید:

cd phases/13-tools-and-protocols/23-capstone-tool-ecosystem
python3 code/main.py

شش نکته را بررسی کنید:

1. دستور server/discover نگارش 2026-07-28 و افزونه‌ی Tasks را اعلام کند.
2. آلیس بتواند بخواند و گزارش بسازد، درحالی‌که فراخوانی باب با دامنه‌ی نوشتن رد شود.
3. تمام اسپَن‌های محلی در یک دور اجرای هماهنگ‌کننده، شناسه‌ی ردگیری مشترکی داشته باشند و شناسه‌های اسپَن والد را ثبت کنند.
4. ساخت گزارش ابتدا به‌صورت یک هندل تسک آغاز شود. متد tasks/get تسک تکمیل‌شده‌ای برگرداند که نتیجه‌ی نهایی‌اش شامل متن و ارجاع ui:// باشد.
5. سیستم نویسنده‌ی واگذارشده نفوذناپذیر باقی بماند، چون هماهنگ‌کننده فقط اسپَن مرزی آن را ثبت می‌کند.
6. در خروجی هیچ ادعایی مبنی بر اتصال شبکه، تبادل OAuth، صدور داده به گردآورنده، رندر در مرورگر یا اجرای محیط ایزوله ثبت نشده باشد.

این اسکریپت دو بار اجرا می‌شود، بنابراین دو ردگیری ریشه تولید می‌کند. داده‌های ثبت عملکرد، درون همان پردازه می‌مانند و با اجرای بعدی بازنشانی می‌شوند.

انتقال به محیط واقعی

لایه‌ها را یکی‌یکی ارتقا دهید:

1. تابع server_discover() و لیست ایستای ابزارها را با فراخوانی‌های واقعی server/discover و tools/list جایگزین کنید. نسخه، هویت و قابلیت‌ها را در هر درخواست بفرستید.
2. توکن‌های ایستا را با یک سرور مجوزدهی و اعتبارسنجی منبع حفاظت‌شده جایگزین کنید.
3. افزونه‌ی io.modelcontextprotocol/tasks را پیاده‌سازی کرده و متدهای tasks/get، tasks/update، tasks/cancel، مهلت زمانی، TTL و بازیابی پس از راه‌اندازی مجدد را تست کنید. متدهای tasks/result یا tasks/list را اضافه نکنید.
4. بخش ساختگی واگذاری را با یک کلاینت A2A جایگزین کنید که می‌تواند Agent Card را بخواند و پیام بفرستد.
5. برنامه را با SDK رسمی بسازید و ابزارهای سرور را با app.callServerTool فراخوانی کنید.
6. اسپَن‌ها را به یک گردآورنده‌ی آزمایشی صادر کنید و روابط والد-فرزندی را در سمت گیرنده بسنجید.
7. اجرای ابزارها و اسکریپت‌ها را به محیط ایزوله‌ی منطبق با درس 26 بسپارید.
8. رویه را در قالب یک بسته‌ی پوشه‌ای کامل آماده کرده و تاییدیه‌ی انتشار درس 27 را دریافت کنید.

هر ارتقا نیازمند یک آزمون یکپارچگی است که از مرز جدید عبور کند. با ورود به شبکه‌ی واقعی، آزمون‌های سطح پایین‌تر مربوط به خط‌مشی‌ها را حذف نکنید.

انتشار خروجی

این درس فایل outputs/skill-ecosystem-blueprint.md را تولید می‌کند که ساختار دوره‌ای قدیمی و تک‌فایلی دارد. این خروجی، یک طرح معماری تک‌صفحه‌ای شامل مبانی پایه، امنیت، واگذاری، دورسنجی، بسته‌بندی و سخت‌ترین ریسک عملیاتی می‌خواهد. فیلدهای کاتالوگی سطح اول آن با کاتالوگ واقعی مخزن و پارسرهای نصاب ارزیابی می‌شوند.

این فایل به‌دلیل این‌که یک بسته‌ی پوشه‌ای نیست، نمی‌تواند ارجاعات، اسکریپت‌ها، دارایی‌ها یا داده‌های ارزیابی را با خود داشته باشد. هنگام انتشار مهارتی قابل‌استفاده‌ی مجدد در خارج از این دوره، از فرمت بسته‌بندی درس‌های 22 و 24 تا 27 استفاده کنید.

تمرین‌ها

1. اسکریپت code/main.py را اجرا کنید. واقعیت‌های اثبات‌شده در خروجی را از ادعاهای محیط عملیاتی که همچنان نیازمند شواهد یکپارچگی هستند، تفکیک کنید.
2. یک بک‌اند ایستای دوم اضافه کرده و قاعده‌ی تداخل دو ابزار هم‌نام را تعیین کنید. سپس هر دو لیست را با فراخوانی‌های واقعی tools/list جایگزین کنید.
3. بخش ساختگی نویسنده را با یک سرور آزمایشی A2A جایگزین کنید. شناسه Agent Card، درخواست پیام، مسیر مهلت زمانی و خروجی نهایی برگشتی را ثبت کنید.
4. یک ذخیره‌ساز تسک اضافه کنید که با راه‌اندازی مجدد پردازه از بین نرود. اثبات کنید که کلاینت می‌تواند با tasks/get کار را از سر بگیرد، مقدار pollIntervalMs را رعایت کند و بدون نیاز به tasks/result نتیجه‌ی نهایی تسک تکمیل‌شده را بخواند.
5. یک برنامه‌ی کمینه‌ی MCP بسازید و متد app.callServerTool را در مرورگری با خط‌مشی‌های امنیتی سخت‌گیرانه‌ی CSP و مجوزهای صریح آزمایش کنید.
6. اسپَن‌های شبیه‌سازی‌شده را با کمک SDK ابزار OTel به یک گردآورنده‌ی محلی بفرستید. تایید دریافت، شناسه‌های ردگیری، روابط والد-فرزندی و وضعیت خطاها را بررسی کنید.
7. یک فایل AGENTS.md برای قوانین نگهداری کل مخزن و یک بسته‌ی مهارت مستقل برای رویه‌ی پژوهشِ قابل‌استفاده‌ی مجدد بنویسید. توضیح دهید چرا هیچ‌کدام از این دو فایل، اختیاری برای اجرای ابزارها صادر نمی‌کنند.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• مشخصات فنی MCP نسخه‌ی 2026-07-28 برای بررسی درخواست‌های بی‌وضعیت، کشف، ابزارها، مجوزها و رفتار بسترهای انتقال.
• تغییرات کلیدی MCP در نگارش 2026-07-28 جهت اطلاع از حذف نشست‌ها، متادیتای هر درخواست، MRTR، افزونه‌ها و موارد منسوخ‌شده.
• افزونه‌ی Tasks در MCP درباره‌ی متدهای tasks/get، tasks/update، tasks/cancel و نتایج نهایی همراهِ تسک‌های پایان‌یافته.
• SDK برنامه‌های MCP برای آشنایی با شیء App و فراخوانی app.callServerTool.
• پروتکل A2A جهت بررسی Agent Cards، تحویل پیام، تسک‌ها، مصنوعات و اتصالات بسترهای انتقال.
• قراردادهای معنایی GenAI در OpenTelemetry برای رعایت استانداردهای ردگیری و ویژگی‌ها.
• مشخصات فنی Agent Skills برای آشنایی با قرارداد بسته‌های قابل‌حمل مورد استفاده در لایه‌ی رویه‌ای.