mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-03 14:09:24 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
166
docs/edge/ko/tools/cloud-storage/bedrockkbretriever.mdx
Normal file
166
docs/edge/ko/tools/cloud-storage/bedrockkbretriever.mdx
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: 'Bedrock 지식 베이스 검색기'
|
||||
description: '자연어 쿼리를 사용하여 Amazon Bedrock 지식 베이스에서 정보를 검색합니다'
|
||||
icon: aws
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `BedrockKBRetrieverTool`
|
||||
|
||||
`BedrockKBRetrieverTool`은 CrewAI 에이전트가 자연어 쿼리를 사용하여 Amazon Bedrock Knowledge Bases에서 정보를 검색할 수 있도록 합니다.
|
||||
|
||||
## 설치
|
||||
|
||||
```bash
|
||||
uv pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## 요구 사항
|
||||
|
||||
- AWS 자격 증명이 구성되어 있음 (환경 변수 또는 AWS CLI를 통해)
|
||||
- `boto3` 및 `python-dotenv` 패키지
|
||||
- Amazon Bedrock Knowledge Base에 대한 액세스
|
||||
|
||||
## 사용법
|
||||
|
||||
CrewAI agent와 함께 이 도구를 사용하는 방법은 다음과 같습니다:
|
||||
|
||||
```python {2, 4-17}
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool
|
||||
|
||||
# Initialize the tool
|
||||
kb_tool = BedrockKBRetrieverTool(
|
||||
knowledge_base_id="your-kb-id",
|
||||
number_of_results=5
|
||||
)
|
||||
|
||||
# Create a CrewAI agent that uses the tool
|
||||
researcher = Agent(
|
||||
role='Knowledge Base Researcher',
|
||||
goal='Find information about company policies',
|
||||
backstory='I am a researcher specialized in retrieving and analyzing company documentation.',
|
||||
tools=[kb_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Create a task for the agent
|
||||
research_task = Task(
|
||||
description="Find our company's remote work policy and summarize the key points.",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
# Create a crew with the agent
|
||||
crew = Crew(
|
||||
agents=[researcher],
|
||||
tasks=[research_task],
|
||||
verbose=2
|
||||
)
|
||||
|
||||
# Run the crew
|
||||
result = crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
## 도구 인자
|
||||
|
||||
| 인자 | 타입 | 필수 여부 | 기본값 | 설명 |
|
||||
|:---------|:-----|:---------|:---------|:-------------|
|
||||
| **knowledge_base_id** | `str` | 예 | 없음 | 지식 베이스의 고유 식별자 (0-10자리 영숫자) |
|
||||
| **number_of_results** | `int` | 아니오 | 5 | 반환할 최대 결과 개수 |
|
||||
| **retrieval_configuration** | `dict` | 아니오 | 없음 | 지식 베이스 쿼리를 위한 사용자 지정 설정 |
|
||||
| **guardrail_configuration** | `dict` | 아니오 | 없음 | 콘텐츠 필터링 설정 |
|
||||
| **next_token** | `str` | 아니오 | 없음 | 페이지네이션을 위한 토큰 |
|
||||
|
||||
## 환경 변수
|
||||
|
||||
```bash
|
||||
BEDROCK_KB_ID=your-knowledge-base-id # Alternative to passing knowledge_base_id
|
||||
AWS_REGION=your-aws-region # Defaults to us-east-1
|
||||
AWS_ACCESS_KEY_ID=your-access-key # Required for AWS authentication
|
||||
AWS_SECRET_ACCESS_KEY=your-secret-key # Required for AWS authentication
|
||||
```
|
||||
|
||||
## 응답 형식
|
||||
|
||||
도구는 결과를 JSON 형식으로 반환합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"content": "Retrieved text content",
|
||||
"content_type": "text",
|
||||
"source_type": "S3",
|
||||
"source_uri": "s3://bucket/document.pdf",
|
||||
"score": 0.95,
|
||||
"metadata": {
|
||||
"additional": "metadata"
|
||||
}
|
||||
}
|
||||
],
|
||||
"nextToken": "pagination-token",
|
||||
"guardrailAction": "NONE"
|
||||
}
|
||||
```
|
||||
|
||||
## 고급 사용법
|
||||
|
||||
### 사용자 지정 검색 구성
|
||||
|
||||
```python
|
||||
kb_tool = BedrockKBRetrieverTool(
|
||||
knowledge_base_id="your-kb-id",
|
||||
retrieval_configuration={
|
||||
"vectorSearchConfiguration": {
|
||||
"numberOfResults": 10,
|
||||
"overrideSearchType": "HYBRID"
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
policy_expert = Agent(
|
||||
role='Policy Expert',
|
||||
goal='Analyze company policies in detail',
|
||||
backstory='I am an expert in corporate policy analysis with deep knowledge of regulatory requirements.',
|
||||
tools=[kb_tool]
|
||||
)
|
||||
```
|
||||
|
||||
## 지원되는 데이터 소스
|
||||
|
||||
- Amazon S3
|
||||
- Confluence
|
||||
- Salesforce
|
||||
- SharePoint
|
||||
- 웹 페이지
|
||||
- 사용자 지정 문서 위치
|
||||
- Amazon Kendra
|
||||
- SQL 데이터베이스
|
||||
|
||||
## 사용 사례
|
||||
|
||||
### 엔터프라이즈 지식 통합
|
||||
- 민감한 데이터를 노출하지 않고도 CrewAI 에이전트가 귀사의 독점 지식에 접근할 수 있도록 합니다.
|
||||
- 에이전트가 귀사의 특정 정책, 절차 및 문서를 기반으로 의사 결정을 내릴 수 있도록 허용합니다.
|
||||
- 데이터 보안을 유지하면서 내부 문서를 기반으로 질문에 답변할 수 있는 에이전트를 생성합니다.
|
||||
|
||||
### 전문 분야 지식
|
||||
- CrewAI 에이전트를 도메인별 지식 베이스(법률, 의료, 기술 등)에 재학습 없이 연결할 수 있습니다
|
||||
- 이미 AWS 환경에서 관리되고 있는 기존 지식 저장소를 활용할 수 있습니다
|
||||
- CrewAI의 추론과 지식 베이스의 도메인별 정보를 결합할 수 있습니다
|
||||
|
||||
### 데이터 기반 의사결정
|
||||
- Ground CrewAI 에이전트 응답을 일반 지식이 아닌 실제 회사 데이터에 기반하게 하세요
|
||||
- 에이전트가 귀사의 특정 비즈니스 맥락과 문서를 바탕으로 추천을 제공하도록 보장하세요
|
||||
- 지식 기반에서 사실 정보를 검색하여 환각을 줄이세요
|
||||
|
||||
### 확장 가능한 정보 접근
|
||||
- 모델에 모든 지식을 삽입하지 않고도 조직의 테라바이트급 지식에 접근할 수 있습니다.
|
||||
- 특정 작업에 필요한 관련 정보만 동적으로 쿼리합니다.
|
||||
- 대규모 지식 베이스를 효율적으로 처리하기 위해 AWS의 확장 가능한 인프라를 활용합니다.
|
||||
|
||||
### 컴플라이언스 및 거버넌스
|
||||
- CrewAI 에이전트가 회사의 승인된 문서에 부합하는 응답을 제공하도록 보장하십시오
|
||||
- 에이전트가 사용한 정보 출처에 대한 감사 가능한 기록을 만드십시오
|
||||
- 에이전트가 접근할 수 있는 정보 출처를 제어하십시오
|
||||
52
docs/edge/ko/tools/cloud-storage/overview.mdx
Normal file
52
docs/edge/ko/tools/cloud-storage/overview.mdx
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: "개요"
|
||||
description: "클라우드 서비스, 스토리지 시스템, 클라우드 기반 AI 플랫폼과 상호작용합니다"
|
||||
icon: "face-smile"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이러한 도구를 통해 에이전트는 클라우드 서비스와 상호 작용하고, 클라우드 스토리지에 접근하며, 대규모 운영을 위해 클라우드 기반 AI 플랫폼을 활용할 수 있습니다.
|
||||
|
||||
## **사용 가능한 도구**
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="S3 리더 도구" icon="cloud" href="/ko/tools/cloud-storage/s3readertool">
|
||||
Amazon S3 버킷에서 파일과 데이터를 읽습니다.
|
||||
</Card>
|
||||
|
||||
<Card title="S3 라이터 도구" icon="cloud-arrow-up" href="/ko/tools/cloud-storage/s3writertool">
|
||||
파일을 Amazon S3 스토리지에 작성하고 업로드합니다.
|
||||
</Card>
|
||||
|
||||
<Card title="Bedrock Invoke Agent" icon="aws" href="/ko/tools/integration/bedrockinvokeagenttool">
|
||||
AI 기반 작업을 위해 Amazon Bedrock 에이전트를 호출합니다.
|
||||
</Card>
|
||||
|
||||
<Card title="Bedrock KB Retriever" icon="database" href="/ko/tools/cloud-storage/bedrockkbretriever">
|
||||
Amazon Bedrock 지식 베이스에서 정보를 검색합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## **일반적인 사용 사례**
|
||||
|
||||
- **파일 저장**: 클라우드 스토리지 시스템에 파일을 저장하고 가져오기
|
||||
- **데이터 백업**: 중요한 데이터를 클라우드 스토리지에 백업하기
|
||||
- **AI 서비스**: 클라우드 기반의 AI 모델 및 서비스에 접근하기
|
||||
- **지식 검색**: 클라우드에 호스팅된 지식 베이스를 질의하기
|
||||
- **확장 가능한 운영**: 처리 작업을 위해 클라우드 인프라 활용하기
|
||||
|
||||
```python
|
||||
from crewai_tools import S3ReaderTool, S3WriterTool, BedrockInvokeAgentTool
|
||||
|
||||
# Create cloud tools
|
||||
s3_reader = S3ReaderTool()
|
||||
s3_writer = S3WriterTool()
|
||||
bedrock_agent = BedrockInvokeAgentTool()
|
||||
|
||||
# Add to your agent
|
||||
agent = Agent(
|
||||
role="Cloud Operations Specialist",
|
||||
tools=[s3_reader, s3_writer, bedrock_agent],
|
||||
goal="Manage cloud resources and AI services"
|
||||
)
|
||||
```
|
||||
145
docs/edge/ko/tools/cloud-storage/s3readertool.mdx
Normal file
145
docs/edge/ko/tools/cloud-storage/s3readertool.mdx
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
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://bucket-name/file-name` 형식의 S3 파일 경로입니다.
|
||||
|
||||
## AWS 자격 증명
|
||||
|
||||
이 도구는 S3 버킷에 접근하기 위해 AWS 자격 증명이 필요합니다. 환경 변수를 사용하여 이러한 자격 증명을 구성할 수 있습니다:
|
||||
|
||||
- **CREW_AWS_REGION**: S3 버킷이 위치한 AWS 리전입니다. 기본값은 `us-east-1`입니다.
|
||||
- **CREW_AWS_ACCESS_KEY_ID**: AWS 액세스 키 ID입니다.
|
||||
- **CREW_AWS_SEC_ACCESS_KEY**: AWS 시크릿 액세스 키입니다.
|
||||
|
||||
## 사용법
|
||||
|
||||
`S3ReaderTool`을 agent와 함께 사용할 때, agent는 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 for 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 스토리지에서 정보를 검색하는 모든 작업에 특히 유용합니다.
|
||||
151
docs/edge/ko/tools/cloud-storage/s3writertool.mdx
Normal file
151
docs/edge/ko/tools/cloud-storage/s3writertool.mdx
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: S3 Writer Tool
|
||||
description: S3WriterTool은 CrewAI 에이전트가 Amazon S3 버킷의 파일에 콘텐츠를 쓸 수 있도록 해줍니다.
|
||||
icon: aws
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# `S3WriterTool`
|
||||
|
||||
## 설명
|
||||
|
||||
`S3WriterTool`은 Amazon S3 버킷의 파일에 콘텐츠를 기록하도록 설계되었습니다. 이 도구를 사용하면 CrewAI 에이전트가 S3에서 파일을 생성하거나 업데이트할 수 있어, 데이터를 저장하거나 구성 파일을 저장하거나 기타 콘텐츠를 AWS S3 스토리지에 영구적으로 보관해야 하는 워크플로우에 이상적입니다.
|
||||
|
||||
## 설치
|
||||
|
||||
이 도구를 사용하려면 필요한 종속성을 설치해야 합니다:
|
||||
|
||||
```shell
|
||||
uv add boto3
|
||||
```
|
||||
|
||||
## 시작 단계
|
||||
|
||||
`S3WriterTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
|
||||
|
||||
1. **필수 패키지 설치**: 위 명령어를 사용하여 필요한 패키지를 설치합니다.
|
||||
2. **AWS 자격 증명 구성**: 환경 변수로 AWS 자격 증명을 설정합니다.
|
||||
3. **도구 초기화**: 도구의 인스턴스를 생성합니다.
|
||||
4. **S3 경로 및 내용 지정**: 파일을 작성할 S3 경로와 작성할 내용을 제공합니다.
|
||||
|
||||
## 예시
|
||||
|
||||
다음 예시는 `S3WriterTool`을 사용하여 S3 버킷의 파일에 콘텐츠를 쓰는 방법을 보여줍니다:
|
||||
|
||||
```python Code
|
||||
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"})
|
||||
```
|
||||
|
||||
## 파라미터
|
||||
|
||||
`S3WriterTool`은 에이전트가 사용할 때 다음 파라미터를 허용합니다:
|
||||
|
||||
- **file_path**: 필수. `s3://bucket-name/file-name` 형식의 S3 파일 경로입니다.
|
||||
- **content**: 필수. 파일에 쓸 내용입니다.
|
||||
|
||||
## AWS 자격 증명
|
||||
|
||||
이 도구는 S3 버킷에 접근하기 위해 AWS 자격 증명이 필요합니다. 다음과 같이 환경 변수로 자격 증명을 설정할 수 있습니다:
|
||||
|
||||
- **CREW_AWS_REGION**: S3 버킷이 위치한 AWS 리전. 기본값은 `us-east-1`입니다.
|
||||
- **CREW_AWS_ACCESS_KEY_ID**: AWS 액세스 키 ID.
|
||||
- **CREW_AWS_SEC_ACCESS_KEY**: AWS 시크릿 액세스 키.
|
||||
|
||||
## 사용법
|
||||
|
||||
`S3WriterTool`을 agent와 함께 사용할 때, agent는 S3 파일 경로와 작성할 내용을 모두 제공해야 합니다:
|
||||
|
||||
```python Code
|
||||
# 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"})
|
||||
```
|
||||
|
||||
## 오류 처리
|
||||
|
||||
`S3WriterTool`은 일반적인 S3 문제에 대한 오류 처리를 포함합니다:
|
||||
|
||||
- 잘못된 S3 경로 형식
|
||||
- 권한 문제(예: 버킷에 대한 쓰기 권한 없음)
|
||||
- AWS 자격 증명 문제
|
||||
- 버킷이 존재하지 않음
|
||||
|
||||
오류가 발생하면 도구는 문제에 대한 세부 정보가 포함된 오류 메시지를 반환합니다.
|
||||
|
||||
## 구현 세부 정보
|
||||
|
||||
`S3WriterTool`은 S3와 상호 작용하기 위해 AWS SDK for Python(boto3)를 사용합니다:
|
||||
|
||||
```python Code
|
||||
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)}"
|
||||
```
|
||||
|
||||
## 결론
|
||||
|
||||
`S3WriterTool`은 Amazon S3 버킷의 파일에 콘텐츠를 간편하게 작성할 수 있는 방법을 제공합니다. 이 도구를 통해 에이전트가 S3에서 파일을 생성하고 업데이트할 수 있어 클라우드 기반 파일 저장소가 필요한 워크플로우를 지원합니다. 이 도구는 데이터 영속성, 구성 관리, 보고서 생성 및 AWS S3 저장소에 정보를 저장해야 하는 작업에 특히 유용합니다.
|
||||
Reference in New Issue
Block a user