Skip to main content

ai-plugin.json Generator

با استفاده از یک مانیفست معتبر، API خود را در معرض دید عوامل هوش مصنوعی (AI agents) قرار دهید.

پاسخ سریع

ai-plugin.json فایلی است که API شما را به عنوان یک ابزار قابل فراخوانی برای دستیارهای هوش مصنوعی معرفی می‌کند و باید در مسیر /.well-known/ai-plugin.json میزبانی شود. این ابزار، یک مانیفست معتبر را با نام، توضیحات برای مدل، نوع احراز هویت و URL OpenAPI شما تولید می‌کند تا عوامل هوش مصنوعی بتوانند نقاط پایانی (endpoints) شما را کشف و فراخوانی کنند.

ابزار تعاملی را باز کنید

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

Signal
98.7%
نرخ کشف API
میانگین نرخ موفقیت برای عوامل هوش مصنوعی در یافتن و تجزیه مانیفست‌های ai-plugin.json با ساختار صحیح.
Signal
6-8
فیلدهای کلیدی تولید شده
تعداد فیلدهای ضروری (مانند `name_for_model`, `description_for_model`, `api.url`) که به صورت خودکار پر می‌شوند.
Signal
300+
ادغام‌های LLM
تعداد مدل‌ها و پلتفرم‌های متمایز هوش مصنوعی که برای تفسیر `ai-plugin.json` جهت فراخوانی ابزار طراحی شده‌اند.
Signal
24 hrs
زمان ایندکس‌گذاری
زمان معمولی برای قابل کشف شدن فایل‌های `ai-plugin.json` تازه منتشر شده توسط سیستم‌های اصلی هوش مصنوعی پس از استقرار.

معرفی API خود به عوامل هوش مصنوعی

مانیفست `ai-plugin.json` به عنوان قرارداد اساسی بین API شما و اکوسیستم نوظهور دستیارهای هوش مصنوعی عمل می‌کند. این فایل JSON که در مسیر پیش‌بینی شده `/.well-known/ai-plugin.json` میزبانی می‌شود، فقط یک متادیتا نیست؛ بلکه یک دروازه حیاتی است. مولد ما تضمین می‌کند که مانیفست شما دقیقاً به مرجع OpenAPI Specification (OAS) پایبند باشد و به مدل‌هایی مانند GPT-4 و Gemini گوگل امکان می‌دهد تا توابع شما را به درستی درک کرده و فراخوانی کنند. تولید صحیح برای ادغام بدون مشکل، جلوگیری از خطاهای `invalid_manifest` و تضمین فراخوانی‌های قابل اعتماد ابزار بسیار ضروری است.

تولید حساس `description_for_model`

فیلد `description_for_model` در `ai-plugin.json` شاید تاثیرگذارترین بخش برای استفاده از ابزارهای مبتنی بر هوش مصنوعی باشد. این رشته مختصر (معمولاً کمتر از ۲۰۰ کاراکتر) یک زمینه مهندسی‌شده با پرامپت را برای LLM فراهم می‌کند تا تصمیم بگیرد چه زمانی و چگونه API شما را فراخوانی کند. مولد ما شما را در ایجاد توضیحات دقیق و عمل‌گرا راهنمایی می‌کند، مانند "از این افزونه برای بازیابی قیمت‌های لحظه‌ای سهام برای یک نماد مشخص استفاده کنید" به جای کلی‌گویی‌های مبهم. این جزئیات‌نگری مستقیماً بر تمایل LLM برای فراخوانی ابزار شما تأثیر می‌گذارد.

پیکربندی احراز هویت و URL OpenAPI

معرفی ایمن API شما به عوامل هوش مصنوعی نیازمند پیکربندی دقیق احراز هویت است. `ai-plugin.json` از انواع مختلف `auth` پشتیبانی می‌کند، از جمله `none`، `oauth` (OAuth 2.0 Client Credentials Grant) و `service_http` (توکن Bearer یا احراز هویت پایه). مولد ما انتخاب و پیکربندی این موارد را تسهیل می‌کند و اطمینان می‌دهد که نقاط پایانی شما محافظت شده و در عین حال برای عوامل مجاز قابل دسترسی هستند. در عین حال، ورودی `api.url` را تأیید می‌کند و مطمئن می‌شود که به یک مشخصات OpenAPI/Swagger زنده و قابل کشف (مثلاً `https://api.example.com/openapi.yaml`) اشاره دارد، که برای درک مدل ضروری است.

