أداة قراءة S3

S3ReaderTool

الوصف

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

التثبيت

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

uv add boto3

خطوات البدء

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

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

مثال

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

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:

# 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:

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.