S3 Reader Tool

`S3ReaderTool`

描述

S3ReaderTool 专为从 Amazon S3 存储桶读取文件而设计。这个工具让 CrewAI agents 能访问并读取存储在 S3 中的内容，非常适合需要读取数据、配置文件或任何其他 AWS S3 存储内容的工作流。

安装

要使用这个工具，需要安装所需依赖：

uv add boto3

入门步骤

要有效使用 S3ReaderTool，请按以下步骤操作：

安装依赖：使用上面的命令安装所需包。
配置 AWS 凭据：将 AWS 凭据设置为环境变量。
初始化工具：创建该工具的实例。
指定 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"})

参数

当由 agent 使用时，S3ReaderTool 接受以下参数：

file_path：必填。格式为 s3://bucket-name/file-name 的 S3 文件路径。

AWS 凭据

该工具需要 AWS 凭据才能访问 S3 存储桶。你可以通过环境变量配置这些凭据：

CREW_AWS_REGION：S3 存储桶所在的 AWS 区域。默认值为 us-east-1。
CREW_AWS_ACCESS_KEY_ID：你的 AWS access key ID。
CREW_AWS_SEC_ACCESS_KEY：你的 AWS secret access key。

用法

在 agent 中使用 S3ReaderTool 时，agent 需要提供 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 使用 Python 的 AWS SDK（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 存储桶读取文件的方式。通过让 agents 访问存储在 S3 中的内容，它为需要基于云的文件访问的工作流提供了支持。这个工具对于数据处理、配置管理以及任何涉及从 AWS S3 存储中检索信息的任务都非常有用。