---
title: أداة قراءة S3
description: تمكّن `S3ReaderTool` وكلاء CrewAI من قراءة الملفات من حاويات Amazon S3.
icon: aws
mode: "wide"
---

# `S3ReaderTool`

## الوصف

صُممت `S3ReaderTool` لقراءة الملفات من حاويات Amazon S3. تتيح هذه الأداة لوكلاء CrewAI الوصول إلى المحتوى المخزن في S3 واسترجاعه، مما يجعلها مثالية لسير العمل الذي يتطلب قراءة البيانات أو ملفات الإعداد أو أي محتوى آخر مخزن في تخزين AWS S3.

## التثبيت

لاستخدام هذه الأداة، تحتاج إلى تثبيت التبعيات المطلوبة:

```shell
uv add boto3
```

## خطوات البدء

لاستخدام `S3ReaderTool` بفعالية، اتبع الخطوات التالية:

1. **تثبيت التبعيات**: ثبّت الحزم المطلوبة باستخدام الأمر أعلاه.
2. **إعداد بيانات اعتماد AWS**: عيّن بيانات اعتماد AWS كمتغيرات بيئة.
3. **تهيئة الأداة**: أنشئ مثيلاً من الأداة.
4. **تحديد مسار S3**: قدّم مسار S3 للملف المراد قراءته.

## مثال

يوضح المثال التالي كيفية استخدام `S3ReaderTool` لقراءة ملف من حاوية S3:

```python Code
from crewai import Agent, Task, Crew
from crewai_tools.aws.s3 import S3ReaderTool

# Initialize the tool
s3_reader_tool = S3ReaderTool()

# Define an agent that uses the tool
file_reader_agent = Agent(
    role="File Reader",
    goal="Read files from S3 buckets",
    backstory="An expert in retrieving and processing files from cloud storage.",
    tools=[s3_reader_tool],
    verbose=True,
)

# Example task to read a configuration file
read_task = Task(
    description="Read the configuration file from {my_bucket} and summarize its contents.",
    expected_output="A summary of the configuration file contents.",
    agent=file_reader_agent,
)

# Create and run the crew
crew = Crew(agents=[file_reader_agent], tasks=[read_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"})
```

## المعاملات

تقبل `S3ReaderTool` المعامل التالي عند استخدامها من قبل وكيل:

- **file_path**: مطلوب. مسار ملف S3 بتنسيق `s3://bucket-name/file-name`.

## بيانات اعتماد AWS

تتطلب الأداة بيانات اعتماد AWS للوصول إلى حاويات S3. يمكنك إعداد هذه البيانات باستخدام متغيرات البيئة:

- **CREW_AWS_REGION**: منطقة AWS حيث تقع حاوية S3. القيمة الافتراضية `us-east-1`.
- **CREW_AWS_ACCESS_KEY_ID**: معرّف مفتاح الوصول لـ AWS.
- **CREW_AWS_SEC_ACCESS_KEY**: مفتاح الوصول السري لـ AWS.

## الاستخدام

عند استخدام `S3ReaderTool` مع وكيل، سيحتاج الوكيل لتقديم مسار ملف S3:

```python Code
# Example of using the tool with an agent
file_reader_agent = Agent(
    role="File Reader",
    goal="Read files from S3 buckets",
    backstory="An expert in retrieving and processing files from cloud storage.",
    tools=[s3_reader_tool],
    verbose=True,
)

# Create a task for the agent to read a specific file
read_config_task = Task(
    description="Read the application configuration file from {my_bucket} and extract the database connection settings.",
    expected_output="The database connection settings from the configuration file.",
    agent=file_reader_agent,
)

# Run the task
crew = Crew(agents=[file_reader_agent], tasks=[read_config_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"})
```

## معالجة الأخطاء

تتضمن `S3ReaderTool` معالجة أخطاء لمشكلات S3 الشائعة:

- تنسيق مسار S3 غير صالح
- ملفات مفقودة أو غير قابلة للوصول
- مشكلات الأذونات
- مشكلات بيانات اعتماد AWS

عند حدوث خطأ، ستعيد الأداة رسالة خطأ تتضمن تفاصيل حول المشكلة.

## تفاصيل التنفيذ

تستخدم `S3ReaderTool` حزمة AWS SDK لـ Python (boto3) للتفاعل مع S3:

```python Code
class S3ReaderTool(BaseTool):
    name: str = "S3 Reader Tool"
    description: str = "Reads a file from Amazon S3 given an S3 file path"

    def _run(self, file_path: str) -> str:
        try:
            bucket_name, object_key = self._parse_s3_path(file_path)

            s3 = boto3.client(
                's3',
                region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'),
                aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'),
                aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY')
            )

            # Read file content from S3
            response = s3.get_object(Bucket=bucket_name, Key=object_key)
            file_content = response['Body'].read().decode('utf-8')

            return file_content
        except ClientError as e:
            return f"Error reading file from S3: {str(e)}"
```

## الخلاصة

توفر `S3ReaderTool` طريقة مباشرة لقراءة الملفات من حاويات Amazon S3. من خلال تمكين الوكلاء من الوصول إلى المحتوى المخزن في S3، تسهّل سير العمل الذي يتطلب وصولاً سحابياً للملفات. هذه الأداة مفيدة بشكل خاص لمعالجة البيانات وإدارة الإعدادات وأي مهمة تتضمن استرجاع المعلومات من تخزين AWS S3.