---
title: تكامل Box
description: "تخزين الملفات وإدارة المستندات مع تكامل Box لـ CrewAI."
icon: "box"
mode: "wide"
---

## نظرة عامة

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

## المتطلبات الأساسية

قبل استخدام تكامل Box، تأكد من توفر ما يلي:

- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال
- حساب Box بالصلاحيات المناسبة
- ربط حساب Box الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors)

## إعداد تكامل Box

### 1. ربط حساب Box الخاص بك

1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors)
2. ابحث عن **Box** في قسم تكاملات المصادقة
3. انقر على **Connect** وأكمل عملية OAuth
4. امنح الصلاحيات اللازمة لإدارة الملفات والمجلدات
5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. تثبيت الحزمة المطلوبة

```bash
uv add crewai-tools
```

### 3. إعداد متغير البيئة

<Note>
  لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة
  `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك.
</Note>

```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

أو أضفه إلى ملف `.env`:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## الإجراءات المتاحة

<AccordionGroup>
  <Accordion title="box/save_file">
    **الوصف:** حفظ ملف من عنوان URL في Box.

    **المعاملات:**
    - `fileAttributes` (object, مطلوب): السمات - بيانات وصفية للملف تشمل الاسم والمجلد الأصلي والطوابع الزمنية.
      ```json
      {
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "name": "qwerty.png",
        "parent": { "id": "1234567" }
      }
      ```
    - `file` (string, مطلوب): عنوان URL للملف - يجب أن يكون حجم الملفات أقل من 50 ميجابايت. (مثال: "https://picsum.photos/200/300").

  </Accordion>

  <Accordion title="box/save_file_from_object">
    **الوصف:** حفظ ملف في Box.

    **المعاملات:**
    - `file` (string, مطلوب): الملف - يقبل كائن ملف يحتوي على بيانات الملف. يجب أن يكون حجم الملفات أقل من 50 ميجابايت.
    - `fileName` (string, مطلوب): اسم الملف (مثال: "qwerty.png").
    - `folder` (string, اختياري): المجلد - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار وجهة مجلد الملف. يستخدم المجلد الجذري افتراضياً إذا تُرك فارغاً.

  </Accordion>

  <Accordion title="box/get_file_by_id">
    **الوصف:** الحصول على ملف بواسطة المعرّف في Box.

    **المعاملات:**
    - `fileId` (string, مطلوب): معرّف الملف - المعرّف الفريد الذي يمثل ملفاً. (مثال: "12345").

  </Accordion>

  <Accordion title="box/list_files">
    **الوصف:** عرض قائمة الملفات في Box.

    **المعاملات:**
    - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0").
    - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية.
      ```json
      {
        "operator": "OR",
        "conditions": [
          {
            "operator": "AND",
            "conditions": [
              {
                "field": "direction",
                "operator": "$stringExactlyMatches",
                "value": "ASC"
              }
            ]
          }
        ]
      }
      ```

  </Accordion>

  <Accordion title="box/create_folder">
    **الوصف:** إنشاء مجلد في Box.

    **المعاملات:**
    - `folderName` (string, مطلوب): الاسم - اسم المجلد الجديد. (مثال: "New Folder").
    - `folderParent` (object, مطلوب): المجلد الأصلي - المجلد الأصلي الذي سيُنشأ فيه المجلد الجديد.
      ```json
      {
        "id": "123456"
      }
      ```

  </Accordion>

  <Accordion title="box/move_folder">
    **الوصف:** نقل مجلد في Box.

    **المعاملات:**
    - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0").
    - `folderName` (string, مطلوب): الاسم - اسم المجلد. (مثال: "New Folder").
    - `folderParent` (object, مطلوب): المجلد الأصلي - وجهة المجلد الأصلي الجديد.
      ```json
      {
        "id": "123456"
      }
      ```

  </Accordion>

  <Accordion title="box/get_folder_by_id">
    **الوصف:** الحصول على مجلد بواسطة المعرّف في Box.

    **المعاملات:**
    - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0").

  </Accordion>

  <Accordion title="box/search_folders">
    **الوصف:** البحث في المجلدات في Box.

    **المعاملات:**
    - `folderId` (string, مطلوب): معرّف المجلد - المجلد المراد البحث فيه.
    - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية.
      ```json
      {
        "operator": "OR",
        "conditions": [
          {
            "operator": "AND",
            "conditions": [
              {
                "field": "sort",
                "operator": "$stringExactlyMatches",
                "value": "name"
              }
            ]
          }
        ]
      }
      ```

  </Accordion>

  <Accordion title="box/delete_folder">
    **الوصف:** حذف مجلد في Box.

    **المعاملات:**
    - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0").
    - `recursive` (boolean, اختياري): تكراري - حذف مجلد غير فارغ بحذف المجلد وجميع محتوياته تكرارياً.

  </Accordion>
</AccordionGroup>

## أمثلة الاستخدام

### إعداد Agent أساسي لـ Box

```python
from crewai import Agent, Task, Crew
from crewai import Agent, Task, Crew

# Create an agent with Box capabilities
box_agent = Agent(
    role="Document Manager",
    goal="Manage files and folders in Box efficiently",
    backstory="An AI assistant specialized in document management and file organization.",
    apps=['box']  # All Box actions will be available
)

# Task to create a folder structure
create_structure_task = Task(
    description="Create a folder called 'Project Files' in the root directory and upload a document from URL",
    agent=box_agent,
    expected_output="Folder created and file uploaded successfully"
)

# Run the task
crew = Crew(
    agents=[box_agent],
    tasks=[create_structure_task]
)

crew.kickoff()
```

### تصفية أدوات Box محددة

```python
from crewai import Agent, Task, Crew

# Create agent with specific Box actions only
file_organizer_agent = Agent(
    role="File Organizer",
    goal="Organize and manage file storage efficiently",
    backstory="An AI assistant that focuses on file organization and storage management.",
    apps=['box/create_folder', 'box/save_file', 'box/list_files']  # Specific Box actions
)

# Task to organize files
organization_task = Task(
    description="Create a folder structure for the marketing team and organize existing files",
    agent=file_organizer_agent,
    expected_output="Folder structure created and files organized"
)

crew = Crew(
    agents=[file_organizer_agent],
    tasks=[organization_task]
)

crew.kickoff()
```

### إدارة الملفات المتقدمة

```python
from crewai import Agent, Task, Crew

file_manager = Agent(
    role="File Manager",
    goal="Maintain organized file structure and manage document lifecycle",
    backstory="An experienced file manager who ensures documents are properly organized and accessible.",
    apps=['box']
)

# Complex task involving multiple Box operations
management_task = Task(
    description="""
    1. List all files in the root folder
    2. Create monthly archive folders for the current year
    3. Move old files to appropriate archive folders
    4. Generate a summary report of the file organization
    """,
    agent=file_manager,
    expected_output="Files organized into archive structure with summary report"
)

crew = Crew(
    agents=[file_manager],
    tasks=[management_task]
)

crew.kickoff()
```