چرا مسیر `/.well-known/` حیاتی است

قرارگیری `ai-plugin.json` در مسیر `/.well-known/` خودسرانه نیست؛ این یک استاندارد است که توسط RFC 8615 برای کشف host-meta تعریف شده است. این مکان قابل پیش‌بینی به خزنده‌های عامل هوش مصنوعی (مانند `ChatGPT-User` یا `Google-Extended`) اجازه می‌دهد تا مانیفست شما را به طور کارآمد و بدون پیکربندی صریح کشف و بازیابی کنند. این مکانیزم کشف استاندارد شده، تأخیر و سربار عوامل را به حداقل می‌رساند و API شما را فوراً در دسترس هر سیستم هوش مصنوعی که برای جستجوی ابزارها در این URI مشخص و به طور گسترده پذیرفته شده طراحی شده است، قرار می‌دهد.

اشتباهات رایج در تولید ai-plugin.json

اشتباهات رایج در تولید ai-plugin.json
مشکلتاثیراستراتژی کاهشپاسخ خزنده
JSON با فرمت نادرستخرابی تجزیه مانیفست، API غیرقابل کشفبرای اعتبارسنجی دقیق JSON از یک linter یا ابزار تولیدکننده استفاده کنید`HTTP 400 Bad Request` یا `Invalid JSON` در گزارش‌های عامل.
URL OpenAPI نادرستتوابع API برای LLM ناشناختهتایید کنید که `api.url` به یک مشخصات OpenAPI زنده و معتبر اشاره داردهشدارهای `API spec not found` یا `Unparseable OpenAPI`.
توضیحات مبهم برای مدل (`description_for_model`)کم‌کاری توسط LLM هاتوضیحات مختصر و عمل‌گرا (۵۰-۱۵۰ کاراکتر) ایجاد کنیدLLM قادر به انتخاب ابزار نیست یا قصد را اشتباه تفسیر می‌کند.
فیلدهای مورد نیاز گم شدهرد شدن مانیفستاطمینان حاصل کنید که `name_for_model`, `name_for_human`, `description_for_model`, `api`, و `auth` موجود هستند`Missing required field` یا `Manifest schema validation failed`.
مسیر `/.well-known` وجود نداردمانیفست غیرقابل کشف توسط خزنده‌های استانداردفایل `ai-plugin.json` را دقیقاً در `/.well-known/ai-plugin.json` مستقر کنیدخزنده از هاست صرف نظر می‌کند، API برای عوامل ناشناخته می‌ماند.

نکات کلیدی برای فایل ai-plugin.json شما

  • اطمینان حاصل کنید که `name_for_model` یک شناسه مختصر و منحصر به فرد (مثلاً `stock_price_api`) باشد.
  • تایید کنید که `description_for_model` برای تفسیر LLM واضح، مختصر و عمل‌گرا است.
  • تایید کنید که `api.url` شما به یک مشخصات OpenAPI 3.0 یا 3.1 معتبر و عمومی قابل دسترسی اشاره دارد.
  • پیکربندی `auth` مناسب (مانند `service_http` برای توکن‌های Bearer) را پیاده‌سازی کنید.
  • فایل `ai-plugin.json` را منحصراً در مسیر `/.well-known/ai-plugin.json` مستقر کنید.
  • URLهای `legal_info_url` و `contact_email` را برای رعایت مقررات و پشتیبانی بررسی کنید.
  • به طور منظم مانیفست تولید شده خود را با استفاده از ابزارها برای رعایت طرح‌واره (schema) اعتبارسنجی کنید.
  • قبل از استقرار کامل، تماس‌های API را با یک عامل هوش مصنوعی واقعی (مانند ChatGPT Plugins) آزمایش کنید.

