كـ

كل مساحة Gradio تعرض ملف نصي بسيط باسم agents.md يمكن لوكلاء البرمجة (Claude Code، Codex، OpenCode، Pi، إلخ) استدعاؤه مباشرة. ابحث عن ملف عبر البحث الدلالي على huggingface.co/spaces (مثلًا “audio transcription”)، وجربه اختياريًا في الواجهة أولاً، ثم وجّه وكيلك إلى ملف agents.md الخاص به. يعطيك الاستجابة كل ما يلزم لاستدعاء المساحة في محاولة واحدة: عنوان مخطط البيانات، وقوالب الاستدعاء والاستعلام، وتعليمات رفع الملفات، وتلميح للمصادقة.

تصبح هذه الإمكانية أقوى بكثير عند سلاسل المساحات. يمكن للوكيل تحويل موجه إلى أصل ثلاثي الأبعاد عن طريق استدعاء black-forest-labs/flux-klein-9b-kv للحصول على صورة، ثم تمرير الصورة المولّدة إلى microsoft/TRELLIS.2 للحصول على النموذج ثلاثي الأبعاد. لا حاجة إلى مكتبة عميل، ولا إلى تكامل مبرمج مسبقاً.

كل ما تحتاجه هو HF_TOKEN مُعيّن في بيئة التشغيل للبدء.

من واجهة المستخدم

تحتوي كل صفحة Space متوافقة على زر Agents في الترويسة. انقر عليه لنسخ أمر curl الخاص بملف agents.md لذلك الـ Space، ثم الصقه في الوكيل الخاص بك.

نقطة النهاية agents.md

https://huggingface.co/spaces/<namespace>/<repo>/agents.md

مثال:

curl https://huggingface.co/spaces/microsoft/TRELLIS.2/agents.md

يعيد:

To use this application (microsoft/TRELLIS.2: Create 3D model from a single image):
API schema: GET https://microsoft-trellis-2.hf.space/gradio_api/info
Call endpoint: POST https://microsoft-trellis-2.hf.space/gradio_api/call/v2/{endpoint} {"param_name": value, ...}
Poll result: GET https://microsoft-trellis-2.hf.space/gradio_api/call/{endpoint}/{event_id}
File inputs: POST https://microsoft-trellis-2.hf.space/gradio_api/upload -F "files=@file.ext", use as: {"path": "<returned-path>", "meta": {"_type": "gradio.FileData"}, "orig_name": "file.ext"}
Auth: Bearer $HF_TOKEN (https://huggingface.co/settings/tokens)

مدخلات الملفات

عندما يستقبل نقطة نهاية ملفًا (صورة، صوت، فيديو، إلخ)، ارفع الملف أولًا ثم اذكر المسار المُعاد في استدعاءك. ارفع الملف إلى /gradio_api/upload وأعد استخدام المسار الذي يعيده:

# 1. Upload the file
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/proxy/microsoft-trellis-2.hf.space/gradio_api/upload \
  -F "files=@chair.png"
# → ["/tmp/gradio/.../chair.png"]

# 2. Reference the returned path as a FileData object in your call
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/proxy/microsoft-trellis-2.hf.space/gradio_api/call/v2/predict \
  -d '{"image": {"path": "/tmp/gradio/.../chair.png", "meta": {"_type": "gradio.FileData"}, "orig_name": "chair.png"}}'

يمكن تمرير المدخلات التي تقبل عنوان URL عام (بدلاً من ملف مرفوع) مباشرةً دون الحاجة إلى خطوة الرفع.

المصادقة وZeroGPU

يعمل معظم المساحات الأكثر شيوعًا على ZeroGPU، والذي يستخدم الحصة اليومية للمستدعي. يجب على الوكلاء دائمًا تمرير $HF_TOKEN حتى تُحتسب تكاليف الاستدعاءات على حسابك بدلاً من مجمّع مجهول الهوية يخضع للتحكم في المعدل. كما أن نفس الرمز مطلوب للمساحات الخاصة. أنشئ رمزًا في huggingface.co/settings/tokens (يربط سطر المصادقة في agents.md بهذه الصفحة مباشرةً).

curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/proxy/microsoft-trellis-2.hf.space/gradio_api/call/v2/predict \
  -d '{"image": {"path": "https://example.com/chair.png"}}'

كيف سيقوم الوكلاء باستخدام هذا

1. يقوم الوكيل بإرسال طلب curl إلى /agents.md الخاص بالمساحة.
2. يجلب /gradio_api/info لمعرفة أسماء نقاط النهاية والمدخلات.
3. في حال مدخلات الملفات، يرسل الملف عبر طلب POST إلى /gradio_api/upload ويحتفظ بالمسار المُعاد.
4. يُرسل طلب POST إلى /gradio_api/call/v2/<endpoint>، ثم يرسل طلب GET إلى عنوان الاستعلام (poll URL) لبث النتيجة.