# الوكلاء

توفّر Hugging Face أدوات وبروتوكولات تربط وكلاء الذكاء الاصطناعي مباشرةً بـ Hub. سواء كنت تتحدث مع Claude، أو تبني باستخدام Codex، أو تطوّر وكلاء مخصصين، يمكنك الوصول إلى النماذج، ومجموعات البيانات، وSpaces، وأدوات المجتمع. تغطي هذه الصفحة كيفية ربط [وكلاء الدردشة](#chat-with-hugging-face) و[وكلاء البرمجة](#coding-agents) لديك بـ Hub.

| صفحة | الوصف |
| ---- | ----------- |
| [سطر الأوامر](./agents-cli) | امنح وكيلك واجهة `hf` السطرية مع مهارة مدمجة |
| [خادم MCP](./agents-mcp) | اتصل بأي عميل متوافق مع MCP على Hub |
| [المهارات](./agents-skills) | إرشادات خاصة بالمهام لتدفقات العمل في الذكاء الاصطناعي وتعلم الآلة |
| [SDK](./agents-sdk) | Build agents programmatically with Python or JavaScript |
| [الوكلاء المحليون](./agents-local) | تشغيل وكلاء محليين بالكامل باستخدام llama.cpp وPi |
| [تتبعات الوكيل](./agent-traces) | عرض جلسات Claude Code وCodex وPi على Hub |

## التحدث مع Hugging Face

اربط مساعدك الذكي مباشرةً بـ Hugging Face Hub باستخدام بروتوكول سياق النموذج (MCP). بمجرد الاتصال، يمكنك البحث عن النماذج، واستكشاف مجموعات البيانات، وتوليد الصور، واستخدام أدوات المجتمع — كل ذلك من داخل واجهة الدردشة الخاصة بك.

### المساعدون المدعومون

يعمل خادم HF MCP مع أي عميل متوافق مع MCP:
- **ChatGPT** (عبر الإضافات)
- **Claude Desktop**
- **عملاء MCP مخصصون**

### الإعداد

#### 1. افتح إعدادات MCP

![MCP Settings Example](https://huggingface.co/huggingface/documentation-images/resolve/main/agents-docs/mcp-settings.png)

قم بزيارة [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp) أثناء تسجيل الدخول.

#### 2. اختر عميلك

اختر عميلك المتوافق مع MCP من القائمة. تعرض الصفحة تعليمات خاصة بكل عميل ومقطع إعداد جاهز للنسخ.

#### 3. تكوين وإعادة التشغيل

انسخ مقتطف الإعدادات إلى إعدادات MCP الخاصة بعميلك، ثم احفظ وأعد تشغيل عميلك.

> [!TIP]
> تولّد صفحة الإعدادات التكوين الدقيق الذي يتوقعه عميلك. استخدمها بدلاً من كتابة التكوين يدوياً.

### ما يمكنك فعله

بمجرد الاتصال، اطلب من مساعدك استخدام أدوات Hugging Face من بين الأدوات التي اخترتها في إعداداتك:

| المهمة | مثال على الاستعلام |
| ---- | -------------- |
| البحث في النماذج | "ابحث عن كمّات Qwen 3 على Hugging Face" |
| استكشاف مجموعات البيانات | "عرض مجموعات بيانات عن سلاسل زمنية تتعلق بالطقس" |
| البحث عن مساحات | "ابحث عن مساحة يمكنها نسخ ملفات الصوت" |
| توليد الصور | "أنشئ صورة 1024x1024 لقط بأسلوب جيبلي" |
| البحث في الأوراق | "ابحث عن الأوراق البحثية الحديثة حول نماذج الرؤية واللغة" |

يستدعي مساعدك أدوات MCP التي يعرضها خادم Hugging Face ويعيد النتائج مع البيانات الوصفية والروابط والسياق.

### إضافة أدوات المجتمع

وسّع إعدادك باستخدام مساحات Gradio المتوافقة مع MCP:

1. تصفّح [مساحات تدعم MCP](https://huggingface.co/spaces?filter=mcp-server)
2. أضِفها في [إعدادات MCP](https://huggingface.co/settings/mcp)
3. أعد تشغيل عميلك لبدء استخدام الأدوات الجديدة

تُعرّض تطبيقات Gradio MCP دوالها كأدوات مع حُجج ووصوف، مما يتيح لمساعدك استدعاءها مباشرة.

### التعرف على المزيد

- [دليل خادم MCP](./agents-mcp) - إعداد وتكوين مفصّل
- [إعدادات HF MCP](https://huggingface.co/settings/mcp) - تكوين عميلك
- [MCP-compatible Spaces](https://huggingface.co/spaces?filter=mcp-server) - Community tools

## وكلاء البرمجة

دمج Hugging Face في سير عمل البرمجة لديك باستخدام MCP Server و Skills. اطلع على النماذج ومجموعات البيانات وأدوات التعلم الآلي مباشرةً من بيئة تطوير البرامج (IDE) أو وكيل البرمجة الخاص بك. على سبيل المثال، نغطي وكلاء البرمجة التالية وأكثر باستخدام MCP و/أو Skills:

| وكيل البرمجة | طريقة التكامل |
| ------------ | ------------------ |
| [Claude Code](https://code.claude.com/docs) | خادم MCP + المهارات |
| [OpenAI Codex](https://openai.com/codex/) | خادم MCP + المهارات |
| [فتح الكود](https://opencode.ai/) | خادم MCP + المهارات |
| [Cursor](https://www.cursor.com/) | خادم MCP + المهارات |
| [VS Code](https://code.visualstudio.com/) | خادم MCP |
| [Gemini CLI](https://geminicli.com/) | خادم MCP |
| [Zed](https://zed.dev/) | خادم MCP |

### الإعداد السريع

#### خادم MCP

يمنح خادم MCP وكيل البرمجة الخاص بك إمكانية الوصول إلى بحث Hub وSpaces وأدوات المجتمع.

**Cursor / VS Code / Zed:**

1. قم بزيارة [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp)
2. اختر بيئة تطويرك من القائمة
3. انسخ مقتطف الإعداد
4. أضِفه إلى إعدادات MCP في بيئة تطويرك المتكاملة
5. إعادة تشغيل بيئة تطوير المتكاملة

**كود كلود:**

```bash
claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"
```

#### المهارات

توفّر المهارات إرشادات مخصّصة للمهام في سير عمل الذكاء الاصطناعي وتعلّم الآلة. تعمل هذه المهارات بالتوازي مع MCP أو بشكل مستقل.

```bash
# start claude 
claude

# install the skills marketplace plugin
/plugin marketplace add huggingface/skills
```

ثم، لتثبيت مواصفة مهارة:
```bash
/plugin install hf-cli@huggingface-skills
```

راجع [دليل المهارات](./agents-skills) لمعرفة المهارات المتاحة وطريقة استخدامها.

### ما يمكنك فعله

بمجرد إتمام التهيئة، يمكن لوكيل البرمجة الخاص بك:

| القدرة | مثال |
| ---------- | ------- |
| البحث في الـ Hub | "ابحث عن نموذج لتوليد الأكواد بأقل من 7 مليارات من المعاملات" |
| توليد الصور | "أنشئ مخططًا لمعمارية التحويلة" |
| استكشاف مجموعات البيانات | "ما هي مجموعات البيانات المتاحة لتحليل المشاعر؟" |
| تشغيل المساحات | استخدم مساحة Whisper لتحويل هذا الملف الصوتي إلى نص |
| احصل على التوثيق | كيف أقوم بضبط نموذج باستخدام transformers؟ |

### إعداد البيئة

#### المصادقة

اضبط رمز Hugging Face الخاص بك كمتغير بيئة:

```bash
export HF_TOKEN="hf_..."
```

أو قم بالمصادقة عبر [CLI](./agents-cli):

```bash
hf auth login
```

#### إضافة أدوات المجتمع

وسّع إعدادك باستخدام مساحات Gradio المتوافقة مع MCP:

1. تصفّح [مساحات تدعم MCP](https://huggingface.co/spaces?filter=mcp-server)
2. أضِفها في [إعدادات MCP](https://huggingface.co/settings/mcp)
3. أعد تشغيل بيئة تطويرك المتكاملة

### مثال على سير عمل

```text
You: Find a text classification model that works well on short texts

Agent: [Searches Hugging Face Hub]
       Found several options:
       - distilbert-base-uncased-finetuned-sst-2-english (sentiment)
       - facebook/bart-large-mnli (zero-shot)
       ...

You: Show me how to use the first one

Agent: [Fetches documentation]
       Here's how to use it with transformers:
       
       from transformers import pipeline
       classifier = pipeline("sentiment-analysis", 
                            model="distilbert-base-uncased-finetuned-sst-2-english")
       result = classifier("I love this product!")
```

## سجّل هيكل الوكيل الخاص بك

تدير Hugging Face سجلاً عامًا لأغلفة الوكلاء (agent harnesses)، وهي وكلاء البرمجة والأدوات التي تتفاعل مع Hub (مثل Claude Code وCodex وCursor وغيرها). عندما يكتشف `huggingface_hub` أنه يعمل داخل غلاف مسجّل، فإنه يبلغ عن ذلك عبر عامل المستخدم (user agent) في طلبات Hub. تسجيل غلافك يعني أن هذه النشاط يُنسب إلى أداتك بالاسم، ويمنح مشروعك تسمية عرض ودّية، وروابط تعود إلى مستنداتك ومستودعك، ومكانًا في [مجموعة بيانات استخدام الوكلاء](https://huggingface.co/datasets/huggingface/agent-usage) العامة — في حين أن الأدوات غير المسجّلة تُحتسب فقط ضمن حصتها المجمّعة `unknown`.

لتسجيل إطار عمل، افتح طلب سحب (Pull Request) لإضافة مدخل إلى [`agent-harnesses.ts`](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/agent-harnesses.ts) في حزمة `@huggingface/tasks`:

- يجب أن يكون معرّف الإطار (مفتاح الإدخال) أحرفًا صغيرة ومفصولة بشرطات (مثال: `"claude-code"`).
- اضبط `prettyLabel` بحالة أحرف سهلة الاستخدام (مثال: `Claude Code`).
- (اختياري) اضبط `repoUrl` برابط إلى كود المصدر الخاص بالهارنس (عادةً مستودع GitHub).
- (اختياري) اضبط `docsUrl` برابط إلى توثيق الإطار أو موقعه الإلكتروني.
- (اختياري) اضبط `description` بشرح موجز من سطر واحد للإطار.
- تحديد كيفية اكتشاف إطارك من البيئة:
  - إذا قام إطار العمل الخاص بك بإعداد أحد متغيرات البيئة القياسية (`AI_AGENT` أو `AGENT`)، فإن قيمته تُستخدم مباشرةً كمعرّف ولا حاجة إلى أي إعداد إضافي.
  - وإلا، اضبط `envVars` لربط أسماء متغيرات البيئة بأنماط قيم. استخدم `"*"` لمطابقة أي قيمة غير فارغة، أو نصًا دقيقًا لمطابقة دقيقة، أو `"<prefix>*"` لمطابقة البادئة.

وهذا كل شيء! بمجرد دمج طلب الإضافة، تُنسب حركة `huggingface_hub` (بما في ذلك واجهة سطر الأوامر `hf`) من إطار عمل الوكيل الخاص بك إليه بالاسم، ويظهر في [مجموعة بيانات استخدام الوكلاء](https://huggingface.co/datasets/huggingface/agent-usage) بدءًا من التحديث الشهري التالي.

## الخطوات التالية

- [CLI](./agents-cli) - واجهة سطر الأوامر لعمليات Hub
- [خادم MCP](./agents-mcp) - اربط أي مساعد ذكاء اصطناعي متوافق مع MCP بالمركز
- [المهارات](./agents-skills) - قدرات جاهزة مسبقًا لوكلاء البرمجة
- [SDK](./agents-sdk) - مكتبات Python وJavaScript لبناء الوكلاء