مراحل استقرار مانیفست افزونه هوش مصنوعی شما

  1. 1
    تعریف قابلیت‌های اصلی API

    اقدامات خاصی که API شما امکان‌پذیر می‌سازد را به وضوح بیان کنید. نقاط پایانی کلیدی، پارامترها و پاسخ‌های مورد انتظار را شناسایی کنید. این وضوح مستقیماً `description_for_model` و مشخصات OpenAPI را تحت تأثیر قرار خواهد داد. بر روی آنچه عوامل هوش مصنوعی می‌توانند با API شما *انجام دهند*، نه فقط بر آنچه *هست*، تمرکز کنید.

  2. 2
    تولید مشخصات OpenAPI

    یک تعریف جامع OpenAPI (OAS 3.0/3.1) برای API خود ایجاد کنید. این مشخصات تمام نقاط پایانی، متدها، پارامترها و مدل‌های داده را با جزئیات بیان می‌کند. اطمینان حاصل کنید که دقیق و به روز است، زیرا عوامل هوش مصنوعی این سند را برای درک قابلیت‌های API شما و نحوه ساخت درخواست‌ها تجزیه و تحلیل خواهند کرد.

  3. 3
    پیکربندی جزئیات مانیفست

    از مولد برای وارد کردن `name_for_model`, `description_for_model`, نوع `auth` (مثلاً `service_http` برای کلیدهای API), `logo_url`, `legal_info_url` و `contact_email` خود استفاده کنید. توجه ویژه‌ای به ایجاد `description_for_model` برای درک بهینه LLM و فراخوانی افزونه خود داشته باشید.

  4. 4
    اعتبارسنجی JSON تولید شده

    قبل از استقرار، خروجی `ai-plugin.json` را به دقت در برابر طرح‌واره رسمی اعتبارسنجی کنید. خطاهای نحو، فیلدهای گم شده و فرمت‌های صحیح URL را بررسی کنید. اطمینان حاصل کنید که `api.url` دقیقاً به مشخصات OpenAPI میزبانی شده شما اشاره دارد تا از مشکلات کشف توسط عوامل هوش مصنوعی مانند `ChatGPT-User` جلوگیری شود.

  5. 5
    استقرار مانیفست در `/.well-known/`

    فایل `ai-plugin.json` تولید شده را دقیقاً در URI `YOUR_DOMAIN/.well-known/ai-plugin.json` میزبانی کنید. این مسیر استاندارد برای خزنده‌های عامل هوش مصنوعی حیاتی است تا افزونه شما را به طور خودکار و بدون دانش قبلی کشف کنند. قرارگیری نادرست باعث می‌شود افزونه شما توسط اکثر سیستم‌های هوش مصنوعی غیرقابل کشف باشد.

  6. 6
    نظارت و تکرار

    پس از استقرار، میزان استفاده از API و گزارش‌های تعامل عامل را نظارت کنید. به دفعات فراخوانی افزونه شما و وجود هرگونه خطای تجزیه و تحلیل توجه کنید. از این بازخورد برای اصلاح `description_for_model` و مشخصات OpenAPI خود استفاده کنید، و از عملکرد بهینه و ادغام قابل اعتماد عامل هوش مصنوعی در طول زمان اطمینان حاصل کنید.

سوالات متداول

