S3 Reader Tool

S3 Reader Tool

S3ReaderTool은 CrewAI 에이전트가 Amazon S3 버킷에서 파일을 읽을 수 있게 해주는 도구예요.

출처: 문서

본문

S3ReaderTool

설명 (Description)

S3ReaderTool은 Amazon S3 버킷에서 파일을 읽도록 설계되었어요. 이 도구를 사용하면 CrewAI 에이전트가 S3에 저장된 콘텐츠에 접근하고 검색할 수 있어서, AWS S3 스토리지에 저장된 데이터·설정 파일·기타 콘텐츠를 읽어야 하는 워크플로에 이상적입니다.

설치 (Installation)

이 도구를 사용하려면 필수 의존성을 설치해야 합니다:

uv add boto3

시작하기 위한 단계 (Steps to Get Started)

S3ReaderTool을 효과적으로 사용하려면 다음 단계를 따라주세요:

  • 의존성 설치 — 위 명령으로 필요한 패키지를 설치하세요.
  • AWS 자격 증명 구성 — AWS 자격 증명을 환경 변수로 설정하세요.
  • 도구 초기화 — 도구의 인스턴스를 만드세요.
  • S3 경로 지정 — 읽으려는 파일의 S3 경로를 제공하세요.

예제 (Example)

다음 예제는 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"})

파라미터 (Parameters)

S3ReaderTool은 에이전트가 사용할 때 다음 파라미터를 받습니다:

  • file_path: 필수. s3://bucket-name/file-name 형식의 S3 파일 경로.

AWS 자격 증명 (AWS Credentials)

도구는 S3 버킷에 접근하려면 AWS 자격 증명이 필요합니다. 환경 변수로 구성할 수 있어요:

  • CREW_AWS_REGION: S3 버킷이 위치한 AWS 리전. 기본값은 us-east-1.
  • CREW_AWS_ACCESS_KEY_ID: AWS 액세스 키 ID.
  • CREW_AWS_SEC_ACCESS_KEY: AWS 시크릿 액세스 키.

사용법 (Usage)

에이전트와 함께 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"})

에러 처리 (Error Handling)

S3ReaderTool은 일반적인 S3 문제에 대한 에러 처리를 포함합니다:

  • 잘못된 S3 경로 형식
  • 누락되었거나 접근할 수 없는 파일
  • 권한 문제
  • AWS 자격 증명 문제

에러가 발생하면 도구는 문제에 대한 세부 정보를 포함한 에러 메시지를 반환합니다.

구현 세부사항 (Implementation Details)

S3ReaderTool은 AWS SDK for 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)}"

결론 (Conclusion)

S3ReaderTool은 Amazon S3 버킷에서 파일을 읽는 간단한 방법을 제공합니다. 에이전트가 S3에 저장된 콘텐츠에 접근할 수 있게 함으로써 클라우드 기반 파일 접근이 필요한 워크플로를 지원합니다. 이 도구는 데이터 처리, 설정 관리, 그리고 AWS S3 스토리지에서 정보를 검색하는 모든 태스크에 특히 유용합니다.

더 알아보기 (Learn more)