S3 Writer Tool

S3 Writer Tool

S3WriterTool은 CrewAI 에이전트가 Amazon S3 버킷의 파일에 콘텐츠를 쓸 수 있게 해주는 도구예요.

출처: 문서

본문

S3WriterTool

설명 (Description)

S3WriterTool은 Amazon S3 버킷의 파일에 콘텐츠를 쓰도록 설계되었어요. 이 도구를 사용하면 CrewAI 에이전트가 S3에서 파일을 만들거나 업데이트할 수 있어서, 데이터를 저장하거나, 설정 파일을 저장하거나, 다른 콘텐츠를 AWS S3 스토리지에 영속화해야 하는 워크플로에 이상적입니다.

설치 (Installation)

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

uv add boto3

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

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

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

예제 (Example)

다음 예제는 S3WriterTool을 사용해 S3 버킷의 파일에 콘텐츠를 쓰는 방법을 보여줍니다:

from crewai import Agent, Task, Crew
from crewai_tools.aws.s3 import S3WriterTool

# Initialize the tool
s3_writer_tool = S3WriterTool()

# Define an agent that uses the tool
file_writer_agent = Agent(
    role="File Writer",
    goal="Write content to files in S3 buckets",
    backstory="An expert in storing and managing files in cloud storage.",
    tools=[s3_writer_tool],
    verbose=True,
)

# Example task to write a report
write_task = Task(
    description="Generate a summary report of the quarterly sales data and save it to {my_bucket}.",
    expected_output="Confirmation that the report was successfully saved to S3.",
    agent=file_writer_agent,
)

# Create and run the crew
crew = Crew(agents=[file_writer_agent], tasks=[write_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/reports/quarterly-summary.txt"})

파라미터 (Parameters)

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

  • file_path: 필수. s3://bucket-name/file-name 형식의 S3 파일 경로.
  • content: 필수. 파일에 쓸 콘텐츠.

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)

에이전트와 함께 S3WriterTool을 사용할 때, 에이전트는 S3 파일 경로와 쓸 콘텐츠를 모두 제공해야 합니다:

# Example of using the tool with an agent
file_writer_agent = Agent(
    role="File Writer",
    goal="Write content to files in S3 buckets",
    backstory="An expert in storing and managing files in cloud storage.",
    tools=[s3_writer_tool],
    verbose=True,
)

# Create a task for the agent to write a specific file
write_config_task = Task(
    description="""
    Create a configuration file with the following database settings:
    - host: db.example.com
    - port: 5432
    - username: app_user
    - password: secure_password
    
    Save this configuration as JSON to {my_bucket}.
    """,
    expected_output="Confirmation that the configuration file was successfully saved to S3.",
    agent=file_writer_agent,
)

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

에러 처리 (Error Handling)

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

  • 잘못된 S3 경로 형식
  • 권한 문제 (예: 버킷에 대한 쓰기 접근 권한 없음)
  • AWS 자격 증명 문제
  • 버킷이 존재하지 않음

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

구현 세부사항 (Implementation Details)

S3WriterTool은 AWS SDK for Python(boto3)을 사용해 S3와 상호작용합니다:

class S3WriterTool(BaseTool):
    name: str = "S3 Writer Tool"
    description: str = "Writes content to a file in Amazon S3 given an S3 file path"
    
    def _run(self, file_path: str, content: 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')
            )

            s3.put_object(Bucket=bucket_name, Key=object_key, Body=content.encode('utf-8'))
            return f"Successfully wrote content to {file_path}"
        except ClientError as e:
            return f"Error writing file to S3: {str(e)}"

결론 (Conclusion)

S3WriterTool은 Amazon S3 버킷의 파일에 콘텐츠를 쓰는 간단한 방법을 제공합니다. 에이전트가 S3에서 파일을 만들고 업데이트할 수 있게 함으로써 클라우드 기반 파일 스토리지가 필요한 워크플로를 지원합니다. 이 도구는 데이터 영속화, 설정 관리, 리포트 생성, 그리고 AWS S3 스토리지에 정보를 저장하는 모든 태스크에 특히 유용합니다.

더 알아보기 (Learn more)