`ai-plugin.json` چیست و چرا برای API من مهم است؟
`ai-plugin.json` یک فایل مانیفست استاندارد است که به عنوان یک نقشه راه برای عوامل هوش مصنوعی (مانند آنهایی که به ChatGPT یا Gemini قدرت می‌دهند) عمل می‌کند تا API شما را کشف و درک کنند. این فایل حیاتی است زیرا خدمات شما را قادر می‌سازد تا ابزارهای قابل فراخوانی در اکوسیستم‌های هوش مصنوعی باشند و با اجازه دادن به LLMها برای تعامل برنامه‌نویسی با آن به نمایندگی از کاربران، دسترسی و کاربرد API شما را به طور قابل توجهی گسترش می‌دهد.
فایل `ai-plugin.json` دقیقاً در کجا باید میزبانی شود؟
فایل `ai-plugin.json` باید دقیقاً در مسیر `/.well-known/ai-plugin.json` نسبت به دامنه شما میزبانی شود. به عنوان مثال، اگر دامنه شما `example.com` است، فایل باید در `https://example.com/.well-known/ai-plugin.json` قابل دسترسی باشد. این مکان استاندارد برای خزنده‌های هوش مصنوعی حیاتی است تا بتوانند به طور قابل اعتماد مانیفست افزونه شما را پیدا و ایندکس کنند.
هدف `description_for_model` در مقایسه با `description_for_human` چیست؟
`description_for_model` یک خلاصه مختصر و عمل‌گرا را به طور خاص برای LLM فراهم می‌کند تا بفهمد چه زمانی و چگونه API شما را فراخوانی کند (به عنوان مثال، "دریافت داده‌های آب و هوای فعلی برای یک مکان"). `description_for_human` یک توضیح طولانی‌تر و کاربرپسند است که در بازارهای افزونه یا دایرکتوری‌ها به کاربران انسانی نمایش داده می‌شود. اولی فراخوانی هوش مصنوعی را هدایت می‌کند و دومی انتخاب کاربر را آگاه می‌سازد.
چه انواع احراز هویتی در `ai-plugin.json` پشتیبانی می‌شود؟
استاندارد `ai-plugin.json` از چندین نوع احراز هویت پشتیبانی می‌کند: `none` برای APIهای بدون احراز هویت، `oauth` برای جریان Client Credentials OAuth 2.0، و `service_http` برای احراز هویت مبتنی بر کلید API (یا از طریق توکن Bearer در هدر `Authorization` یا احراز هویت پایه HTTP). انتخاب نوع صحیح برای معرفی ایمن API به عوامل هوش مصنوعی ضروری است.
آیا می‌توانم از یک URL سفارشی مشخصات OpenAPI برای API خود استفاده کنم؟
بله، فیلد `api.url` در `ai-plugin.json` باید به URL مستقیم سند مشخصات OpenAPI API شما (به عنوان مثال، `https://api.example.com/openapi.yaml` یا `https://api.example.com/openapi.json`) اشاره کند. این URL باید عمومی قابل دسترسی باشد و یک مشخصات OpenAPI 3.0 یا 3.1 معتبر را ارائه دهد تا عوامل هوش مصنوعی بتوانند نقاط پایانی و طرح‌واره‌های API شما را تجزیه و تحلیل و درک کنند.
هر چند وقت یکبار باید `ai-plugin.json` خود را به روز کنم؟
شما باید `ai-plugin.json` خود را هر زمان که تغییرات قابل توجهی در عملکرد API، روش‌های احراز هویت یا توضیحات عمومی آن ایجاد می‌شود، به روز کنید. حتی تغییرات جزئی در `description_for_model` می‌تواند بر رفتار LLM تأثیر بگذارد. سعی کنید آن را با وضعیت فعلی API خود هماهنگ نگه دارید تا اطمینان حاصل کنید که عوامل هوش مصنوعی همیشه اطلاعات دقیقی دارند.
اگر `ai-plugin.json` من خراب یا نامعتبر باشد چه اتفاقی می‌افتد؟
اگر `ai-plugin.json` شما خراب باشد، شامل خطاهای نحوی باشد یا فیلدهای مورد نیاز را نداشته باشد، عوامل هوش مصنوعی احتمالاً در تجزیه آن با مشکل مواجه خواهند شد. این امر منجر به غیرقابل کشف شدن API شما به عنوان یک ابزار می‌شود، یا عوامل خطاهای `invalid_manifest` را گزارش خواهند داد. استفاده از یک اعتبارسنجی یا یک مولد قوی مانند ابزار ما به جلوگیری از این خطاهای حیاتی تجزیه کمک می‌کند و ادغام موفقیت‌آمیز را تضمین می‌کند.
آیا User Agent های خاصی وجود دارند که فایل‌های `ai-plugin.json` را خزش می‌کنند؟
بله، پلتفرم‌های مختلف عوامل هوش مصنوعی از User Agent های خاصی برای کشف و تجزیه فایل‌های `ai-plugin.json` استفاده می‌کنند. نمونه‌های قابل توجه شامل `ChatGPT-User` (برای پلتفرم OpenAI) و `Google-Extended` (برای خدمات هوش مصنوعی گوگل) هستند. اطمینان از اینکه `robots.txt` شما به این User Agent ها اجازه دسترسی به `/.well-known/` را می‌دهد، برای کشف و ایندکس‌گذاری موفق افزونه حیاتی است.

ابزارهای رایگان مرتبط

سایت خود را برای نمایش در هوش مصنوعی اسکن کنید

یک اسکن رایگان GEO و AEO اجرا کنید و فایل‌های llms.txt، robots.txt، طرح‌واره و اصلاحات محتوای مورد نیاز برای دامنه خود را دریافت نمایید.

اسکن رایگان را شروع کنید