mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-02 13:48:09 +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
8
docs/edge/ko/api-reference/inputs.mdx
Normal file
8
docs/edge/ko/api-reference/inputs.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "GET /inputs"
|
||||
description: "크루가 필요로 하는 입력 확인"
|
||||
openapi: "/enterprise-api.ko.yaml GET /inputs"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
135
docs/edge/ko/api-reference/introduction.mdx
Normal file
135
docs/edge/ko/api-reference/introduction.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: "소개"
|
||||
description: "CrewAI AMP REST API에 대한 완벽한 참고 자료"
|
||||
icon: "code"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# CrewAI 엔터프라이즈 API
|
||||
|
||||
CrewAI 엔터프라이즈 API 참고 자료에 오신 것을 환영합니다. 이 API를 사용하면 배포된 crew와 프로그래밍 방식으로 상호작용할 수 있어, 애플리케이션, 워크플로우 및 서비스와의 통합이 가능합니다.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
<Steps>
|
||||
<Step title="API 자격 증명 받기">
|
||||
CrewAI AMP 대시보드에서 자신의 crew 상세 페이지로 이동하여 Status 탭에서 Bearer Token을 복사하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="필수 입력값 확인하기">
|
||||
`GET /inputs` 엔드포인트를 사용하여 crew가 기대하는 파라미터를 확인하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="Crew 실행 시작하기">
|
||||
입력값과 함께 `POST /kickoff`를 호출하여 crew 실행을 시작하고 `kickoff_id`를
|
||||
받으세요.
|
||||
</Step>
|
||||
|
||||
<Step title="진행 상황 모니터링">
|
||||
`GET /status/{kickoff_id}`를 사용하여 실행 상태를 확인하고 결과를 조회하세요.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 인증
|
||||
|
||||
모든 API 요청은 Bearer 토큰을 사용한 인증이 필요합니다. `Authorization` 헤더에 토큰을 포함하세요:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
https://your-crew-url.crewai.com/inputs
|
||||
```
|
||||
|
||||
### 토큰 유형
|
||||
|
||||
| 토큰 유형 | 범위 | 사용 사례 |
|
||||
| :-------------------- | :--------------- | :------------------------------------ |
|
||||
| **Bearer Token** | 조직 단위 접근 | 전체 crew 운영, 서버 간 통합에 이상적 |
|
||||
| **User Bearer Token** | 사용자 범위 접근 | 제한된 권한, 사용자별 작업에 적합 |
|
||||
|
||||
<Tip>
|
||||
두 토큰 유형 모두 CrewAI AMP 대시보드의 crew 상세 페이지 Status 탭에서 확인할
|
||||
수 있습니다.
|
||||
</Tip>
|
||||
|
||||
## 기본 URL
|
||||
|
||||
각 배포된 crew마다 고유한 API 엔드포인트가 있습니다:
|
||||
|
||||
```
|
||||
https://your-crew-name.crewai.com
|
||||
```
|
||||
|
||||
`your-crew-name`을(를) 대시보드에서 확인할 수 있는 실제 crew의 URL로 교체하세요.
|
||||
|
||||
## 일반적인 워크플로우
|
||||
|
||||
1. **탐색**: `GET /inputs`를 호출하여 crew가 필요한 것을 파악합니다.
|
||||
2. **실행**: `POST /kickoff`를 통해 입력값을 제출하여 처리를 시작합니다.
|
||||
3. **모니터링**: 완료될 때까지 `GET /status/{kickoff_id}`를 주기적으로 조회합니다.
|
||||
4. **결과**: 완료된 응답에서 최종 출력을 추출합니다.
|
||||
|
||||
## 오류 처리
|
||||
|
||||
API는 표준 HTTP 상태 코드를 사용합니다:
|
||||
|
||||
| 코드 | 의미 |
|
||||
| ----- | :------------------------------------ |
|
||||
| `200` | 성공 |
|
||||
| `400` | 잘못된 요청 - 잘못된 입력 형식 |
|
||||
| `401` | 인증 실패 - 잘못된 베어러 토큰 |
|
||||
| `404` | 찾을 수 없음 - 리소스가 존재하지 않음 |
|
||||
| `422` | 유효성 검사 오류 - 필수 입력 누락 |
|
||||
| `500` | 서버 오류 - 지원팀에 문의하십시오 |
|
||||
|
||||
## 인터랙티브 테스트
|
||||
|
||||
<Info>
|
||||
**왜 "전송" 버튼이 없나요?** 각 CrewAI AMP 사용자는 고유한 crew URL을
|
||||
가지므로, 혼동을 피하기 위해 인터랙티브 플레이그라운드 대신 **참조 모드**를
|
||||
사용합니다. 이를 통해 비작동 전송 버튼 없이 요청이 어떻게 생겼는지 정확히
|
||||
보여줍니다.
|
||||
</Info>
|
||||
|
||||
각 엔드포인트 페이지에서는 다음을 확인할 수 있습니다:
|
||||
|
||||
- ✅ 모든 파라미터가 포함된 **정확한 요청 형식**
|
||||
- ✅ 성공 및 오류 사례에 대한 **응답 예시**
|
||||
- ✅ 여러 언어(cURL, Python, JavaScript 등)로 제공되는 **코드 샘플**
|
||||
- ✅ 올바른 Bearer 토큰 형식의 **인증 예시**
|
||||
|
||||
### **실제 API를 테스트하려면:**
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="cURL 예제 복사" icon="terminal">
|
||||
cURL 예제를 복사한 후, URL과 토큰을 실제 값으로 교체하세요
|
||||
</Card>
|
||||
<Card title="Postman/Insomnia 사용" icon="play">
|
||||
예제를 원하는 API 테스트 도구에 가져오세요
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
**예시 작업 흐름:**
|
||||
|
||||
1. **cURL 예제를 복사**합니다 (엔드포인트 페이지에서)
|
||||
2. **`your-actual-crew-name.crewai.com`**을(를) 실제 crew URL로 교체합니다
|
||||
3. **Bearer 토큰을** 대시보드에서 복사한 실제 토큰으로 교체합니다
|
||||
4. **요청을 실행**합니다 (터미널이나 API 클라이언트에서)
|
||||
|
||||
## 도움이 필요하신가요?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Enterprise Support"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
API 통합 및 문제 해결에 대한 지원을 받으세요
|
||||
</Card>
|
||||
<Card
|
||||
title="Enterprise Dashboard"
|
||||
icon="chart-line"
|
||||
href="https://app.crewai.com"
|
||||
>
|
||||
crew를 관리하고 실행 로그를 확인하세요
|
||||
</Card>
|
||||
</CardGroup>
|
||||
8
docs/edge/ko/api-reference/kickoff.mdx
Normal file
8
docs/edge/ko/api-reference/kickoff.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "POST /kickoff"
|
||||
description: "크루 실행 시작"
|
||||
openapi: "/enterprise-api.ko.yaml POST /kickoff"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
6
docs/edge/ko/api-reference/resume.mdx
Normal file
6
docs/edge/ko/api-reference/resume.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "POST /resume"
|
||||
description: "인간 피드백으로 crew 실행 재개"
|
||||
openapi: "/enterprise-api.ko.yaml POST /resume"
|
||||
mode: "wide"
|
||||
---
|
||||
6
docs/edge/ko/api-reference/status.mdx
Normal file
6
docs/edge/ko/api-reference/status.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "GET /status/{kickoff_id}"
|
||||
description: "실행 상태 조회"
|
||||
openapi: "/enterprise-api.ko.yaml GET /status/{kickoff_id}"
|
||||
mode: "wide"
|
||||
---
|
||||
4374
docs/edge/ko/changelog.mdx
Normal file
4374
docs/edge/ko/changelog.mdx
Normal file
File diff suppressed because it is too large
Load Diff
147
docs/edge/ko/concepts/agent-capabilities.mdx
Normal file
147
docs/edge/ko/concepts/agent-capabilities.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "에이전트 기능"
|
||||
description: "CrewAI 에이전트를 확장하는 다섯 가지 방법 이해하기: 도구, MCP, 앱, 스킬, 지식."
|
||||
icon: puzzle-piece
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI 에이전트는 **다섯 가지 고유한 기능 유형**으로 확장할 수 있으며, 각각 다른 목적을 가지고 있습니다. 각 유형을 언제 사용해야 하는지, 그리고 어떻게 함께 작동하는지 이해하는 것이 효과적인 에이전트를 구축하는 핵심입니다.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="도구" icon="wrench" href="/ko/concepts/tools" color="#3B82F6">
|
||||
**호출 가능한 함수** — 에이전트가 행동을 취할 수 있게 합니다. 웹 검색, 파일 작업, API 호출, 코드 실행.
|
||||
</Card>
|
||||
<Card title="MCP 서버" icon="plug" href="/ko/mcp/overview" color="#8B5CF6">
|
||||
**원격 도구 서버** — Model Context Protocol을 통해 에이전트를 외부 도구 서버에 연결합니다. 도구와 같은 효과이지만 외부에서 호스팅됩니다.
|
||||
</Card>
|
||||
<Card title="앱" icon="grid-2" color="#EC4899">
|
||||
**플랫폼 통합** — CrewAI 플랫폼을 통해 에이전트를 SaaS 앱(Gmail, Slack, Jira, Salesforce)에 연결합니다. 플랫폼 통합 토큰으로 로컬에서 실행됩니다.
|
||||
</Card>
|
||||
<Card title="스킬" icon="bolt" href="/ko/concepts/skills" color="#F59E0B">
|
||||
**도메인 전문성** — 에이전트 프롬프트에 지침, 가이드라인 및 참조 자료를 주입합니다. 스킬은 에이전트에게 *어떻게 생각할지*를 알려줍니다.
|
||||
</Card>
|
||||
<Card title="지식" icon="book" href="/ko/concepts/knowledge" color="#10B981">
|
||||
**검색된 사실** — 시맨틱 검색(RAG)을 통해 문서, 파일 및 URL에서 에이전트에게 데이터를 제공합니다. 지식은 에이전트에게 *무엇을 알아야 하는지*를 제공합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## 핵심 구분
|
||||
|
||||
가장 중요한 점: **이 기능들은 두 가지 범주로 나뉩니다**.
|
||||
|
||||
### 액션 기능 (도구, MCP, 앱)
|
||||
|
||||
에이전트에게 **무언가를 할 수 있는** 능력을 부여합니다 — API 호출, 파일 읽기, 웹 검색, 이메일 전송. 실행 시점에 세 가지 모두 동일한 내부 형식(`BaseTool` 인스턴스)으로 변환되며, 에이전트가 호출할 수 있는 통합 도구 목록에 나타납니다.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool
|
||||
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find and compile market data",
|
||||
backstory="Expert market analyst",
|
||||
tools=[SerperDevTool(), FileReadTool()], # 로컬 도구
|
||||
mcps=["https://mcp.example.com/sse"], # 원격 MCP 서버 도구
|
||||
apps=["gmail", "google_sheets"], # 플랫폼 통합
|
||||
)
|
||||
```
|
||||
|
||||
### 컨텍스트 기능 (스킬, 지식)
|
||||
|
||||
에이전트의 **프롬프트**를 수정합니다 — 에이전트가 추론을 시작하기 전에 전문성, 지침 또는 검색된 데이터를 주입합니다. 에이전트에게 새로운 액션을 제공하는 것이 아니라, 에이전트가 어떻게 생각하고 어떤 정보에 접근할 수 있는지를 형성합니다.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Security Auditor",
|
||||
goal="Audit cloud infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security with 10 years of experience",
|
||||
skills=["./skills/security-audit"], # 도메인 지침
|
||||
knowledge_sources=[pdf_source, url_source], # 검색된 사실
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 언제 무엇을 사용할까
|
||||
|
||||
| 필요한 것... | 사용할 것 | 예시 |
|
||||
| :------------------------------------------------------- | :---------------- | :--------------------------------------- |
|
||||
| 에이전트가 웹을 검색 | **도구** | `tools=[SerperDevTool()]` |
|
||||
| 에이전트가 MCP를 통해 원격 API 호출 | **MCP** | `mcps=["https://api.example.com/sse"]` |
|
||||
| 에이전트가 Gmail로 이메일 전송 | **앱** | `apps=["gmail"]` |
|
||||
| 에이전트가 특정 절차를 따름 | **스킬** | `skills=["./skills/code-review"]` |
|
||||
| 에이전트가 회사 문서 참조 | **지식** | `knowledge_sources=[pdf_source]` |
|
||||
| 에이전트가 웹 검색 AND 리뷰 가이드라인 준수 | **도구 + 스킬** | 둘 다 함께 사용 |
|
||||
|
||||
---
|
||||
|
||||
## 기능 조합하기
|
||||
|
||||
실제로 에이전트는 종종 **여러 기능 유형을 함께** 사용합니다. 현실적인 예시입니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
# 완전히 갖춘 리서치 에이전트
|
||||
researcher = Agent(
|
||||
role="Senior Research Analyst",
|
||||
goal="Produce comprehensive market analysis reports",
|
||||
backstory="Expert analyst with deep industry knowledge",
|
||||
|
||||
# 액션: 에이전트가 할 수 있는 것
|
||||
tools=[
|
||||
SerperDevTool(), # 웹 검색
|
||||
FileReadTool(), # 로컬 파일 읽기
|
||||
CodeInterpreterTool(), # 분석을 위한 Python 코드 실행
|
||||
],
|
||||
mcps=["https://data-api.example.com/sse"], # 원격 데이터 API 접근
|
||||
apps=["google_sheets"], # Google Sheets에 쓰기
|
||||
|
||||
# 컨텍스트: 에이전트가 아는 것
|
||||
skills=["./skills/research-methodology"], # 연구 수행 방법
|
||||
knowledge_sources=[company_docs], # 회사 특화 데이터
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 비교 테이블
|
||||
|
||||
| 특성 | 도구 | MCP | 앱 | 스킬 | 지식 |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: |
|
||||
| **에이전트에게 액션 부여** | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| **프롬프트 수정** | ❌ | ❌ | ❌ | ✅ | ✅ |
|
||||
| **코드 필요** | 예 | 설정만 | 설정만 | 마크다운만 | 설정만 |
|
||||
| **로컬 실행** | 예 | 경우에 따라 | 예 (환경 변수 필요) | N/A | 예 |
|
||||
| **API 키 필요** | 도구별 | 서버별 | 통합 토큰 | 아니오 | 임베더만 |
|
||||
| **Agent에 설정** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` |
|
||||
| **Crew에 설정** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` |
|
||||
|
||||
---
|
||||
|
||||
## 상세 가이드
|
||||
|
||||
각 기능 유형에 대해 더 알아볼 준비가 되셨나요?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="도구" icon="wrench" href="/ko/concepts/tools">
|
||||
맞춤형 도구 생성, 75개 이상의 OSS 카탈로그 사용, 캐싱 및 비동기 실행 설정.
|
||||
</Card>
|
||||
<Card title="MCP 통합" icon="plug" href="/ko/mcp/overview">
|
||||
stdio, SSE 또는 HTTP를 통해 MCP 서버에 연결. 도구 필터링, 인증 설정.
|
||||
</Card>
|
||||
<Card title="스킬" icon="bolt" href="/ko/concepts/skills">
|
||||
SKILL.md로 스킬 패키지 구축, 도메인 전문성 주입, 점진적 공개 사용.
|
||||
</Card>
|
||||
<Card title="지식" icon="book" href="/ko/concepts/knowledge">
|
||||
PDF, CSV, URL 등에서 지식 추가. 임베더 및 검색 설정.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
716
docs/edge/ko/concepts/agents.mdx
Normal file
716
docs/edge/ko/concepts/agents.mdx
Normal file
@@ -0,0 +1,716 @@
|
||||
---
|
||||
title: 에이전트
|
||||
description: CrewAI 프레임워크 내에서 에이전트를 생성하고 관리하는 자세한 가이드입니다.
|
||||
icon: robot
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 에이전트 개요
|
||||
|
||||
CrewAI 프레임워크에서 `Agent`는 다음과 같은 역할을 수행하는 자율적 단위입니다:
|
||||
- 특정 작업 수행
|
||||
- 자신의 역할과 목표에 기반한 의사결정
|
||||
- 도구를 활용하여 목표 달성
|
||||
- 다른 에이전트와의 소통 및 협업
|
||||
- 상호작용에 대한 기억 유지
|
||||
- 허용될 경우 작업 위임
|
||||
|
||||
<Tip>
|
||||
에이전트는 특정한 기술, 전문성, 책임을 가진 전문 팀원이라고 생각하시면 됩니다. 예를 들어, `Researcher` 에이전트는 정보 수집 및 분석에 뛰어날 수 있고, `Writer` 에이전트는 콘텐츠 작성에 더 강점을 가질 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
<Note type="info" title="엔터프라이즈 확장: 시각적 에이전트 빌더">
|
||||
CrewAI AOP에는 코드를 작성하지 않고도 에이전트 생성 및 구성을 간편하게 할 수 있는 시각적 에이전트 빌더가 포함되어 있습니다. 에이전트를 시각적으로 설계하고 실시간으로 테스트하세요.
|
||||
|
||||
|
||||
|
||||
시각적 에이전트 빌더를 통해 다음과 같은 기능을 사용할 수 있습니다:
|
||||
- 폼 기반 인터페이스를 통한 직관적 에이전트 구성
|
||||
- 실시간 테스트 및 검증
|
||||
- 사전 구성된 에이전트 유형 템플릿 라이브러리
|
||||
- 에이전트 속성 및 행동의 손쉬운 커스터마이즈
|
||||
</Note>
|
||||
|
||||
## 에이전트 속성
|
||||
|
||||
| 속성 | 파라미터 | 타입 | 설명 |
|
||||
| :-------------------------------------- | :----------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------- |
|
||||
| **역할** | `role` | `str` | 에이전트의 기능과 전문 분야를 정의합니다. |
|
||||
| **목표** | `goal` | `str` | 에이전트의 의사결정을 이끄는 개별 목표입니다. |
|
||||
| **배경 이야기** | `backstory` | `str` | 에이전트에게 맥락과 개성을 부여하여 상호작용을 풍부하게 합니다. |
|
||||
| **LLM** _(옵션)_ | `llm` | `Union[str, LLM, Any]` | 에이전트를 구동하는 언어 모델입니다. `OPENAI_MODEL_NAME`에 지정된 모델 또는 "gpt-4"가 기본값입니다. |
|
||||
| **도구** _(옵션)_ | `tools` | `List[BaseTool]` | 에이전트가 사용할 수 있는 기능 혹은 역량입니다. 기본값은 빈 리스트입니다. |
|
||||
| **Function Calling LLM** _(옵션)_ | `function_calling_llm` | `Optional[Any]` | 도구 호출을 위한 언어 모델로, 지정 시 crew의 LLM을 재정의합니다. |
|
||||
| **최대 반복 횟수** _(옵션)_ | `max_iter` | `int` | 에이전트가 최선의 답변을 제공하기 전 최대 반복 수입니다. 기본값은 20입니다. |
|
||||
| **최대 RPM** _(옵션)_ | `max_rpm` | `Optional[int]` | 레이트 리밋 회피를 위한 분당 최대 요청 수입니다. |
|
||||
| **최대 실행 시간** _(옵션)_ | `max_execution_time` | `Optional[int]` | 작업 실행의 최대 시간(초)입니다. |
|
||||
| **상세 로그** _(옵션)_ | `verbose` | `bool` | 디버깅을 위한 상세 실행 로그를 활성화합니다. 기본값은 False입니다. |
|
||||
| **위임 허용** _(옵션)_ | `allow_delegation` | `bool` | 에이전트가 다른 에이전트에게 작업을 위임할 수 있도록 허용합니다. 기본값은 False입니다. |
|
||||
| **Step Callback** _(옵션)_ | `step_callback` | `Optional[Any]` | 각 에이전트 단계 후 호출되는 함수로, crew 콜백을 재정의합니다. |
|
||||
| **캐시** _(옵션)_ | `cache` | `bool` | 도구 사용에 대해 캐싱을 활성화합니다. 기본값은 True입니다. |
|
||||
| **시스템 템플릿** _(옵션)_ | `system_template` | `Optional[str]` | 에이전트 맞춤형 시스템 프롬프트 템플릿입니다. |
|
||||
| **프롬프트 템플릿** _(옵션)_ | `prompt_template` | `Optional[str]` | 에이전트 맞춤형 프롬프트 템플릿입니다. |
|
||||
| **응답 템플릿** _(옵션)_ | `response_template` | `Optional[str]` | 에이전트 맞춤형 응답 템플릿입니다. |
|
||||
| **코드 실행 허용** _(옵션)_ | `allow_code_execution` | `Optional[bool]` | 에이전트의 코드 실행 활성화 여부입니다. 기본값은 False입니다. |
|
||||
| **최대 재시도 횟수** _(옵션)_ | `max_retry_limit` | `int` | 오류 발생 시 최대 재시도 횟수입니다. 기본값은 2입니다. |
|
||||
| **컨텍스트 윈도우 준수** _(옵션)_ | `respect_context_window` | `bool` | 메시지를 컨텍스트 윈도우 크기 내로 유지하기 위하여 요약 기능을 사용합니다. 기본값은 True입니다. |
|
||||
| **코드 실행 모드** _(옵션)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | 코드 실행 모드: 'safe'(Docker 사용) 또는 'unsafe'(직접 실행). 기본값은 'safe'입니다. |
|
||||
| **멀티모달** _(옵션)_ | `multimodal` | `bool` | 에이전트가 멀티모달 기능을 지원하는지 여부입니다. 기본값은 False입니다. |
|
||||
| **날짜 자동 삽입** _(옵션)_ | `inject_date` | `bool` | 작업에 현재 날짜를 자동으로 삽입할지 여부입니다. 기본값은 False입니다. |
|
||||
| **날짜 형식** _(옵션)_ | `date_format` | `str` | inject_date 활성화 시 날짜 표시 형식 문자열입니다. 기본값은 "%Y-%m-%d"(ISO 포맷)입니다. |
|
||||
| **추론** _(옵션)_ | `reasoning` | `bool` | 에이전트가 작업을 실행하기 전에 반영 및 플랜을 생성할지 여부입니다. 기본값은 False입니다. |
|
||||
| **최대 추론 시도 수** _(옵션)_ | `max_reasoning_attempts` | `Optional[int]` | 작업 실행 전 최대 추론 시도 횟수입니다. 설정하지 않으면 준비될 때까지 시도합니다. |
|
||||
| **임베더** _(옵션)_ | `embedder` | `Optional[Dict[str, Any]]` | 에이전트가 사용하는 임베더 설정입니다. |
|
||||
| **지식 소스** _(옵션)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | 에이전트가 사용할 수 있는 지식 소스입니다. |
|
||||
| **시스템 프롬프트 사용** _(옵션)_ | `use_system_prompt` | `Optional[bool]` | 시스템 프롬프트 사용 여부(o1 모델 지원용). 기본값은 True입니다. |
|
||||
|
||||
## 에이전트 생성
|
||||
|
||||
CrewAI에서 에이전트를 생성하는 일반적인 방법은 **JSONC 프로젝트 구성(새 crew 권장)** 또는 **코드에서 직접 정의**입니다.
|
||||
|
||||
### JSONC 구성 (권장)
|
||||
|
||||
`crewai create crew <name>`으로 만든 새 프로젝트는 JSON-first 구성을 사용합니다. 각 에이전트는 `agents/<agent_name>.jsonc`에 정의하고, `crew.jsonc`에서 crew에 포함할 에이전트를 나열합니다.
|
||||
|
||||
```jsonc agents/researcher.jsonc
|
||||
{
|
||||
"role": "{topic} Senior Data Researcher",
|
||||
"goal": "Uncover cutting-edge developments in {topic}",
|
||||
"backstory": "You find the most relevant information and present it clearly.",
|
||||
"llm": "openai/gpt-4o",
|
||||
"tools": ["SerperDevTool"],
|
||||
"settings": {
|
||||
"verbose": true,
|
||||
"allow_delegation": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`role`, `goal`, `backstory`에 `{placeholder}`를 사용할 수 있습니다. 기본값은 `crew.jsonc`의 `inputs`에 넣고, 빠진 값은 `crewai run`이 실행 시 물어봅니다. `verbose`, `allow_delegation`, `max_iter`, `memory`, `cache`, `planning_config` 같은 동작 필드는 최상위 또는 `settings` 안에 둘 수 있습니다.
|
||||
|
||||
<Note>
|
||||
JSONC는 주석과 trailing comma를 지원합니다. `agents/<name>.jsonc`와 `agents/<name>.json`이 모두 있으면 CrewAI는 JSONC 파일을 사용합니다.
|
||||
</Note>
|
||||
|
||||
### 클래식 YAML 구성
|
||||
|
||||
`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `config/agents.yaml`과 `crew.py`의 `@CrewBase` 클래스를 사용합니다.
|
||||
|
||||
YAML 구성은 기존 Python/YAML 프로젝트와 `@CrewBase` 클래스에서 에이전트를 정의하려는 팀을 위해 계속 지원됩니다.
|
||||
|
||||
클래식 프로젝트를 만든 후, `src/<project_name>/config/agents.yaml` 파일로 이동하여 템플릿을 여러분의 요구 사항에 맞게 수정하세요.
|
||||
|
||||
<Note>
|
||||
YAML 파일의 변수(예: `{topic}`)는 crew를 실행할 때 입력값에서 가져온 값으로 대체됩니다:
|
||||
```python Code
|
||||
crew.kickoff(inputs={'topic': 'AI Agents'})
|
||||
```
|
||||
</Note>
|
||||
|
||||
아래는 YAML을 사용하여 에이전트를 구성하는 예시입니다:
|
||||
|
||||
```yaml agents.yaml
|
||||
# src/<project_name>/config/agents.yaml
|
||||
researcher:
|
||||
role: >
|
||||
{topic} Senior Data Researcher
|
||||
goal: >
|
||||
Uncover cutting-edge developments in {topic}
|
||||
backstory: >
|
||||
You're a seasoned researcher with a knack for uncovering the latest
|
||||
developments in {topic}. Known for your ability to find the most relevant
|
||||
information and present it in a clear and concise manner.
|
||||
|
||||
reporting_analyst:
|
||||
role: >
|
||||
{topic} Reporting Analyst
|
||||
goal: >
|
||||
Create detailed reports based on {topic} data analysis and research findings
|
||||
backstory: >
|
||||
You're a meticulous analyst with a keen eye for detail. You're known for
|
||||
your ability to turn complex data into clear and concise reports, making
|
||||
it easy for others to understand and act on the information you provide.
|
||||
```
|
||||
|
||||
이 YAML 구성을 코드에서 사용하려면, `CrewBase`를 상속하는 crew 클래스를 생성하세요:
|
||||
|
||||
```python Code
|
||||
# src/<project_name>/crew.py
|
||||
from crewai import Agent, Crew, Process
|
||||
from crewai.project import CrewBase, agent, crew
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
@CrewBase
|
||||
class LatestAiDevelopmentCrew():
|
||||
"""LatestAiDevelopment crew"""
|
||||
|
||||
agents_config = "config/agents.yaml"
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
verbose=True,
|
||||
tools=[SerperDevTool()]
|
||||
)
|
||||
|
||||
@agent
|
||||
def reporting_analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['reporting_analyst'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
YAML 파일(`agents.yaml`)에서 사용하는 이름은 파이썬 코드의 메서드 이름과 일치해야 합니다.
|
||||
</Note>
|
||||
|
||||
### 직접 코드 정의
|
||||
|
||||
`Agent` 클래스를 인스턴스화하여 코드에서 직접 agent를 생성할 수 있습니다. 아래는 사용 가능한 모든 파라미터를 보여주는 종합적인 예제입니다:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
# 사용 가능한 모든 파라미터로 agent 생성
|
||||
agent = Agent(
|
||||
role="Senior Data Scientist",
|
||||
goal="Analyze and interpret complex datasets to provide actionable insights",
|
||||
backstory="With over 10 years of experience in data science and machine learning, "
|
||||
"you excel at finding patterns in complex datasets.",
|
||||
llm="gpt-4", # 기본값: OPENAI_MODEL_NAME 또는 "gpt-4"
|
||||
function_calling_llm=None, # 옵션: 도구 호출을 위한 별도의 LLM
|
||||
verbose=False, # 기본값: False
|
||||
allow_delegation=False, # 기본값: False
|
||||
max_iter=20, # 기본값: 20번 반복
|
||||
max_rpm=None, # 옵션: API 호출에 대한 속도 제한
|
||||
max_execution_time=None, # 옵션: 최대 실행 시간(초 단위)
|
||||
max_retry_limit=2, # 기본값: 오류 시 2번 재시도
|
||||
allow_code_execution=False, # 기본값: False
|
||||
code_execution_mode="safe", # 기본값: "safe" (옵션: "safe", "unsafe")
|
||||
respect_context_window=True, # 기본값: True
|
||||
use_system_prompt=True, # 기본값: True
|
||||
multimodal=False, # 기본값: False
|
||||
inject_date=False, # 기본값: False
|
||||
date_format="%Y-%m-%d", # 기본값: ISO 형식
|
||||
reasoning=False, # 기본값: False
|
||||
max_reasoning_attempts=None, # 기본값: None
|
||||
tools=[SerperDevTool()], # 옵션: 도구 리스트
|
||||
knowledge_sources=None, # 옵션: 지식 소스 리스트
|
||||
embedder=None, # 옵션: 커스텀 임베더 구성
|
||||
system_template=None, # 옵션: 커스텀 시스템 프롬프트 템플릿
|
||||
prompt_template=None, # 옵션: 커스텀 프롬프트 템플릿
|
||||
response_template=None, # 옵션: 커스텀 응답 템플릿
|
||||
step_callback=None, # 옵션: 모니터링용 콜백 함수
|
||||
)
|
||||
```
|
||||
|
||||
일반적인 사용 사례를 위한 주요 파라미터 조합을 살펴보겠습니다:
|
||||
|
||||
#### 기본 연구 에이전트
|
||||
```python Code
|
||||
research_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Find and summarize information about specific topics",
|
||||
backstory="You are an experienced researcher with attention to detail",
|
||||
tools=[SerperDevTool()],
|
||||
verbose=True # Enable logging for debugging
|
||||
)
|
||||
```
|
||||
|
||||
#### 코드 개발 에이전트
|
||||
```python Code
|
||||
dev_agent = Agent(
|
||||
role="Senior Python Developer",
|
||||
goal="Write and debug Python code",
|
||||
backstory="Expert Python developer with 10 years of experience",
|
||||
allow_code_execution=True,
|
||||
code_execution_mode="safe", # Uses Docker for safety
|
||||
max_execution_time=300, # 5-minute timeout
|
||||
max_retry_limit=3 # More retries for complex code tasks
|
||||
)
|
||||
```
|
||||
|
||||
#### 장기 실행 분석 에이전트
|
||||
```python Code
|
||||
analysis_agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Perform deep analysis of large datasets",
|
||||
backstory="Specialized in big data analysis and pattern recognition",
|
||||
memory=True,
|
||||
respect_context_window=True,
|
||||
max_rpm=10, # Limit API calls
|
||||
function_calling_llm="gpt-4o-mini" # Cheaper model for tool calls
|
||||
)
|
||||
```
|
||||
|
||||
#### 커스텀 템플릿 에이전트
|
||||
```python Code
|
||||
custom_agent = Agent(
|
||||
role="Customer Service Representative",
|
||||
goal="Assist customers with their inquiries",
|
||||
backstory="Experienced in customer support with a focus on satisfaction",
|
||||
system_template="""<|start_header_id|>system<|end_header_id|>
|
||||
{{ .System }}<|eot_id|>""",
|
||||
prompt_template="""<|start_header_id|>user<|end_header_id|>
|
||||
{{ .Prompt }}<|eot_id|>""",
|
||||
response_template="""<|start_header_id|>assistant<|end_header_id|>
|
||||
{{ .Response }}<|eot_id|>""",
|
||||
)
|
||||
```
|
||||
|
||||
#### 날짜 인식이 가능한 Reasoning Agent
|
||||
```python Code
|
||||
strategic_agent = Agent(
|
||||
role="Market Analyst",
|
||||
goal="Track market movements with precise date references and strategic planning",
|
||||
backstory="Expert in time-sensitive financial analysis and strategic reporting",
|
||||
inject_date=True, # Automatically inject current date into tasks
|
||||
date_format="%B %d, %Y", # Format as "May 21, 2025"
|
||||
reasoning=True, # Enable strategic planning
|
||||
max_reasoning_attempts=2, # Limit planning iterations
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### Reasoning Agent
|
||||
```python Code
|
||||
reasoning_agent = Agent(
|
||||
role="Strategic Planner",
|
||||
goal="Analyze complex problems and create detailed execution plans",
|
||||
backstory="Expert strategic planner who methodically breaks down complex challenges",
|
||||
reasoning=True, # Enable reasoning and planning
|
||||
max_reasoning_attempts=3, # Limit reasoning attempts
|
||||
max_iter=30, # Allow more iterations for complex planning
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### 멀티모달 에이전트
|
||||
```python Code
|
||||
multimodal_agent = Agent(
|
||||
role="Visual Content Analyst",
|
||||
goal="Analyze and process both text and visual content",
|
||||
backstory="Specialized in multimodal analysis combining text and image understanding",
|
||||
multimodal=True, # Enable multimodal capabilities
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### 매개변수 세부 정보
|
||||
|
||||
#### 중요 파라미터
|
||||
- `role`, `goal`, 그리고 `backstory`는 필수이며 에이전트의 행동을 결정합니다
|
||||
- `llm`은 사용되는 언어 모델을 결정합니다 (기본값: OpenAI의 GPT-4)
|
||||
|
||||
#### 메모리 및 컨텍스트
|
||||
- `memory`: 대화 이력을 유지하도록 활성화합니다
|
||||
- `respect_context_window`: 토큰 제한 문제를 방지합니다
|
||||
- `knowledge_sources`: 도메인별 지식 기반을 추가합니다
|
||||
|
||||
#### 실행 제어
|
||||
- `max_iter`: 최적의 답변을 제공하기 전의 최대 시도 횟수
|
||||
- `max_execution_time`: 제한 시간(초 단위)
|
||||
- `max_rpm`: API 호출 속도 제한
|
||||
- `max_retry_limit`: 오류 발생 시 재시도 횟수
|
||||
|
||||
#### 코드 실행
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` 및 `code_execution_mode`는 더 이상 사용되지 않습니다. `CodeInterpreterTool`이 `crewai-tools`에서 제거되었습니다. 안전한 코드 실행을 위해 [E2B](https://e2b.dev) 또는 [Modal](https://modal.com)과 같은 전용 샌드박스 서비스를 사용하세요.
|
||||
</Warning>
|
||||
|
||||
- `allow_code_execution` _(지원 중단)_: 이전에 `CodeInterpreterTool`을 통한 내장 코드 실행을 활성화했습니다.
|
||||
- `code_execution_mode` _(지원 중단)_: 이전에 실행 모드를 제어했습니다 (Docker의 경우 `"safe"`, 직접 실행의 경우 `"unsafe"`).
|
||||
|
||||
#### 고급 기능
|
||||
- `multimodal`: 텍스트와 시각적 콘텐츠 처리를 위한 멀티모달 기능 활성화
|
||||
- `reasoning`: 에이전트가 작업을 수행하기 전에 반영하고 계획을 작성할 수 있도록 활성화
|
||||
- `inject_date`: 현재 날짜를 작업 설명에 자동으로 삽입
|
||||
|
||||
#### 템플릿
|
||||
- `system_template`: 에이전트의 핵심 동작을 정의합니다
|
||||
- `prompt_template`: 입력 형식을 구성합니다
|
||||
- `response_template`: 에이전트 응답을 포맷합니다
|
||||
|
||||
<Note>
|
||||
커스텀 템플릿을 사용할 때는 `system_template`과 `prompt_template`가 모두 정의되어 있는지 확인하십시오. `response_template`은 선택 사항이지만 일관된 출력 포맷을 위해 권장됩니다.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
커스텀 템플릿을 사용할 때는 템플릿에서 `{role}`, `{goal}`, `{backstory}`와 같은 변수를 사용할 수 있습니다. 이 변수들은 실행 중에 자동으로 채워집니다.
|
||||
</Note>
|
||||
|
||||
## 에이전트 도구
|
||||
|
||||
에이전트는 다양한 도구를 장착하여 그 능력을 향상시킬 수 있습니다. CrewAI는 다음의 도구들을 지원합니다:
|
||||
- [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools)
|
||||
- [LangChain Tools](https://python.langchain.com/docs/integrations/tools)
|
||||
|
||||
에이전트에 도구를 추가하는 방법은 다음과 같습니다:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, WikipediaTools
|
||||
|
||||
# 도구 생성
|
||||
search_tool = SerperDevTool()
|
||||
wiki_tool = WikipediaTools()
|
||||
|
||||
# 에이전트에 도구 추가
|
||||
researcher = Agent(
|
||||
role="AI Technology Researcher",
|
||||
goal="Research the latest AI developments",
|
||||
tools=[search_tool, wiki_tool],
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## 에이전트 메모리와 컨텍스트
|
||||
|
||||
에이전트는 상호작용의 메모리를 유지하고 이전 작업의 컨텍스트를 사용할 수 있습니다. 이는 여러 작업에 걸쳐 정보를 유지해야 하는 복잡한 워크플로우에서 특히 유용합니다.
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
|
||||
analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze and remember complex data patterns",
|
||||
memory=True, # Enable memory
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
`memory`가 활성화되면 에이전트는 여러 상호작용에 걸쳐 컨텍스트를 유지하게 되어, 복잡하고 여러 단계로 이루어진 작업을 처리하는 능력이 향상됩니다.
|
||||
</Note>
|
||||
|
||||
## 컨텍스트 윈도우 관리
|
||||
|
||||
CrewAI는 대화가 언어 모델의 토큰 한도를 초과하는 상황을 처리하기 위해 정교한 자동 컨텍스트 윈도우 관리 기능을 포함하고 있습니다. 이 강력한 기능은 `respect_context_window` 매개변수로 제어됩니다.
|
||||
|
||||
### 컨텍스트 윈도우 관리 방식
|
||||
|
||||
에이전트의 대화 기록이 LLM의 컨텍스트 윈도우 크기를 초과할 경우, CrewAI는 이 상황을 자동으로 감지하고 다음 중 하나를 수행할 수 있습니다:
|
||||
|
||||
1. **자동으로 내용을 요약** ( `respect_context_window=True` 인 경우)
|
||||
2. **오류와 함께 실행 중지** ( `respect_context_window=False` 인 경우)
|
||||
|
||||
### 자동 컨텍스트 처리 (`respect_context_window=True`)
|
||||
|
||||
이 설정은 대부분의 사용 사례에서 **기본값이자 권장 옵션**입니다. 활성화되면 CrewAI는 다음과 같이 동작합니다:
|
||||
|
||||
```python Code
|
||||
# Agent with automatic context management (default)
|
||||
smart_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Analyze large documents and datasets",
|
||||
backstory="Expert at processing extensive information",
|
||||
respect_context_window=True, # 🔑 Default: auto-handle context limits
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
**컨텍스트 한도를 초과할 경우 발생하는 일:**
|
||||
- ⚠️ **경고 메시지**: `"Context length exceeded. Summarizing content to fit the model context window."`
|
||||
- 🔄 **자동 요약**: CrewAI가 대화 기록을 지능적으로 요약함
|
||||
- ✅ **작업 지속**: 요약된 컨텍스트로 작업이 원활하게 계속됨
|
||||
- 📝 **정보 보존**: 토큰 수를 줄이면서도 주요 정보는 유지됨
|
||||
|
||||
### 엄격한 컨텍스트 제한(`respect_context_window=False`)
|
||||
|
||||
정확한 제어가 필요하며, 정보를 잃지 않으려면 실행이 중지되도록 할 때:
|
||||
|
||||
```python Code
|
||||
# Agent with strict context limits
|
||||
strict_agent = Agent(
|
||||
role="Legal Document Reviewer",
|
||||
goal="Provide precise legal analysis without information loss",
|
||||
backstory="Legal expert requiring complete context for accurate analysis",
|
||||
respect_context_window=False, # ❌ Stop execution on context limit
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
**컨텍스트 한도를 초과하면 발생하는 일:**
|
||||
- ❌ **오류 메시지**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."`
|
||||
- 🛑 **실행 중지**: 작업 실행이 즉시 중단됨
|
||||
- 🔧 **수동 개입 필요**: 접근 방식을 직접 수정해야 함
|
||||
|
||||
### 올바른 설정 선택
|
||||
|
||||
#### 다음과 같은 경우 `respect_context_window=True` (기본값)을 사용하세요:
|
||||
- **문서가 클 경우** 컨텍스트 제한을 초과할 수 있습니다
|
||||
- **오래 지속되는 대화**에서 일부 요약이 허용되는 경우
|
||||
- **연구 과제**에서 정확한 세부사항보다는 전체적인 컨텍스트가 더 중요한 경우
|
||||
- **프로토타이핑 및 개발**에서 견고한 실행을 원하는 경우
|
||||
|
||||
```python Code
|
||||
# Perfect for document processing
|
||||
document_processor = Agent(
|
||||
role="Document Analyst",
|
||||
goal="Extract insights from large research papers",
|
||||
backstory="Expert at analyzing extensive documentation",
|
||||
respect_context_window=True, # Handle large documents gracefully
|
||||
max_iter=50, # Allow more iterations for complex analysis
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### `respect_context_window=False`를 사용할 때:
|
||||
- **정확성이 매우 중요**하고 정보 손실이 허용되지 않을 때
|
||||
- **법률 또는 의료 업무**에서 전체 맥락이 필요한 경우
|
||||
- **코드 리뷰**에서 누락된 세부 정보가 버그를 유발할 수 있는 경우
|
||||
- **금융 분석**에서 정확도가 최우선인 경우
|
||||
|
||||
```python Code
|
||||
# Perfect for precision tasks
|
||||
precision_agent = Agent(
|
||||
role="Code Security Auditor",
|
||||
goal="Identify security vulnerabilities in code",
|
||||
backstory="Security expert requiring complete code context",
|
||||
respect_context_window=False, # Prefer failure over incomplete analysis
|
||||
max_retry_limit=1, # Fail fast on context issues
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### 대용량 데이터에 대한 대체 접근 방식
|
||||
|
||||
매우 큰 데이터셋을 다룰 때는 다음과 같은 전략을 고려하세요:
|
||||
|
||||
#### 1. RAG 도구 사용하기
|
||||
```python Code
|
||||
from crewai_tools import RagTool
|
||||
|
||||
# Create RAG tool for large document processing
|
||||
rag_tool = RagTool()
|
||||
|
||||
rag_agent = Agent(
|
||||
role="Research Assistant",
|
||||
goal="Query large knowledge bases efficiently",
|
||||
backstory="Expert at using RAG tools for information retrieval",
|
||||
tools=[rag_tool], # Use RAG instead of large context windows
|
||||
respect_context_window=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
#### 2. 지식 소스 사용
|
||||
```python Code
|
||||
# Use knowledge sources instead of large prompts
|
||||
knowledge_agent = Agent(
|
||||
role="Knowledge Expert",
|
||||
goal="Answer questions using curated knowledge",
|
||||
backstory="Expert at leveraging structured knowledge sources",
|
||||
knowledge_sources=[your_knowledge_sources], # Pre-processed knowledge
|
||||
respect_context_window=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### 컨텍스트 윈도우 모범 사례
|
||||
|
||||
1. **컨텍스트 사용 모니터링**: `verbose=True`를 활성화하여 컨텍스트 관리 과정을 확인하세요
|
||||
2. **효율성 설계**: 작업 구조를 효과적으로 설계하여 컨텍스트 누적을 최소화하세요
|
||||
3. **적절한 모델 사용**: 작업에 적합한 컨텍스트 윈도우를 가진 LLM을 선택하세요
|
||||
4. **두 가지 설정 모두 테스트**: `True`와 `False` 모두 시도하여 어떤 것이 더 효과적인지 확인하세요
|
||||
5. **RAG와 조합 사용**: 매우 큰 데이터셋의 경우 컨텍스트 윈도우에만 의존하지 말고 RAG 도구도 함께 사용하세요
|
||||
|
||||
### 컨텍스트 문제 해결
|
||||
|
||||
**컨텍스트 제한 오류가 발생하는 경우:**
|
||||
```python Code
|
||||
# 빠른 해결책: 자동 처리 활성화
|
||||
agent.respect_context_window = True
|
||||
|
||||
# 더 나은 솔루션: 대용량 데이터에는 RAG 도구 사용
|
||||
from crewai_tools import RagTool
|
||||
agent.tools = [RagTool()]
|
||||
|
||||
# 대안: 작업을 더 작은 단위로 나누기
|
||||
# 또는 대용량 프롬프트 대신 knowledge 소스 사용
|
||||
```
|
||||
|
||||
**자동 요약 기능이 중요한 정보를 놓치는 경우:**
|
||||
```python Code
|
||||
# 자동 요약 비활성화 후 RAG 사용
|
||||
agent = Agent(
|
||||
role="Detailed Analyst",
|
||||
goal="Maintain complete information accuracy",
|
||||
backstory="Expert requiring full context",
|
||||
respect_context_window=False, # 요약 안 함
|
||||
tools=[RagTool()], # 대용량 데이터에는 RAG 사용
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
컨텍스트 윈도우 관리 기능은 백그라운드에서 자동으로 작동합니다. 특별한 함수를 호출할 필요가 없으며, 원하는 동작에 맞게 `respect_context_window`만 설정하면 CrewAI가 나머지를 처리합니다!
|
||||
</Note>
|
||||
|
||||
## `kickoff()`을 사용한 에이전트 직접 상호작용
|
||||
|
||||
에이전트는 `kickoff()` 메서드를 사용하여 작업(task)이나 crew 워크플로우를 거치지 않고 직접 사용할 수 있습니다. 이는 전체 crew 오케스트레이션 기능이 필요하지 않을 때 에이전트와 상호작용하는 더 간단한 방법을 제공합니다.
|
||||
|
||||
### `kickoff()` 작동 방식
|
||||
|
||||
`kickoff()` 메서드는 메시지를 에이전트에게 직접 보내고 응답을 받을 수 있게 해줍니다. 이는 LLM과 상호 작용하는 것과 유사하지만, 에이전트의 모든 기능(도구, 추론 등)을 활용할 수 있다는 점이 다릅니다.
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
# Create an agent
|
||||
researcher = Agent(
|
||||
role="AI Technology Researcher",
|
||||
goal="Research the latest AI developments",
|
||||
tools=[SerperDevTool()],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Use kickoff() to interact directly with the agent
|
||||
result = researcher.kickoff("What are the latest developments in language models?")
|
||||
|
||||
# Access the raw response
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
### 매개변수 및 반환 값
|
||||
|
||||
| 매개변수 | 타입 | 설명 |
|
||||
| :---------------- | :---------------------------------- | :------------------------------------------------------------------------ |
|
||||
| `messages` | `Union[str, List[Dict[str, str]]]` | 문자열 쿼리 또는 역할/내용이 포함된 메시지 딕셔너리의 리스트 |
|
||||
| `response_format` | `Optional[Type[Any]]` | 구조화된 출력을 위한 선택적 Pydantic 모델 |
|
||||
|
||||
이 메서드는 다음과 같은 속성을 가진 `LiteAgentOutput` 객체를 반환합니다:
|
||||
|
||||
- `raw`: 원시 출력 텍스트를 포함하는 문자열
|
||||
- `pydantic`: 파싱된 Pydantic 모델 (`response_format`이 제공된 경우)
|
||||
- `agent_role`: 출력을 생성한 agent의 역할
|
||||
- `usage_metrics`: 실행에 대한 토큰 사용 지표
|
||||
|
||||
### 구조화된 출력
|
||||
|
||||
`response_format`으로 Pydantic 모델을 제공하여 구조화된 출력을 받을 수 있습니다:
|
||||
|
||||
```python Code
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
|
||||
class ResearchFindings(BaseModel):
|
||||
main_points: List[str]
|
||||
key_technologies: List[str]
|
||||
future_predictions: str
|
||||
|
||||
# Get structured output
|
||||
result = researcher.kickoff(
|
||||
"Summarize the latest developments in AI for 2025",
|
||||
response_format=ResearchFindings
|
||||
)
|
||||
|
||||
# Access structured data
|
||||
print(result.pydantic.main_points)
|
||||
print(result.pydantic.future_predictions)
|
||||
```
|
||||
|
||||
### 여러 개의 메시지
|
||||
|
||||
대화 기록을 메시지 딕셔너리의 목록으로 제공할 수도 있습니다:
|
||||
|
||||
```python Code
|
||||
messages = [
|
||||
{"role": "user", "content": "I need information about large language models"},
|
||||
{"role": "assistant", "content": "I'd be happy to help with that! What specifically would you like to know?"},
|
||||
{"role": "user", "content": "What are the latest developments in 2025?"}
|
||||
]
|
||||
|
||||
result = researcher.kickoff(messages)
|
||||
```
|
||||
|
||||
### 비동기 지원
|
||||
|
||||
동일한 매개변수를 사용하는 비동기 버전은 `kickoff_async()`를 통해 사용할 수 있습니다:
|
||||
|
||||
```python Code
|
||||
import asyncio
|
||||
|
||||
async def main():
|
||||
result = await researcher.kickoff_async("What are the latest developments in AI?")
|
||||
print(result.raw)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
<Note>
|
||||
`kickoff()` 메서드는 내부적으로 `LiteAgent`를 사용하며, 모든 agent 설정(역할, 목표, 백스토리, 도구 등)을 유지하면서도 더 간단한 실행 흐름을 제공합니다.
|
||||
</Note>
|
||||
|
||||
## 중요한 고려사항 및 모범 사례
|
||||
|
||||
### 보안 및 코드 실행
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` 및 `code_execution_mode`는 더 이상 사용되지 않으며 `CodeInterpreterTool`이 제거되었습니다. 안전한 코드 실행을 위해 [E2B](https://e2b.dev) 또는 [Modal](https://modal.com)과 같은 전용 샌드박스 서비스를 사용하세요.
|
||||
</Warning>
|
||||
|
||||
### 성능 최적화
|
||||
- `respect_context_window: true`를 사용하여 토큰 제한 문제를 방지하세요.
|
||||
- 적절한 `max_rpm`을 설정하여 속도 제한을 피하세요.
|
||||
- 반복적인 작업의 성능 향상을 위해 `cache: true`를 활성화하세요.
|
||||
- 작업의 복잡도에 따라 `max_iter`와 `max_retry_limit`을 조정하세요.
|
||||
|
||||
### 메모리 및 컨텍스트 관리
|
||||
- 도메인별 정보를 위해 `knowledge_sources`를 활용하세요
|
||||
- 커스텀 임베딩 모델을 사용할 때는 `embedder`를 구성하세요
|
||||
- 에이전트 행동을 세밀하게 제어하려면 커스텀 템플릿(`system_template`, `prompt_template`, `response_template`)을 사용하세요
|
||||
|
||||
### 고급 기능
|
||||
- 복잡한 작업을 실행하기 전에 계획을 세우고 반성해야 하는 에이전트의 경우 `reasoning: true`를 활성화하세요.
|
||||
- 계획 반복 횟수를 제어하려면 적절한 `max_reasoning_attempts` 값을 설정하세요 (무제한 시 None 사용).
|
||||
- 시간에 민감한 작업을 위해 에이전트가 현재 날짜를 인식할 수 있도록 `inject_date: true`를 사용하세요.
|
||||
- 표준 Python datetime 형식 코드를 사용하여 `date_format`으로 날짜 형식을 맞춤 설정할 수 있습니다.
|
||||
- 텍스트와 시각적 콘텐츠를 모두 처리해야 하는 에이전트의 경우 `multimodal: true`를 활성화하세요.
|
||||
|
||||
### 에이전트 협업
|
||||
- 에이전트들이 함께 작업해야 할 때 `allow_delegation: true`를 활성화하세요
|
||||
- 에이전트 상호작용을 모니터링하고 기록하려면 `step_callback`을 사용하세요
|
||||
- 다양한 목적에 따라 서로 다른 LLM을 사용하는 것을 고려하세요:
|
||||
- 복잡한 추론에는 메인 `llm`
|
||||
- 효율적인 도구 사용에는 `function_calling_llm`
|
||||
|
||||
### 날짜 인식 및 추론
|
||||
- 시간에 민감한 작업을 위해 `inject_date: true`를 사용하여 에이전트에게 현재 날짜 인식 기능을 제공합니다.
|
||||
- 표준 Python datetime 형식 코드를 사용하는 `date_format`으로 날짜 형식을 사용자 정의할 수 있습니다.
|
||||
- 유효한 형식 코드는 다음과 같습니다: %Y (연도), %m (월), %d (일), %B (전체 월 이름) 등.
|
||||
- 잘못된 날짜 형식은 경고로 기록되며, 작업 설명을 수정하지 않습니다.
|
||||
- 사전 계획 및 성찰이 필요한 복잡한 작업의 경우 `reasoning: true`를 활성화하세요.
|
||||
|
||||
### 모델 호환성
|
||||
- 시스템 메시지를 지원하지 않는 이전 모델의 경우 `use_system_prompt: false`로 설정하세요
|
||||
- 선택한 `llm`이(가) 필요한 기능(예: 함수 호출)을 지원하는지 확인하세요
|
||||
|
||||
## 일반적인 문제 해결
|
||||
|
||||
1. **Rate Limiting(속도 제한)**: API 속도 제한에 도달하는 경우:
|
||||
- 적절한 `max_rpm` 구현
|
||||
- 반복적인 작업에 캐싱 사용
|
||||
- 요청을 일괄 처리(batch)하는 것 고려
|
||||
|
||||
2. **Context Window Errors(컨텍스트 윈도우 오류)**: 컨텍스트 한계를 초과하는 경우:
|
||||
- `respect_context_window` 활성화
|
||||
- 더 효율적인 프롬프트 사용
|
||||
- 주기적으로 에이전트 메모리 정리
|
||||
|
||||
3. **Code Execution Issues(코드 실행 문제)**: 코드 실행이 실패하는 경우:
|
||||
- 안전 모드를 위해 Docker 설치 여부 확인
|
||||
- 실행 권한 확인
|
||||
- 코드 샌드박스 설정 검토
|
||||
|
||||
4. **Memory Issues(메모리 문제)**: 에이전트 응답이 일관되지 않은 경우:
|
||||
- knowledge 소스 구성 확인
|
||||
- 대화 기록 관리 검토
|
||||
|
||||
에이전트는 특정 사용 사례에 맞게 구성될 때 가장 효과적입니다. 자신의 요구 사항을 이해하고 이에 맞게 이러한 매개변수를 조정하는 데 시간을 투자하세요.
|
||||
423
docs/edge/ko/concepts/checkpointing.mdx
Normal file
423
docs/edge/ko/concepts/checkpointing.mdx
Normal file
@@ -0,0 +1,423 @@
|
||||
---
|
||||
title: Checkpointing
|
||||
description: 실행 상태를 자동으로 저장하여 크루, 플로우, 에이전트가 실패 후 재개할 수 있습니다.
|
||||
icon: floppy-disk
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
체크포인팅은 실행 중 실행 상태의 스냅샷을 저장하여 크루, 플로우, 에이전트가 실패 후 재개하거나 대체 브랜치로 분기될 수 있도록 합니다.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="설명" icon="lightbulb" href="#설명">
|
||||
체크포인팅의 작동 방식: 이벤트, 스토리지, 상속.
|
||||
</Card>
|
||||
<Card title="튜토리얼" icon="graduation-cap" href="#튜토리얼-실패한-크루-재개하기">
|
||||
5분 가이드: 실행, 중단, 재개.
|
||||
</Card>
|
||||
<Card title="사용 방법" icon="screwdriver-wrench" href="#사용-방법">
|
||||
일반적인 워크플로우를 위한 작업 중심 레시피.
|
||||
</Card>
|
||||
<Card title="레퍼런스" icon="book" href="#레퍼런스">
|
||||
`CheckpointConfig`, 이벤트, 프로바이더, CLI.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 설명
|
||||
|
||||
### 체크포인트란
|
||||
|
||||
체크포인트는 실행 중인 작업을 재현하기 위해 CrewAI가 필요한 모든 것을 캡처합니다: 크루, 플로우 또는 에이전트의 전체 상태 — 구성, 에이전트의 메모리 및 지식 소스, 태스크 진행 상황, 중간 출력값, 내부 상태 및 속성 — 그리고 kickoff 입력, 해당 시점까지의 이벤트 기록, 그리고 체크포인트를 원본 실행에 연결하는 lineage ID를 포함합니다.
|
||||
|
||||
복원하면 해당 상태를 재구성하고 계속 진행합니다. 완료된 태스크는 건너뛰고, 메모리와 지식은 재수화되며, 다운스트림 작업은 원본 실행이 생성한 동일한 출력을 기반으로 실행됩니다. 포크하면 새 lineage 아래에서 동일한 복원을 수행하여 새 브랜치와 원본 실행이 서로 덮어쓰지 않고 나란히 체크포인트를 기록할 수 있습니다.
|
||||
|
||||
### 체크포인트가 기록되는 시점
|
||||
|
||||
체크포인팅은 이벤트 기반입니다. 런타임은 `on_events`로 선택한 이벤트를 구독하고, 이벤트가 발생할 때마다 체크포인트를 기록합니다. 기본값 `task_completed`는 완료된 태스크당 하나의 체크포인트를 생성합니다 — 세분화와 디스크 사용의 합리적인 균형입니다. `llm_call_completed`와 같은 고빈도 이벤트는 더 세밀한 복구를 위해 사용 가능하지만 훨씬 많은 파일을 기록합니다.
|
||||
|
||||
### 스토리지
|
||||
|
||||
CrewAI에는 두 가지 프로바이더가 포함되어 있습니다:
|
||||
|
||||
- `JsonProvider`는 체크포인트당 하나의 파일을 기록합니다. 사람이 읽기 쉽고 검사하기 편리합니다.
|
||||
- `SqliteProvider`는 단일 SQLite 데이터베이스에 기록합니다. 고빈도 체크포인팅에 적합합니다.
|
||||
|
||||
`max_checkpoints`가 설정되면 두 프로바이더 모두 가장 오래된 체크포인트를 자동으로 제거합니다.
|
||||
|
||||
<Note>
|
||||
체크포인트 기록은 best-effort 방식입니다. 실패한 체크포인트는 로그에 기록되지만 실행을 중단시키지 않습니다.
|
||||
</Note>
|
||||
|
||||
### 상속 모델
|
||||
|
||||
`Crew`, `Flow`, `Agent` 모두 `checkpoint` 인수를 받습니다. 자식은 자체 값을 설정하거나 `False`를 전달하여 옵트아웃하지 않는 한 부모로부터 상속합니다. 크루에서 체크포인팅을 한 번 활성화하면 모든 에이전트가 참여하거나, 특정 에이전트만 선택적으로 제외할 수 있습니다.
|
||||
|
||||
## 튜토리얼: 실패한 크루 재개하기
|
||||
|
||||
이 가이드는 약 5분이 소요됩니다. 두 개의 태스크가 있는 크루를 실행하고 중간에 종료한 다음, 저장된 체크포인트에서 재개합니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="체크포인팅이 활성화된 크루를 생성합니다">
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
|
||||
writer = Agent(role="Writer", goal="Write", backstory="Expert")
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[
|
||||
Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
|
||||
Task(description="Write a summary", agent=writer, expected_output="paragraph"),
|
||||
],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Step>
|
||||
<Step title="실행하고 첫 번째 태스크 후에 중단합니다">
|
||||
```python
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
첫 번째 태스크가 완료된 후 `Ctrl+C`를 누릅니다. `./.checkpoints/` 디렉토리에서 `<timestamp>_<uuid>.json` 형식의 파일이 체크포인트입니다.
|
||||
</Step>
|
||||
<Step title="체크포인트에서 재개합니다">
|
||||
```python
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
result = crew.kickoff(
|
||||
from_checkpoint=CheckpointConfig(
|
||||
restore_from="./.checkpoints/<timestamp>_<uuid>.json",
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
연구 태스크는 건너뛰고, 작성자는 저장된 연구 출력에 대해 실행되며, 크루가 완료됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 사용 방법
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="기본값으로 체크포인팅 활성화" icon="play">
|
||||
```python
|
||||
crew = Crew(agents=[...], tasks=[...], checkpoint=True)
|
||||
```
|
||||
|
||||
`task_completed` 이벤트마다 `./.checkpoints/`에 기록합니다.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="스토리지와 빈도 사용자 정의" icon="sliders">
|
||||
```python
|
||||
from crewai import Crew, CheckpointConfig
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
on_events=["task_completed", "crew_kickoff_completed"],
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="스토리지 프로바이더 선택" icon="database">
|
||||
<CodeGroup>
|
||||
```python JsonProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import JsonProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
provider=JsonProvider(),
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
```python SqliteProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import SqliteProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./.checkpoints.db",
|
||||
provider=SqliteProvider(),
|
||||
max_checkpoints=50,
|
||||
),
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
SQLite는 동시 읽기를 위해 WAL 저널 모드를 활성화합니다. 고빈도 체크포인팅에는 SQLite를 선호하세요.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="특정 에이전트 옵트아웃" icon="user-slash">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[
|
||||
Agent(role="Researcher", ...),
|
||||
Agent(role="Writer", ..., checkpoint=False),
|
||||
],
|
||||
tasks=[...],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="새 브랜치로 포크" icon="code-branch">
|
||||
`fork()`는 새 lineage 아래에 체크포인트를 복원하여 새 실행이 원본과 충돌하지 않도록 합니다.
|
||||
|
||||
```python
|
||||
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
|
||||
crew = Crew.fork(config, branch="experiment-a")
|
||||
result = crew.kickoff(inputs={"strategy": "aggressive"})
|
||||
```
|
||||
|
||||
`branch` 레이블은 선택 사항이며, 생략하면 자동 생성됩니다.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Crew, Flow, Agent 체크포인트" icon="cubes">
|
||||
<Tabs>
|
||||
<Tab title="Crew">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
checkpoint=CheckpointConfig(location="./crew_cp"),
|
||||
)
|
||||
```
|
||||
|
||||
기본 트리거: `task_completed`.
|
||||
</Tab>
|
||||
<Tab title="Flow">
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start, listen
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
def step_one(self):
|
||||
return "data"
|
||||
|
||||
@listen(step_one)
|
||||
def step_two(self, data):
|
||||
return process(data)
|
||||
|
||||
flow = MyFlow(
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./flow_cp",
|
||||
on_events=["method_execution_finished"],
|
||||
),
|
||||
)
|
||||
result = flow.kickoff()
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Agent">
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./agent_cp",
|
||||
on_events=["lite_agent_execution_completed"],
|
||||
),
|
||||
)
|
||||
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="수동으로 체크포인트 기록" icon="code">
|
||||
모든 이벤트에 핸들러를 등록하고 `state.checkpoint()`를 호출합니다.
|
||||
|
||||
<CodeGroup>
|
||||
```python Sync
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = state.checkpoint("./my_checkpoints")
|
||||
print(f"체크포인트 저장: {path}")
|
||||
```
|
||||
```python Async
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = await state.acheckpoint("./my_checkpoints")
|
||||
print(f"체크포인트 저장: {path}")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
핸들러가 세 개의 매개변수를 받을 때 `state` 인수가 자동으로 제공됩니다. 전체 이벤트 카탈로그는 [Event Listeners](/ko/concepts/event-listener) 문서를 참조하세요.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="CLI에서 탐색, 재개, 포크" icon="terminal">
|
||||
```bash
|
||||
crewai checkpoint
|
||||
crewai checkpoint --location ./my_checkpoints
|
||||
crewai checkpoint --location ./.checkpoints.db
|
||||
```
|
||||
|
||||
<Frame caption="체크포인트 트리 — 브랜치와 포크가 부모 아래에 중첩됩니다.">
|
||||
<img src="/images/checkpoint-tui-tree.png" alt="Checkpoint TUI tree view" />
|
||||
</Frame>
|
||||
|
||||
왼쪽 패널은 체크포인트를 브랜치별로 그룹화하며, 포크는 부모 아래에 중첩됩니다. 체크포인트를 선택하면 메타데이터, 엔티티 상태, 태스크 진행 상황이 있는 세부 정보 패널이 열립니다. **Resume**은 실행을 계속하고, **Fork**는 새 브랜치를 시작합니다.
|
||||
|
||||
<Frame caption="개요 탭 — 메타데이터, 엔티티 상태, 실행 요약.">
|
||||
<img src="/images/checkpoint-tui-detail-overview.png" alt="Checkpoint detail overview tab" />
|
||||
</Frame>
|
||||
|
||||
세부 정보 패널에는 두 개의 편집 가능한 영역이 있습니다:
|
||||
|
||||
- **Inputs** — 원래 kickoff의 입력으로, 미리 채워져 있으며 편집 가능합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-inputs.png" alt="Editable kickoff inputs" />
|
||||
</Frame>
|
||||
|
||||
- **태스크 출력** — 완료된 태스크의 출력. 출력을 편집하고 **Fork**를 누르면 다운스트림 태스크가 무효화되어 수정된 컨텍스트로 다시 실행됩니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-tasks.png" alt="Editable task outputs" />
|
||||
</Frame>
|
||||
|
||||
<Frame caption="포크 화면 — 선택한 체크포인트에서 새 브랜치를 확인합니다.">
|
||||
<img src="/images/checkpoint-tui-details-fork.png" alt="Fork confirmation panel" />
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
"what if" 탐색에 유용합니다: 포크, 조정, 관찰.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="TUI 없이 체크포인트 검사" icon="magnifying-glass">
|
||||
```bash
|
||||
crewai checkpoint list ./my_checkpoints
|
||||
crewai checkpoint info ./my_checkpoints/<file>.json
|
||||
crewai checkpoint info ./.checkpoints.db
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 레퍼런스
|
||||
|
||||
### `CheckpointConfig`
|
||||
|
||||
<ParamField path="location" type="str" default='"./.checkpoints"'>
|
||||
스토리지 대상. `JsonProvider`는 디렉토리, `SqliteProvider`는 데이터베이스 파일 경로.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="on_events" type='list[CheckpointEventType | Literal["*"]]' default='["task_completed"]'>
|
||||
체크포인트를 트리거하는 이벤트 타입. `CheckpointEventType`은 `Literal`이므로 타입 체커가 자동 완성하고 지원되지 않는 값을 거부합니다. 전체 목록은 [이벤트 타입](#이벤트-타입) 참조.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="provider" type="BaseProvider" default="JsonProvider()">
|
||||
스토리지 백엔드. `JsonProvider` 또는 `SqliteProvider`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="max_checkpoints" type="int | None" default="None">
|
||||
보관할 최대 체크포인트 수. 각 기록 후 가장 오래된 것이 제거됩니다.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="restore_from" type="Path | str | None" default="None">
|
||||
`from_checkpoint`를 통해 전달될 때 복원할 체크포인트.
|
||||
</ParamField>
|
||||
|
||||
### `checkpoint` 필드 값
|
||||
|
||||
`Crew`, `Flow`, `Agent`에서 사용 가능.
|
||||
|
||||
<ParamField path="None" type="기본값">
|
||||
부모에서 상속.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="True" type="bool">
|
||||
기본값으로 활성화.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="False" type="bool">
|
||||
명시적 옵트아웃. 상속을 중단합니다.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="CheckpointConfig(...)" type="CheckpointConfig">
|
||||
사용자 정의 설정.
|
||||
</ParamField>
|
||||
|
||||
### 이벤트 타입
|
||||
|
||||
`on_events`는 `CheckpointEventType` 값의 임의 조합을 받습니다. 기본값 `["task_completed"]`는 완료된 태스크당 하나의 체크포인트를 기록하며, `["*"]`는 모든 이벤트와 일치합니다.
|
||||
|
||||
<Warning>
|
||||
`["*"]` 및 `llm_call_completed`와 같은 고빈도 이벤트는 많은 체크포인트를 기록하고 성능을 저하시킬 수 있습니다. `max_checkpoints`와 함께 사용하세요.
|
||||
</Warning>
|
||||
|
||||
<Expandable title="지원되는 모든 이벤트">
|
||||
|
||||
- **Task** — `task_started`, `task_completed`, `task_failed`, `task_evaluation`
|
||||
- **Crew** — `crew_kickoff_started`, `crew_kickoff_completed`, `crew_kickoff_failed`, `crew_train_started`, `crew_train_completed`, `crew_train_failed`, `crew_test_started`, `crew_test_completed`, `crew_test_failed`, `crew_test_result`
|
||||
- **Agent** — `agent_execution_started`, `agent_execution_completed`, `agent_execution_error`, `lite_agent_execution_started`, `lite_agent_execution_completed`, `lite_agent_execution_error`, `agent_evaluation_started`, `agent_evaluation_completed`, `agent_evaluation_failed`
|
||||
- **Flow** — `flow_created`, `flow_started`, `flow_finished`, `flow_paused`, `method_execution_started`, `method_execution_finished`, `method_execution_failed`, `method_execution_paused`, `human_feedback_requested`, `human_feedback_received`, `flow_input_requested`, `flow_input_received`
|
||||
- **LLM** — `llm_call_started`, `llm_call_completed`, `llm_call_failed`, `llm_stream_chunk`, `llm_thinking_chunk`
|
||||
- **LLM Guardrail** — `llm_guardrail_started`, `llm_guardrail_completed`, `llm_guardrail_failed`
|
||||
- **Tool** — `tool_usage_started`, `tool_usage_finished`, `tool_usage_error`, `tool_validate_input_error`, `tool_selection_error`, `tool_execution_error`
|
||||
- **Memory** — `memory_save_started`, `memory_save_completed`, `memory_save_failed`, `memory_query_started`, `memory_query_completed`, `memory_query_failed`, `memory_retrieval_started`, `memory_retrieval_completed`, `memory_retrieval_failed`
|
||||
- **Knowledge** — `knowledge_search_query_started`, `knowledge_search_query_completed`, `knowledge_query_started`, `knowledge_query_completed`, `knowledge_query_failed`, `knowledge_search_query_failed`
|
||||
- **Reasoning** — `agent_reasoning_started`, `agent_reasoning_completed`, `agent_reasoning_failed`
|
||||
- **MCP** — `mcp_connection_started`, `mcp_connection_completed`, `mcp_connection_failed`, `mcp_tool_execution_started`, `mcp_tool_execution_completed`, `mcp_tool_execution_failed`, `mcp_config_fetch_failed`
|
||||
- **Observation** — `step_observation_started`, `step_observation_completed`, `step_observation_failed`, `plan_refinement`, `plan_replan_triggered`, `goal_achieved_early`
|
||||
- **Skill** — `skill_discovery_started`, `skill_discovery_completed`, `skill_loaded`, `skill_activated`, `skill_load_failed`
|
||||
- **Logging** — `agent_logs_started`, `agent_logs_execution`
|
||||
- **A2A** — `a2a_delegation_started`, `a2a_delegation_completed`, `a2a_conversation_started`, `a2a_conversation_completed`, `a2a_message_sent`, `a2a_response_received`, `a2a_polling_started`, `a2a_polling_status`, `a2a_push_notification_registered`, `a2a_push_notification_received`, `a2a_push_notification_sent`, `a2a_push_notification_timeout`, `a2a_streaming_started`, `a2a_streaming_chunk`, `a2a_agent_card_fetched`, `a2a_authentication_failed`, `a2a_artifact_received`, `a2a_connection_error`, `a2a_server_task_started`, `a2a_server_task_completed`, `a2a_server_task_canceled`, `a2a_server_task_failed`, `a2a_parallel_delegation_started`, `a2a_parallel_delegation_completed`, `a2a_transport_negotiated`, `a2a_content_type_negotiated`, `a2a_context_created`, `a2a_context_expired`, `a2a_context_idle`, `a2a_context_completed`, `a2a_context_pruned`
|
||||
- **시스템 시그널** — `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGTSTP`, `SIGCONT`
|
||||
- **와일드카드** — `"*"`는 모든 이벤트와 일치합니다.
|
||||
|
||||
</Expandable>
|
||||
|
||||
### 스토리지 프로바이더
|
||||
|
||||
<ParamField path="JsonProvider" type="provider">
|
||||
체크포인트당 하나의 파일, `location` 내부에 `<timestamp>_<uuid>.json` 형식으로 명명.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="SqliteProvider" type="provider">
|
||||
WAL 저널링이 있는 `location`의 단일 데이터베이스 파일.
|
||||
</ParamField>
|
||||
|
||||
### CLI
|
||||
|
||||
| 명령 | 목적 |
|
||||
|:-----|:-----|
|
||||
| `crewai checkpoint` | TUI 실행; 스토리지 자동 감지. |
|
||||
| `crewai checkpoint --location <path>` | 특정 위치에 대해 TUI 실행. |
|
||||
| `crewai checkpoint list <path>` | 체크포인트 나열. |
|
||||
| `crewai checkpoint info <path>` | 체크포인트 파일 또는 SQLite 데이터베이스의 최신 항목 검사. |
|
||||
441
docs/edge/ko/concepts/cli.mdx
Normal file
441
docs/edge/ko/concepts/cli.mdx
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
title: CLI
|
||||
description: CrewAI CLI를 사용하여 CrewAI와 상호 작용하는 방법을 알아보세요.
|
||||
icon: terminal
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
릴리즈 0.140.0부터 CrewAI AOP는 로그인 제공자 마이그레이션 프로세스를
|
||||
시작했습니다. 이에 따라 CLI를 통한 인증 흐름이 업데이트되었습니다. Google을
|
||||
통해 로그인하거나 2025년 7월 3일 이후에 계정을 생성한 사용자는 이전 버전의
|
||||
`crewai` 라이브러리로는 로그인할 수 없습니다.
|
||||
</Warning>
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI CLI는 CrewAI와 상호작용할 수 있는 명령어 세트를 제공하여 crew 및 flow를 생성, 학습, 실행, 관리할 수 있습니다.
|
||||
|
||||
## 설치
|
||||
|
||||
CrewAI CLI를 사용하려면, CrewAI가 설치되어 있어야 합니다:
|
||||
|
||||
```shell Terminal
|
||||
pip install crewai
|
||||
```
|
||||
|
||||
## 기본 사용법
|
||||
|
||||
CrewAI CLI 명령어의 기본 구조는 다음과 같습니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai [COMMAND] [OPTIONS] [ARGUMENTS]
|
||||
```
|
||||
|
||||
## 사용 가능한 명령어
|
||||
|
||||
### 1. 생성
|
||||
|
||||
새로운 crew 또는 flow를 생성합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai create [OPTIONS] TYPE NAME
|
||||
```
|
||||
|
||||
- `TYPE`: "crew" 또는 "flow" 중에서 선택
|
||||
- `NAME`: crew 또는 flow의 이름
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai create crew my_new_crew
|
||||
crewai create flow my_new_flow
|
||||
```
|
||||
|
||||
기본적으로 `crewai create crew`는 `crew.jsonc`와 `agents/*.jsonc`가 있는 JSON-first 프로젝트를 만듭니다. `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요할 때만 `crewai create crew my_new_crew --classic`을 사용하세요.
|
||||
|
||||
### 2. 버전
|
||||
|
||||
설치된 CrewAI의 버전을 표시합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai version [OPTIONS]
|
||||
```
|
||||
|
||||
- `--tools`: (선택 사항) 설치된 CrewAI tools의 버전을 표시합니다.
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai version
|
||||
crewai version --tools
|
||||
```
|
||||
|
||||
### 3. 훈련
|
||||
|
||||
지정된 횟수만큼 crew를 훈련시킵니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai train [OPTIONS]
|
||||
```
|
||||
|
||||
- `-n, --n_iterations INTEGER`: crew를 훈련할 반복 횟수 (기본값: 5)
|
||||
- `-f, --filename TEXT`: 훈련에 사용할 커스텀 파일의 경로 (기본값: "trained_agents_data.pkl")
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai train -n 10 -f my_training_data.pkl
|
||||
```
|
||||
|
||||
### 4. 다시 실행
|
||||
|
||||
특정 task에서 crew 실행을 다시 재생합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai replay [OPTIONS]
|
||||
```
|
||||
|
||||
- `-t, --task_id TEXT`: 이 task ID에서부터 crew를 다시 재생하며, 이후의 모든 task를 포함합니다.
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai replay -t task_123456
|
||||
```
|
||||
|
||||
### 5. Log-tasks-outputs
|
||||
|
||||
가장 최근의 crew.kickoff() 작업 결과를 조회합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai log-tasks-outputs
|
||||
```
|
||||
|
||||
### 6. Reset-memories
|
||||
|
||||
크루의 메모리(롱, 쇼트, 엔티티, latest_crew_kickoff_outputs)를 초기화합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai reset-memories [OPTIONS]
|
||||
```
|
||||
|
||||
- `-l, --long`: LONG TERM 메모리 초기화
|
||||
- `-s, --short`: SHORT TERM 메모리 초기화
|
||||
- `-e, --entities`: ENTITIES 메모리 초기화
|
||||
- `-k, --kickoff-outputs`: LATEST KICKOFF TASK OUTPUTS 초기화
|
||||
- `-kn, --knowledge`: KNOWLEDGE 저장소 초기화
|
||||
- `-akn, --agent-knowledge`: AGENT KNOWLEDGE 저장소 초기화
|
||||
- `-a, --all`: 모든 메모리 초기화
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai reset-memories --long --short
|
||||
crewai reset-memories --all
|
||||
```
|
||||
|
||||
### 7. 테스트
|
||||
|
||||
crew를 테스트하고 결과를 평가합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai test [OPTIONS]
|
||||
```
|
||||
|
||||
- `-n, --n_iterations INTEGER`: crew를 테스트할 반복 횟수 (기본값: 3)
|
||||
- `-m, --model TEXT`: Crew에서 테스트를 실행할 LLM 모델 (기본값: "gpt-4o-mini")
|
||||
|
||||
예시:
|
||||
|
||||
```shell Terminal
|
||||
crewai test -n 5 -m gpt-3.5-turbo
|
||||
```
|
||||
|
||||
### 8. 실행
|
||||
|
||||
crew 또는 flow를 실행합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai run
|
||||
```
|
||||
|
||||
<Note>
|
||||
버전 0.103.0부터 `crewai run` 명령은 표준 crew와 flow 모두를 실행하는 데
|
||||
사용할 수 있습니다. flow의 경우 pyproject.toml에서 유형을 자동으로 감지하여
|
||||
적절한 명령을 실행합니다. 이제 crew와 flow 모두를 실행하는 권장 방법입니다.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
이 명령들은 CrewAI 프로젝트가 설정된 디렉터리에서 실행해야 합니다. 일부 명령은
|
||||
프로젝트 구조 내에서 추가 구성 또는 설정이 필요할 수 있습니다.
|
||||
</Note>
|
||||
|
||||
### 9. Chat
|
||||
|
||||
버전 `0.98.0`부터 `crewai chat` 명령어를 실행하면 크루와의 대화형 세션이 시작됩니다. AI 어시스턴트가 크루를 실행하는 데 필요한 입력값을 요청하며 안내합니다. 모든 입력값이 제공되면 크루가 작업을 실행합니다.
|
||||
|
||||
결과를 받은 후에도 추가 지시나 질문을 위해 어시스턴트와 계속 상호작용할 수 있습니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai chat
|
||||
```
|
||||
|
||||
<Note>
|
||||
이 명령어들은 CrewAI 프로젝트의 루트 디렉터리에서 실행해야 합니다.
|
||||
</Note>
|
||||
<Note>
|
||||
중요: 이 명령어를 사용하려면 crew 정의에 `chat_llm` 속성을 설정해야 합니다.
|
||||
|
||||
JSON-first crew에서는 `crew.jsonc`에 추가합니다:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "My Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [],
|
||||
"chat_llm": "openai/gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
클래식 Python/YAML crew에서는 `crew.py`에 설정합니다:
|
||||
|
||||
```python
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
chat_llm="gpt-4o", # LLM for chat orchestration
|
||||
)
|
||||
```
|
||||
|
||||
</Note>
|
||||
|
||||
### 10. 배포
|
||||
|
||||
crew 또는 flow를 [CrewAI AMP](https://app.crewai.com)에 배포하세요.
|
||||
|
||||
- **인증**: CrewAI AOP에 배포하려면 인증이 필요합니다.
|
||||
아래 명령어로 로그인하거나 계정을 생성할 수 있습니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai login
|
||||
```
|
||||
|
||||
- **배포 생성**: 인증이 완료되면, 로컬 프로젝트의 루트에서 crew 또는 flow에 대한 배포를 생성할 수 있습니다.
|
||||
```shell Terminal
|
||||
crewai deploy create
|
||||
```
|
||||
- 로컬 프로젝트 구성을 읽어옵니다.
|
||||
- 로컬에서 확인된 환경 변수(`OPENAI_API_KEY`, `SERPER_API_KEY` 등)를 확인하도록 안내합니다. 이 변수들은 Enterprise 플랫폼에 배포할 때 안전하게 저장됩니다. 실행 전에 중요한 키가 로컬(예: `.env` 파일)에 올바르게 구성되어 있는지 확인하세요.
|
||||
|
||||
### 11. 조직 관리
|
||||
|
||||
CrewAI AMP 조직을 관리합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai org [COMMAND] [OPTIONS]
|
||||
```
|
||||
|
||||
#### 명령어:
|
||||
|
||||
- `list`: 사용자가 속한 모든 조직을 나열합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai org list
|
||||
```
|
||||
|
||||
- `current`: 현재 활성화된 조직을 표시합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai org current
|
||||
```
|
||||
|
||||
- `switch`: 특정 조직으로 전환합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai org switch <organization_id>
|
||||
```
|
||||
|
||||
<Note>
|
||||
이러한 조직 관리 명령어를 사용하려면 CrewAI AOP에 인증되어 있어야 합니다.
|
||||
</Note>
|
||||
|
||||
- **배포 생성** (계속):
|
||||
|
||||
- 배포를 해당 원격 GitHub 저장소에 연결합니다 (일반적으로 자동으로 감지됩니다).
|
||||
|
||||
- **Crew 배포**: 인증이 완료되면 crew 또는 flow를 CrewAI AOP에 배포할 수 있습니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy push
|
||||
```
|
||||
|
||||
- CrewAI AMP 플랫폼에서 배포 프로세스를 시작합니다.
|
||||
- 성공적으로 시작되면, Deployment created successfully! 메시지와 함께 Deployment Name 및 고유한 Deployment ID(UUID)가 출력됩니다.
|
||||
|
||||
- **배포 상태**: 배포 상태를 확인하려면 다음을 사용합니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy status
|
||||
```
|
||||
|
||||
이 명령은 가장 최근의 배포 시도에 대한 최신 배포 상태(예: `Building Images for Crew`, `Deploy Enqueued`, `Online`)를 가져옵니다.
|
||||
|
||||
- **배포 로그**: 배포 로그를 확인하려면 다음을 사용합니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy logs
|
||||
```
|
||||
|
||||
이 명령은 배포 로그를 터미널로 스트리밍합니다.
|
||||
|
||||
- **배포 목록**: 모든 배포를 나열하려면 다음을 사용합니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy list
|
||||
```
|
||||
|
||||
이 명령은 모든 배포를 나열합니다.
|
||||
|
||||
- **배포 삭제**: 배포를 삭제하려면 다음을 사용합니다:
|
||||
|
||||
```shell Terminal
|
||||
crewai deploy remove
|
||||
```
|
||||
|
||||
이 명령은 CrewAI AMP 플랫폼에서 배포를 삭제합니다.
|
||||
|
||||
- **도움말 명령어**: CLI에 대한 도움말을 보려면 다음을 사용합니다:
|
||||
```shell Terminal
|
||||
crewai deploy --help
|
||||
```
|
||||
이 명령은 CrewAI Deploy CLI에 대한 도움말 메시지를 표시합니다.
|
||||
|
||||
CLI를 사용하여 [CrewAI AMP](http://app.crewai.com)에 crew를 배포하는 단계별 시연은 아래 비디오 튜토리얼을 참조하십시오.
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/3EqSV-CYDZA"
|
||||
title="CrewAI Deployment Guide"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
### 11. API 키
|
||||
|
||||
`crewai create crew` 명령어를 실행하면, CLI에서 선택할 수 있는 LLM 제공업체 목록이 표시되고, 그 다음으로 선택한 제공업체에 대한 모델 선택이 이어집니다. 선택한 모델은 생성된 `.env`에 저장되며 각 에이전트 JSONC 파일은 자체 `llm`을 설정할 수 있습니다.
|
||||
|
||||
LLM 제공업체와 모델을 선택하면, API 키를 입력하라는 메시지가 표시됩니다.
|
||||
|
||||
#### 사용 가능한 LLM 공급자
|
||||
|
||||
다음은 CLI에서 제안하는 가장 인기 있는 LLM 공급자 목록입니다:
|
||||
|
||||
- OpenAI
|
||||
- Groq
|
||||
- Anthropic
|
||||
- Google Gemini
|
||||
- SambaNova
|
||||
|
||||
공급자를 선택하면, CLI가 해당 공급자에서 사용 가능한 모델을 보여주고 API 키 입력을 요청합니다.
|
||||
|
||||
#### 기타 옵션
|
||||
|
||||
"기타"를 선택하면 LiteLLM에서 지원하는 공급자 목록에서 선택할 수 있습니다.
|
||||
|
||||
공급자를 선택하면 CLI에서 Key 이름과 API 키 입력을 요청합니다.
|
||||
|
||||
각 공급자의 Key 이름은 다음 링크에서 확인할 수 있습니다:
|
||||
|
||||
- [LiteLLM 공급자](https://docs.litellm.ai/docs/providers)
|
||||
|
||||
### 12. 구성 관리
|
||||
|
||||
CrewAI의 CLI 구성 설정을 관리합니다.
|
||||
|
||||
```shell Terminal
|
||||
crewai config [COMMAND] [OPTIONS]
|
||||
```
|
||||
|
||||
#### 명령어:
|
||||
|
||||
- `list`: 모든 CLI 구성 매개변수 표시
|
||||
|
||||
```shell Terminal
|
||||
crewai config list
|
||||
```
|
||||
|
||||
- `set`: CLI 구성 매개변수 설정
|
||||
|
||||
```shell Terminal
|
||||
crewai config set <key> <value>
|
||||
```
|
||||
|
||||
- `reset`: 모든 CLI 구성 매개변수를 기본값으로 초기화
|
||||
|
||||
```shell Terminal
|
||||
crewai config reset
|
||||
```
|
||||
|
||||
#### 사용 가능한 구성 파라미터
|
||||
|
||||
- `enterprise_base_url`: CrewAI AMP 인스턴스의 기본 URL
|
||||
- `oauth2_provider`: 인증에 사용되는 OAuth2 공급자 (예: workos, okta, auth0)
|
||||
- `oauth2_audience`: OAuth2 audience 값으로, 일반적으로 대상 API 또는 리소스를 식별하는 데 사용됨
|
||||
- `oauth2_client_id`: 인증 요청 시 사용되는 공급자가 발급한 OAuth2 클라이언트 ID
|
||||
- `oauth2_domain`: 토큰 발급에 사용되는 OAuth2 공급자의 도메인 (예: your-org.auth0.com)
|
||||
|
||||
#### 예시
|
||||
|
||||
현재 설정 표시:
|
||||
|
||||
```shell Terminal
|
||||
crewai config list
|
||||
```
|
||||
|
||||
예시 출력:
|
||||
|
||||
| 설정 | 값 | 설명 |
|
||||
| :------------------ | :--------------------- | :------------------------------------------------------------------- |
|
||||
| enterprise_base_url | https://app.crewai.com | CrewAI AMP 인스턴스의 기본 URL |
|
||||
| org_name | Not set | 현재 활성화된 조직의 이름 |
|
||||
| org_uuid | Not set | 현재 활성화된 조직의 UUID |
|
||||
| oauth2_provider | workos | 인증에 사용되는 OAuth2 제공자 (예: workos, okta, auth0) |
|
||||
| oauth2_audience | client_01YYY | 일반적으로 대상 API/리소스를 식별하는 데 사용되는 OAuth2 audience 값 |
|
||||
| oauth2_client_id | client_01XXX | 제공자로부터 발급된 OAuth2 client ID (인증 요청 시 사용) |
|
||||
| oauth2_domain | login.crewai.com | OAuth2 제공자의 도메인 (예: your-org.auth0.com) |
|
||||
|
||||
엔터프라이즈 기본 URL 설정:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set enterprise_base_url https://my-enterprise.crewai.com
|
||||
```
|
||||
|
||||
OAuth2 제공자 설정:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set oauth2_provider auth0
|
||||
```
|
||||
|
||||
OAuth2 도메인 설정:
|
||||
|
||||
```shell Terminal
|
||||
crewai config set oauth2_domain my-company.auth0.com
|
||||
```
|
||||
|
||||
모든 설정을 기본값으로 재설정:
|
||||
|
||||
```shell Terminal
|
||||
crewai config reset
|
||||
```
|
||||
|
||||
<Note>
|
||||
설정 값은 `~/.config/crewai/settings.json`에 저장됩니다. 조직 이름과 UUID와
|
||||
같은 일부 설정 값은 읽기 전용이며 인증 및 조직 명령을 통해 관리됩니다. 도구
|
||||
저장소 관련 설정은 숨겨져 있으며 사용자가 직접 설정할 수 없습니다.
|
||||
</Note>
|
||||
363
docs/edge/ko/concepts/collaboration.mdx
Normal file
363
docs/edge/ko/concepts/collaboration.mdx
Normal file
@@ -0,0 +1,363 @@
|
||||
---
|
||||
title: 협업
|
||||
description: CrewAI 팀 내에서 에이전트가 함께 작업하고, 작업을 위임하며, 효과적으로 소통하는 방법에 대해 설명합니다.
|
||||
icon: screen-users
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI에서의 협업은 에이전트들이 팀으로서 함께 작업하며, 각자의 전문성을 활용하기 위해 작업을 위임하고 질문을 주고받을 수 있도록 합니다. `allow_delegation=True`로 설정하면, 에이전트들은 자동으로 강력한 협업 도구에 접근할 수 있습니다.
|
||||
|
||||
## 빠른 시작: 협업 활성화
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
# Enable collaboration for agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Conduct thorough research on any topic",
|
||||
backstory="Expert researcher with access to various sources",
|
||||
allow_delegation=True, # 🔑 Key setting for collaboration
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Create engaging content based on research",
|
||||
backstory="Skilled writer who transforms research into compelling content",
|
||||
allow_delegation=True, # 🔑 Enables asking questions to other agents
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Agents can now collaborate automatically
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[...],
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## 에이전트 협업 방식
|
||||
|
||||
`allow_delegation=True`로 설정하면, CrewAI는 에이전트에게 두 가지 강력한 도구를 자동으로 제공합니다.
|
||||
|
||||
### 1. **업무 위임 도구**
|
||||
에이전트가 특정 전문성을 가진 팀원에게 작업을 할당할 수 있습니다.
|
||||
|
||||
```python
|
||||
# Agent automatically gets this tool:
|
||||
# Delegate work to coworker(task: str, context: str, coworker: str)
|
||||
```
|
||||
|
||||
### 2. **질문하기 도구**
|
||||
에이전트가 동료로부터 정보를 수집하기 위해 특정 질문을 할 수 있게 해줍니다.
|
||||
|
||||
```python
|
||||
# Agent automatically gets this tool:
|
||||
# Ask question to coworker(question: str, context: str, coworker: str)
|
||||
```
|
||||
|
||||
## 협업의 실제
|
||||
|
||||
아래는 에이전트들이 콘텐츠 제작 작업에 협력하는 완성된 예시입니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
|
||||
# Create collaborative agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Find accurate, up-to-date information on any topic",
|
||||
backstory="""You're a meticulous researcher with expertise in finding
|
||||
reliable sources and fact-checking information across various domains.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Create engaging, well-structured content",
|
||||
backstory="""You're a skilled content writer who excels at transforming
|
||||
research into compelling, readable content for different audiences.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
editor = Agent(
|
||||
role="Content Editor",
|
||||
goal="Ensure content quality and consistency",
|
||||
backstory="""You're an experienced editor with an eye for detail,
|
||||
ensuring content meets high standards for clarity and accuracy.""",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Create a task that encourages collaboration
|
||||
article_task = Task(
|
||||
description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'.
|
||||
|
||||
The article should include:
|
||||
- Current AI applications in healthcare
|
||||
- Emerging trends and technologies
|
||||
- Potential challenges and ethical considerations
|
||||
- Expert predictions for the next 5 years
|
||||
|
||||
Collaborate with your teammates to ensure accuracy and quality.""",
|
||||
expected_output="A well-researched, engaging 1000-word article with proper structure and citations",
|
||||
agent=writer # Writer leads, but can delegate research to researcher
|
||||
)
|
||||
|
||||
# Create collaborative crew
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, editor],
|
||||
tasks=[article_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
## 협업 패턴
|
||||
|
||||
### 패턴 1: 조사 → 작성 → 편집
|
||||
```python
|
||||
research_task = Task(
|
||||
description="Research the latest developments in quantum computing",
|
||||
expected_output="Comprehensive research summary with key findings and sources",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description="Write an article based on the research findings",
|
||||
expected_output="Engaging 800-word article about quantum computing",
|
||||
agent=writer,
|
||||
context=[research_task] # Gets research output as context
|
||||
)
|
||||
|
||||
editing_task = Task(
|
||||
description="Edit and polish the article for publication",
|
||||
expected_output="Publication-ready article with improved clarity and flow",
|
||||
agent=editor,
|
||||
context=[writing_task] # Gets article draft as context
|
||||
)
|
||||
```
|
||||
|
||||
### 패턴 2: 협업 단일 작업
|
||||
```python
|
||||
collaborative_task = Task(
|
||||
description="""Create a marketing strategy for a new AI product.
|
||||
|
||||
Writer: Focus on messaging and content strategy
|
||||
Researcher: Provide market analysis and competitor insights
|
||||
|
||||
Work together to create a comprehensive strategy.""",
|
||||
expected_output="Complete marketing strategy with research backing",
|
||||
agent=writer # Lead agent, but can delegate to researcher
|
||||
)
|
||||
```
|
||||
|
||||
## 계층적 협업
|
||||
|
||||
복잡한 프로젝트의 경우, 매니저 에이전트를 활용하여 계층적 프로세스를 사용하세요:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
|
||||
# Manager agent coordinates the team
|
||||
manager = Agent(
|
||||
role="Project Manager",
|
||||
goal="Coordinate team efforts and ensure project success",
|
||||
backstory="Experienced project manager skilled at delegation and quality control",
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Specialist agents
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Provide accurate research and analysis",
|
||||
backstory="Expert researcher with deep analytical skills",
|
||||
allow_delegation=False, # Specialists focus on their expertise
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Writer",
|
||||
goal="Create compelling content",
|
||||
backstory="Skilled writer who creates engaging content",
|
||||
allow_delegation=False,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Manager-led task
|
||||
project_task = Task(
|
||||
description="Create a comprehensive market analysis report with recommendations",
|
||||
expected_output="Executive summary, detailed analysis, and strategic recommendations",
|
||||
agent=manager # Manager will delegate to specialists
|
||||
)
|
||||
|
||||
# Hierarchical crew
|
||||
crew = Crew(
|
||||
agents=[manager, researcher, writer],
|
||||
tasks=[project_task],
|
||||
process=Process.hierarchical, # Manager coordinates everything
|
||||
manager_llm="gpt-4o", # Specify LLM for manager
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## 협업을 위한 모범 사례
|
||||
|
||||
### 1. **명확한 역할 정의**
|
||||
```python
|
||||
# ✅ Good: Specific, complementary roles
|
||||
researcher = Agent(role="Market Research Analyst", ...)
|
||||
writer = Agent(role="Technical Content Writer", ...)
|
||||
|
||||
# ❌ Avoid: Overlapping or vague roles
|
||||
agent1 = Agent(role="General Assistant", ...)
|
||||
agent2 = Agent(role="Helper", ...)
|
||||
```
|
||||
|
||||
### 2. **전략적 위임 활성화**
|
||||
```python
|
||||
# ✅ Enable delegation for coordinators and generalists
|
||||
lead_agent = Agent(
|
||||
role="Content Lead",
|
||||
allow_delegation=True, # Can delegate to specialists
|
||||
...
|
||||
)
|
||||
|
||||
# ✅ Disable for focused specialists (optional)
|
||||
specialist_agent = Agent(
|
||||
role="Data Analyst",
|
||||
allow_delegation=False, # Focuses on core expertise
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 3. **컨텍스트 공유**
|
||||
```python
|
||||
# ✅ Use context parameter for task dependencies
|
||||
writing_task = Task(
|
||||
description="Write article based on research",
|
||||
agent=writer,
|
||||
context=[research_task], # Shares research results
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 4. **명확한 작업 설명**
|
||||
```python
|
||||
# ✅ 구체적이고 실행 가능한 설명
|
||||
Task(
|
||||
description="""Research competitors in the AI chatbot space.
|
||||
Focus on: pricing models, key features, target markets.
|
||||
Provide data in a structured format.""",
|
||||
...
|
||||
)
|
||||
|
||||
# ❌ 협업에 도움이 되지 않는 모호한 설명
|
||||
Task(description="Do some research about chatbots", ...)
|
||||
```
|
||||
|
||||
## 협업 문제 해결
|
||||
|
||||
### 문제: 에이전트들이 협업하지 않음
|
||||
**증상:** 에이전트들이 각자 작업하며, 위임이 이루어지지 않음
|
||||
```python
|
||||
# ✅ Solution: Ensure delegation is enabled
|
||||
agent = Agent(
|
||||
role="...",
|
||||
allow_delegation=True, # This is required!
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 문제: 지나친 이중 확인
|
||||
**증상:** 에이전트가 과도하게 질문을 하여 진행이 느려짐
|
||||
```python
|
||||
# ✅ Solution: Provide better context and specific roles
|
||||
Task(
|
||||
description="""Write a technical blog post about machine learning.
|
||||
|
||||
Context: Target audience is software developers with basic ML knowledge.
|
||||
Length: 1200 words
|
||||
Include: code examples, practical applications, best practices
|
||||
|
||||
If you need specific technical details, delegate research to the researcher.""",
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### 문제: 위임 루프
|
||||
**증상:** 에이전트들이 무한히 서로에게 위임함
|
||||
```python
|
||||
# ✅ Solution: Clear hierarchy and responsibilities
|
||||
manager = Agent(role="Manager", allow_delegation=True)
|
||||
specialist1 = Agent(role="Specialist A", allow_delegation=False) # No re-delegation
|
||||
specialist2 = Agent(role="Specialist B", allow_delegation=False)
|
||||
```
|
||||
|
||||
## 고급 협업 기능
|
||||
|
||||
### 맞춤 협업 규칙
|
||||
```python
|
||||
# Set specific collaboration guidelines in agent backstory
|
||||
agent = Agent(
|
||||
role="Senior Developer",
|
||||
backstory="""You lead development projects and coordinate with team members.
|
||||
|
||||
Collaboration guidelines:
|
||||
- Delegate research tasks to the Research Analyst
|
||||
- Ask the Designer for UI/UX guidance
|
||||
- Consult the QA Engineer for testing strategies
|
||||
- Only escalate blocking issues to the Project Manager""",
|
||||
allow_delegation=True
|
||||
)
|
||||
```
|
||||
|
||||
### 협업 모니터링
|
||||
```python
|
||||
def track_collaboration(output):
|
||||
"""Track collaboration patterns"""
|
||||
if "Delegate work to coworker" in output.raw:
|
||||
print("🤝 Delegation occurred")
|
||||
if "Ask question to coworker" in output.raw:
|
||||
print("❓ Question asked")
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
step_callback=track_collaboration, # Monitor collaboration
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
## 메모리와 학습
|
||||
|
||||
에이전트가 과거 협업을 기억할 수 있도록 합니다:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Content Lead",
|
||||
memory=True, # Remembers past interactions
|
||||
allow_delegation=True,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
메모리가 활성화되면, 에이전트는 이전 협업에서 학습하여 시간이 지남에 따라 더 나은 위임 결정을 내릴 수 있습니다.
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- **예제 시도하기**: 기본 협업 예제부터 시작하세요
|
||||
- **역할 실험하기**: 다양한 에이전트 역할 조합을 테스트해 보세요
|
||||
- **상호작용 모니터링**: 협업 과정을 직접 보려면 `verbose=True`를 사용하세요
|
||||
- **작업 설명 최적화**: 명확한 작업이 더 나은 협업으로 이어집니다
|
||||
- **확장하기**: 복잡한 프로젝트에는 계층적 프로세스를 시도해 보세요
|
||||
|
||||
협업은 개별 AI 에이전트를 복잡하고 다면적인 문제를 함께 해결할 수 있는 강력한 팀으로 변화시킵니다.
|
||||
460
docs/edge/ko/concepts/crews.mdx
Normal file
460
docs/edge/ko/concepts/crews.mdx
Normal file
@@ -0,0 +1,460 @@
|
||||
---
|
||||
title: 크루
|
||||
description: crewAI 프레임워크에서 크루를 이해하고 다양한 속성과 기능을 활용하기.
|
||||
icon: people-group
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
crewAI에서 crew는 일련의 작업을 달성하기 위해 함께 협력하는 에이전트들의 그룹을 나타냅니다. 각 crew는 작업 실행, 에이전트 간 협업, 그리고 전체 워크플로우에 대한 전략을 정의합니다.
|
||||
|
||||
## Crew 속성
|
||||
|
||||
| 속성 | 파라미터 | 설명 |
|
||||
| :-------------------------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Tasks** | `tasks` | crew에 할당된 작업들의 리스트. |
|
||||
| **Agents** | `agents` | crew의 일원이 되는 에이전트들의 리스트. |
|
||||
| **Process** _(선택사항)_ | `process` | crew가 따르는 프로세스 플로우(예: 순차, 계층적). 기본값은 `sequential`. |
|
||||
| **Verbose** _(선택사항)_ | `verbose` | 실행 중 로그의 상세도 설정. 기본값은 `False`. |
|
||||
| **Manager LLM** _(선택사항)_ | `manager_llm` | 계층적 프로세스에서 매니저 에이전트가 사용하는 언어 모델. **계층적 프로세스를 사용할 때 필수.** |
|
||||
| **Function Calling LLM** _(선택사항)_ | `function_calling_llm` | 전달 시, crew 전체의 모든 agent에 대해 도구의 function calling에 이 LLM을 사용. 각 agent마다 개별 LLM을 가질 수 있으며, 이 경우 crew의 function calling LLM을 오버라이드 함. |
|
||||
| **Config** _(선택사항)_ | `config` | crew용으로 선택적인 구성 설정. `Json` 또는 `Dict[str, Any]` 형식 사용. |
|
||||
| **Max RPM** _(선택사항)_ | `max_rpm` | 실행 중 crew가 준수하는 분당 최대 요청 수. 기본값은 `None`. |
|
||||
| **Memory** _(선택사항)_ | `memory` | 실행 메모리(단기, 장기, 엔터티 메모리) 저장에 사용됨. |
|
||||
| **Cache** _(선택사항)_ | `cache` | 도구 실행 결과를 캐시에 저장할지 여부. 기본값은 `True`. |
|
||||
| **Embedder** _(선택사항)_ | `embedder` | crew에서 사용할 embedder 설정. 현재는 주로 메모리에서 사용. 기본값은 `{"provider": "openai"}`. |
|
||||
| **Step Callback** _(선택사항)_ | `step_callback` | 각 agent의 단계가 끝난 후 호출되는 함수. agent의 작업 기록이나 기타 작업 수행에 사용 가능; agent별 `step_callback`을 오버라이드하지 않음. |
|
||||
| **Task Callback** _(선택사항)_ | `task_callback` | 각 작업 완료 후 호출되는 함수. 작업 실행 후 모니터링이나 추가 작업에 유용. |
|
||||
| **Share Crew** _(선택사항)_ | `share_crew` | 라이브러리 개선 및 모델 학습을 위해 crew 정보와 실행을 crewAI 팀에 공유할지 여부. |
|
||||
| **Output Log File** _(선택사항)_ | `output_log_file` | `True`로 설정 시 로그를 현재 디렉터리에 logs.txt로 저장하거나 파일 경로 지정 가능. 파일명이 .json으로 끝나면 JSON 형식, 아니면 txt 형식으로 로그를 저장. 기본값은 `None`. |
|
||||
| **Manager Agent** _(선택사항)_ | `manager_agent` | 매니저로 사용할 커스텀 agent를 설정. |
|
||||
| **Prompt File** _(선택사항)_ | `prompt_file` | crew에서 사용할 prompt JSON 파일 경로. |
|
||||
| **Planning** *(선택사항)* | `planning` | Crew에 계획 수립 기능을 추가. 활성화하면 각 Crew 반복 전에 모든 Crew 데이터를 AgentPlanner로 전송하여 작업계획을 세우고, 이 계획이 각 작업 설명에 추가됨. |
|
||||
| **Planning LLM** *(선택사항)* | `planning_llm` | 계획 과정에서 AgentPlanner가 사용하는 언어 모델. |
|
||||
| **Knowledge Sources** _(선택사항)_ | `knowledge_sources` | crew 수준에서 사용 가능한 지식 소스. 모든 agent가 접근 가능. |
|
||||
| **Stream** _(선택사항)_ | `stream` | 스트리밍 출력을 활성화하여 crew 실행 중 실시간 업데이트를 받을 수 있습니다. 청크를 반복할 수 있는 `CrewStreamingOutput` 객체를 반환합니다. 기본값은 `False`. |
|
||||
|
||||
<Tip>
|
||||
**Crew Max RPM**: `max_rpm` 속성은 crew가 분당 처리할 수 있는 최대 요청 수를 설정하며, 개별 agent의 `max_rpm` 설정을 crew 단위로 지정할 경우 오버라이드합니다.
|
||||
</Tip>
|
||||
|
||||
## 크루 생성하기
|
||||
|
||||
CrewAI에서 크루를 생성하는 주요 방법은 **JSONC 구성(새 crew 권장)**을 사용하는 방법과 클래식 프로젝트나 고급 사용 사례에서 **코드로 직접 정의**하는 방법입니다.
|
||||
|
||||
### JSONC 구성 (권장)
|
||||
|
||||
`crewai create crew <name>`으로 만든 새 프로젝트는 crew 수준 설정과 태스크를 `crew.jsonc`에 두고, 각 에이전트를 `agents/`의 별도 파일에 둡니다. `crewai run`은 `crew.jsonc` 또는 `crew.json`을 감지해 에이전트를 로드하고, 빠진 placeholder 값을 물은 뒤 crew를 시작합니다.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Market Research Crew",
|
||||
"agents": ["researcher", "analyst"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research",
|
||||
"description": "Research {topic} and collect the most relevant facts.",
|
||||
"expected_output": "Structured research notes about {topic}.",
|
||||
"agent": "researcher"
|
||||
},
|
||||
{
|
||||
"name": "analysis",
|
||||
"description": "Analyze the research and write a concise report.",
|
||||
"expected_output": "A markdown report with findings and recommendations.",
|
||||
"agent": "analyst",
|
||||
"context": ["research"],
|
||||
"output_file": "output/report.md"
|
||||
}
|
||||
],
|
||||
"process": "sequential",
|
||||
"verbose": true,
|
||||
"memory": true,
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`agents`의 각 문자열은 먼저 `agents/<name>.jsonc`, 그 다음 `agents/<name>.json`으로 해석됩니다. 계층형 crew는 `"process": "hierarchical"`와 `manager_llm` 또는 `manager_agent`를 사용하세요.
|
||||
|
||||
<Warning>
|
||||
신뢰하는 출처의 JSON crew 프로젝트만 실행하세요. `custom:<name>` 도구와 `{"python": "module.attribute"}` 참조는 crew 로드 시 로컬 Python 코드를 실행합니다.
|
||||
</Warning>
|
||||
|
||||
### 클래식 YAML 구성
|
||||
|
||||
`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, `@CrewBase`, `@agent`, `@task`, `@crew` 데코레이터를 사용합니다.
|
||||
|
||||
이 방식은 기존 Python/YAML 프로젝트와 Python 데코레이터 제어가 필요한 팀을 위해 계속 지원됩니다.
|
||||
|
||||
클래식 프로젝트를 만든 후, `CrewBase`를 상속받는 클래스에서 데코레이터를 이용해 agent, task, 그리고 crew 자체를 정의할 수 있습니다.
|
||||
|
||||
#### 데코레이터가 적용된 예시 Crew 클래스
|
||||
|
||||
```python code
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class YourCrewName:
|
||||
"""Description of your crew"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
# YAML 구성 파일 경로
|
||||
# YAML로 정의된 에이전트와 태스크의 예시는 아래 링크를 참고하세요:
|
||||
# - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
|
||||
# - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
|
||||
agents_config = 'config/agents.yaml'
|
||||
tasks_config = 'config/tasks.yaml'
|
||||
|
||||
@before_kickoff
|
||||
def prepare_inputs(self, inputs):
|
||||
# crew 시작 전에 입력값을 수정합니다
|
||||
inputs['additional_data'] = "Some extra information"
|
||||
return inputs
|
||||
|
||||
@after_kickoff
|
||||
def process_output(self, output):
|
||||
# crew가 종료된 후 출력값을 수정합니다
|
||||
output.raw += "\nProcessed after kickoff."
|
||||
return output
|
||||
|
||||
@agent
|
||||
def agent_one(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['agent_one'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@agent
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['agent_two'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['task_one'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@task
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['task_two'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents, # @agent 데코레이터로 자동 수집
|
||||
tasks=self.tasks, # @task 데코레이터로 자동 수집
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
위 코드를 실행하는 방법:
|
||||
|
||||
```python code
|
||||
YourCrewName().crew().kickoff(inputs={"any": "input here"})
|
||||
```
|
||||
|
||||
<Note>
|
||||
태스크들은 정의된 순서대로 실행됩니다.
|
||||
</Note>
|
||||
|
||||
`CrewBase` 클래스와 이 데코레이터들은 에이전트와 태스크의 수집을 자동화하여
|
||||
수동으로 관리할 필요를 줄여줍니다.
|
||||
|
||||
#### `annotations.py`의 데코레이터 개요
|
||||
|
||||
CrewAI는 `annotations.py` 파일에서 크루 클래스 내의 메서드를 특별히 처리하기 위해 사용하는 여러 데코레이터를 제공합니다:
|
||||
|
||||
- `@CrewBase`: 클래스를 크루 기본 클래스로 표시합니다.
|
||||
- `@agent`: `Agent` 객체를 반환하는 메서드임을 나타냅니다.
|
||||
- `@task`: `Task` 객체를 반환하는 메서드임을 나타냅니다.
|
||||
- `@crew`: `Crew` 객체를 반환하는 메서드임을 나타냅니다.
|
||||
- `@before_kickoff`: (옵션) 크루가 시작되기 전에 실행될 메서드를 표시합니다.
|
||||
- `@after_kickoff`: (옵션) 크루가 종료된 후에 실행될 메서드를 표시합니다.
|
||||
|
||||
이러한 데코레이터들은 크루의 구조를 구성하는 데 도움이 되며, 에이전트와 태스크를 수동으로 나열하지 않아도 자동으로 수집할 수 있도록 해줍니다.
|
||||
|
||||
### 직접 코드 정의 (대안)
|
||||
|
||||
또는 YAML 구성 파일을 사용하지 않고 코드에서 직접 crew를 정의할 수 있습니다.
|
||||
|
||||
```python code
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai_tools import YourCustomTool
|
||||
|
||||
class YourCrewName:
|
||||
def agent_one(self) -> Agent:
|
||||
return Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data trends in the market",
|
||||
backstory="An experienced data analyst with a background in economics",
|
||||
verbose=True,
|
||||
tools=[YourCustomTool()]
|
||||
)
|
||||
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
role="Market Researcher",
|
||||
goal="Gather information on market dynamics",
|
||||
backstory="A diligent researcher with a keen eye for detail",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
description="Collect recent market data and identify trends.",
|
||||
expected_output="A report summarizing key trends in the market.",
|
||||
agent=self.agent_one()
|
||||
)
|
||||
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
description="Research factors affecting market dynamics.",
|
||||
expected_output="An analysis of factors influencing the market.",
|
||||
agent=self.agent_two()
|
||||
)
|
||||
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=[self.agent_one(), self.agent_two()],
|
||||
tasks=[self.task_one(), self.task_two()],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
위 코드를 실행하는 방법:
|
||||
|
||||
```python code
|
||||
YourCrewName().crew().kickoff(inputs={})
|
||||
```
|
||||
|
||||
이 예시에서:
|
||||
|
||||
- 에이전트와 태스크는 데코레이터 없이 클래스 내에서 직접 정의됩니다.
|
||||
- 에이전트와 태스크 목록을 수동으로 생성하고 관리합니다.
|
||||
- 이 방식은 더 많은 제어를 제공하지만, 대규모 프로젝트의 경우 유지보수가 어려울 수 있습니다.
|
||||
|
||||
## Crew Output
|
||||
|
||||
CrewAI 프레임워크에서 crew의 출력은 `CrewOutput` 클래스 내에 캡슐화되어 있습니다.
|
||||
이 클래스는 crew 실행 결과를 구조화된 방식으로 접근할 수 있도록 하며, 원시 문자열, JSON, Pydantic 모델과 같은 다양한 형식을 포함합니다.
|
||||
`CrewOutput`에는 최종 task 출력 결과, 토큰 사용량, 그리고 개별 task 출력 결과가 포함됩니다.
|
||||
|
||||
### Crew 출력 속성
|
||||
|
||||
| 속성 | 매개변수 | 타입 | 설명 |
|
||||
| :--------------- | :--------------- | :--------------------------- | :----------------------------------------------------------------------------------------- |
|
||||
| **Raw** | `raw` | `str` | crew의 원시 출력값입니다. 출력의 기본 형식입니다. |
|
||||
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | crew의 구조화된 출력을 나타내는 Pydantic 모델 객체입니다. |
|
||||
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | crew의 JSON 출력을 나타내는 딕셔너리입니다. |
|
||||
| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | crew 내 각 작업의 출력을 나타내는 `TaskOutput` 객체의 리스트입니다. |
|
||||
| **Token Usage** | `token_usage` | `Dict[str, Any]` | 실행 중 언어 모델의 성능에 대한 통찰을 제공하는 토큰 사용 요약 정보입니다. |
|
||||
|
||||
### Crew 출력 메서드 및 속성
|
||||
|
||||
| 메서드/속성 | 설명 |
|
||||
| :-------------- | :------------------------------------------------------------------------------------------------ |
|
||||
| **json** | 출력 형식이 JSON인 경우 crew 출력의 JSON 문자열 표현을 반환합니다. |
|
||||
| **to_dict** | JSON 및 Pydantic 출력을 사전으로 변환합니다. |
|
||||
| \***\*str\*\*** | crew 출력의 문자열 표현을 반환합니다. 우선순위는 Pydantic, 그 다음 JSON, 마지막으로 raw입니다. |
|
||||
|
||||
### Crew 출력 접근하기
|
||||
|
||||
crew가 실행된 후에는 `Crew` 객체의 `output` 속성을 통해 출력값에 접근할 수 있습니다. `CrewOutput` 클래스는 이 출력값을 다루고 표시하는 다양한 방법을 제공합니다.
|
||||
|
||||
#### 예시
|
||||
|
||||
```python Code
|
||||
# Example crew execution
|
||||
crew = Crew(
|
||||
agents=[research_agent, writer_agent],
|
||||
tasks=[research_task, write_article_task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
crew_output = crew.kickoff()
|
||||
|
||||
# Accessing the crew output
|
||||
print(f"Raw Output: {crew_output.raw}")
|
||||
if crew_output.json_dict:
|
||||
print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}")
|
||||
if crew_output.pydantic:
|
||||
print(f"Pydantic Output: {crew_output.pydantic}")
|
||||
print(f"Tasks Output: {crew_output.tasks_output}")
|
||||
print(f"Token Usage: {crew_output.token_usage}")
|
||||
```
|
||||
|
||||
## 크루 로그 접근하기
|
||||
|
||||
`output_log_file`을 `True(Boolean)` 또는 `file_name(str)`로 설정하면 크루 실행의 실시간 로그를 볼 수 있습니다. 이벤트 로그는 `file_name.txt`와 `file_name.json` 두 가지 형식 모두를 지원합니다.
|
||||
`True(Boolean)`로 설정할 경우에는 `logs.txt`로 저장됩니다.
|
||||
|
||||
`output_log_file`이 `False(Boolean)` 또는 `None`으로 설정된 경우에는 로그가 저장되지 않습니다.
|
||||
|
||||
```python Code
|
||||
# 크루 로그 저장하기
|
||||
crew = Crew(output_log_file = True) # 로그는 logs.txt로 저장됩니다
|
||||
crew = Crew(output_log_file = file_name) # 로그는 file_name.txt로 저장됩니다
|
||||
crew = Crew(output_log_file = file_name.txt) # 로그는 file_name.txt로 저장됩니다
|
||||
crew = Crew(output_log_file = file_name.json) # 로그는 file_name.json으로 저장됩니다
|
||||
```
|
||||
|
||||
## 메모리 활용
|
||||
|
||||
crew는 메모리(단기, 장기 및 엔티티 메모리)를 활용하여 시간이 지남에 따라 실행 및 학습을 향상시킬 수 있습니다. 이 기능을 통해 crew는 실행 메모리를 저장하고 회상할 수 있어, 의사결정 및 작업 실행 전략에 도움이 됩니다.
|
||||
|
||||
## 캐시 활용
|
||||
|
||||
캐시는 도구 실행 결과를 저장하는 데 사용될 수 있으며, 동일한 작업을 반복 실행할 필요를 줄여 프로세스의 효율성을 높입니다.
|
||||
|
||||
## Crew 사용 메트릭
|
||||
|
||||
crew 실행 후, `usage_metrics` 속성에 접근하여 crew가 실행한 모든 작업에 대한 언어 모델(LLM) 사용 메트릭을 확인할 수 있습니다. 이를 통해 운영 효율성과 개선이 필요한 영역에 대한 인사이트를 얻을 수 있습니다.
|
||||
|
||||
```python Code
|
||||
# Access the crew's usage metrics
|
||||
crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
|
||||
crew.kickoff()
|
||||
print(crew.usage_metrics)
|
||||
```
|
||||
|
||||
## Crew 실행 프로세스
|
||||
|
||||
- **순차적 프로세스**: 작업이 하나씩 차례로 실행되어 linear flow의 작업 흐름을 제공합니다.
|
||||
- **계층적 프로세스**: 매니저 agent가 crew를 조정하여 작업을 위임하고 결과를 검증한 후 다음 단계로 이동합니다. **참고**: 이 프로세스에는 `manager_llm` 또는 `manager_agent`가 필요하며, 프로세스 flow 검증을 위해 필수적입니다.
|
||||
|
||||
### 크루 시작하기
|
||||
|
||||
크루가 구성되면, `kickoff()` 메서드를 사용하여 워크플로를 시작하세요. 이렇게 하면 정의된 프로세스 플로우에 따라 실행 과정이 시작됩니다.
|
||||
|
||||
```python Code
|
||||
# Start the crew's task execution
|
||||
result = my_crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
### Crew를 시작하는 다양한 방법
|
||||
|
||||
crew가 구성되면, 적절한 시작 방법으로 workflow를 시작하세요. CrewAI는 kickoff 프로세스를 더 잘 제어할 수 있도록 여러 방법을 제공합니다.
|
||||
|
||||
#### 동기 메서드
|
||||
|
||||
- `kickoff()`: 정의된 process flow에 따라 실행 프로세스를 시작합니다.
|
||||
- `kickoff_for_each()`: 입력 이벤트나 컬렉션 내 각 항목에 대해 순차적으로 task를 실행합니다.
|
||||
|
||||
#### 비동기 메서드
|
||||
|
||||
CrewAI는 비동기 실행을 위해 두 가지 접근 방식을 제공합니다:
|
||||
|
||||
| 메서드 | 타입 | 설명 |
|
||||
|--------|------|-------------|
|
||||
| `akickoff()` | 네이티브 async | 전체 실행 체인에서 진정한 async/await 사용 |
|
||||
| `akickoff_for_each()` | 네이티브 async | 리스트의 각 입력에 대해 네이티브 async 실행 |
|
||||
| `kickoff_async()` | 스레드 기반 | 동기 실행을 `asyncio.to_thread`로 래핑 |
|
||||
| `kickoff_for_each_async()` | 스레드 기반 | 리스트의 각 입력에 대해 스레드 기반 async |
|
||||
|
||||
<Note>
|
||||
고동시성 워크로드의 경우 `akickoff()` 및 `akickoff_for_each()`가 권장됩니다. 이들은 작업 실행, 메모리 작업, 지식 검색에 네이티브 async를 사용합니다.
|
||||
</Note>
|
||||
|
||||
```python Code
|
||||
# Start the crew's task execution
|
||||
result = my_crew.kickoff()
|
||||
print(result)
|
||||
|
||||
# Example of using kickoff_for_each
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
results = my_crew.kickoff_for_each(inputs=inputs_array)
|
||||
for result in results:
|
||||
print(result)
|
||||
|
||||
# Example of using native async with akickoff
|
||||
inputs = {'topic': 'AI in healthcare'}
|
||||
async_result = await my_crew.akickoff(inputs=inputs)
|
||||
print(async_result)
|
||||
|
||||
# Example of using native async with akickoff_for_each
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
async_results = await my_crew.akickoff_for_each(inputs=inputs_array)
|
||||
for async_result in async_results:
|
||||
print(async_result)
|
||||
|
||||
# Example of using thread-based kickoff_async
|
||||
inputs = {'topic': 'AI in healthcare'}
|
||||
async_result = await my_crew.kickoff_async(inputs=inputs)
|
||||
print(async_result)
|
||||
|
||||
# Example of using thread-based kickoff_for_each_async
|
||||
inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}]
|
||||
async_results = await my_crew.kickoff_for_each_async(inputs=inputs_array)
|
||||
for async_result in async_results:
|
||||
print(async_result)
|
||||
```
|
||||
|
||||
이러한 메서드는 crew 내에서 task를 관리하고 실행하는 데 유연성을 제공하며, 동기 및 비동기 workflow 모두 필요에 맞게 사용할 수 있도록 지원합니다. 자세한 비동기 예제는 [Crew 비동기 시작](/ko/learn/kickoff-async) 가이드를 참조하세요.
|
||||
|
||||
### 스트리밍 Crew 실행
|
||||
|
||||
crew 실행을 실시간으로 확인하려면 스트리밍을 활성화하여 출력이 생성되는 대로 받을 수 있습니다:
|
||||
|
||||
```python Code
|
||||
# 스트리밍 활성화
|
||||
crew = Crew(
|
||||
agents=[researcher],
|
||||
tasks=[task],
|
||||
stream=True
|
||||
)
|
||||
|
||||
# 스트리밍 출력을 반복
|
||||
streaming = crew.kickoff(inputs={"topic": "AI"})
|
||||
for chunk in streaming:
|
||||
print(chunk.content, end="", flush=True)
|
||||
|
||||
# 최종 결과 접근
|
||||
result = streaming.result
|
||||
```
|
||||
|
||||
스트리밍에 대한 자세한 내용은 [스트리밍 Crew 실행](/ko/learn/streaming-crew-execution) 가이드를 참조하세요.
|
||||
|
||||
### 특정 Task에서 다시 실행하기
|
||||
|
||||
이제 CLI 명령어 `replay`를 사용하여 특정 task에서 다시 실행할 수 있습니다.
|
||||
|
||||
CrewAI의 replay 기능을 사용하면 커맨드라인 인터페이스(CLI)를 통해 특정 task에서 다시 실행할 수 있습니다. `crewai replay -t <task_id>` 명령어를 실행하면 replay 과정에서 사용할 `task_id`를 지정할 수 있습니다.
|
||||
|
||||
Kickoff은 이제 최신 kickoff에서 반환된 task output을 로컬에 저장하므로, 해당 지점부터 다시 실행할 수 있습니다.
|
||||
|
||||
### CLI를 사용하여 특정 작업에서 다시 실행하기
|
||||
|
||||
replay 기능을 사용하려면 다음 단계를 따라주세요:
|
||||
|
||||
1. 터미널 또는 명령 프롬프트를 엽니다.
|
||||
2. CrewAI 프로젝트가 위치한 디렉터리로 이동합니다.
|
||||
3. 아래 명령어를 실행합니다:
|
||||
|
||||
최신 kickoff 작업 ID를 확인하려면 다음을 사용하세요:
|
||||
|
||||
```shell
|
||||
crewai log-tasks-outputs
|
||||
```
|
||||
|
||||
그런 다음, 특정 작업에서 다시 실행하려면 다음을 사용하세요:
|
||||
|
||||
```shell
|
||||
crewai replay -t <task_id>
|
||||
```
|
||||
|
||||
이 명령어들을 사용하면 이전에 실행된 작업의 컨텍스트를 유지하면서 최신 kickoff 작업부터 다시 실행할 수 있습니다.
|
||||
414
docs/edge/ko/concepts/event-listener.mdx
Normal file
414
docs/edge/ko/concepts/event-listener.mdx
Normal file
@@ -0,0 +1,414 @@
|
||||
---
|
||||
title: '이벤트 리스너'
|
||||
description: 'CrewAI 이벤트에 연결하여 맞춤형 통합 및 모니터링 구축'
|
||||
icon: spinner
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI는 강력한 이벤트 시스템을 제공하여 crew 실행 중 발생하는 다양한 이벤트를 수신하고 이에 반응할 수 있도록 합니다. 이 기능을 통해 맞춤형 통합, 모니터링 솔루션, 로깅 시스템 또는 CrewAI의 내부 이벤트에 따라 트리거되어야 하는 기타 모든 기능을 구축할 수 있습니다.
|
||||
|
||||
## 작동 방식
|
||||
|
||||
CrewAI는 실행 수명 주기 전반에 걸쳐 이벤트를 발생시키는 이벤트 버스 아키텍처를 사용합니다. 이벤트 시스템은 다음과 같은 구성 요소로 구축되어 있습니다:
|
||||
|
||||
1. **CrewAIEventsBus**: 이벤트 등록 및 발생을 관리하는 싱글톤 이벤트 버스
|
||||
2. **BaseEvent**: 시스템 내 모든 이벤트의 기본 클래스
|
||||
3. **BaseEventListener**: 커스텀 이벤트 리스너 생성을 위한 추상 기본 클래스
|
||||
|
||||
CrewAI에서 특정 동작(예: Crew가 실행을 시작하거나 Agent가 task를 완료하거나 tool이 사용될 때)이 발생하면, 시스템은 해당 이벤트를 발생시킵니다. 이러한 이벤트에 대한 핸들러를 등록하여 해당 이벤트가 발생할 때 커스텀 코드를 실행할 수 있습니다.
|
||||
|
||||
<Note type="info" title="Enterprise Enhancement: Prompt Tracing">
|
||||
CrewAI AOP는 event 시스템을 활용하여 모든 prompt, completion 및 관련 메타데이터를 추적, 저장 및 시각화하는 내장 Prompt Tracing 기능을 제공합니다. 이 기능을 통해 agent 운영에 대한 강력한 디버깅 기능과 투명성을 얻을 수 있습니다.
|
||||
|
||||
|
||||
|
||||
Prompt Tracing을 통해 다음과 같은 작업이 가능합니다:
|
||||
- LLM에 전송된 모든 prompt의 전체 기록 보기
|
||||
- token 사용량 및 비용 추적
|
||||
- agent reasoning 실패 디버깅
|
||||
- 팀 내에서 prompt 시퀀스 공유
|
||||
- 다양한 prompt 전략 비교
|
||||
- 컴플라이언스 및 감사를 위한 trace 내보내기
|
||||
</Note>
|
||||
|
||||
## 커스텀 이벤트 리스너 생성하기
|
||||
|
||||
커스텀 이벤트 리스너를 생성하려면 다음 단계를 따라야 합니다:
|
||||
|
||||
1. `BaseEventListener`를 상속하는 클래스를 생성합니다.
|
||||
2. `setup_listeners` 메서드를 구현합니다.
|
||||
3. 원하는 이벤트에 대한 핸들러를 등록합니다.
|
||||
4. 해당 파일에서 리스너의 인스턴스를 생성합니다.
|
||||
|
||||
아래는 커스텀 이벤트 리스너 클래스의 간단한 예시입니다:
|
||||
|
||||
```python
|
||||
from crewai.events import (
|
||||
CrewKickoffStartedEvent,
|
||||
CrewKickoffCompletedEvent,
|
||||
AgentExecutionCompletedEvent,
|
||||
)
|
||||
from crewai.events import BaseEventListener
|
||||
|
||||
class MyCustomListener(BaseEventListener):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def on_crew_started(source, event):
|
||||
print(f"Crew '{event.crew_name}' has started execution!")
|
||||
|
||||
@crewai_event_bus.on(CrewKickoffCompletedEvent)
|
||||
def on_crew_completed(source, event):
|
||||
print(f"Crew '{event.crew_name}' has completed execution!")
|
||||
print(f"Output: {event.output}")
|
||||
|
||||
@crewai_event_bus.on(AgentExecutionCompletedEvent)
|
||||
def on_agent_execution_completed(source, event):
|
||||
print(f"Agent '{event.agent.role}' completed task")
|
||||
print(f"Output: {event.output}")
|
||||
```
|
||||
|
||||
## 리스너를 올바르게 등록하기
|
||||
|
||||
리스너 클래스를 정의하는 것만으로는 충분하지 않습니다. 해당 클래스의 인스턴스를 생성하고 애플리케이션에 임포트되었는지 확인해야 합니다. 이렇게 하면 다음과 같은 효과가 있습니다:
|
||||
|
||||
1. 이벤트 핸들러가 이벤트 버스에 등록됩니다.
|
||||
2. 리스너 인스턴스가 메모리에 유지됩니다(가비지 컬렉션되지 않음).
|
||||
3. 이벤트가 발생할 때 리스너가 활성화됩니다.
|
||||
|
||||
### 옵션 1: Crew 또는 Flow 구현에서 가져오기 및 인스턴스화
|
||||
|
||||
가장 중요한 것은 Crew 또는 Flow가 정의되고 실행되는 파일에서 리스너의 인스턴스를 생성하는 것입니다.
|
||||
|
||||
#### 크루 기반 애플리케이션의 경우
|
||||
|
||||
크루 구현 파일 상단에 리스너를 생성하고 임포트하세요:
|
||||
|
||||
```python
|
||||
# In your crew.py file
|
||||
from crewai import Agent, Crew, Task
|
||||
from my_listeners import MyCustomListener
|
||||
|
||||
# Create an instance of your listener
|
||||
my_listener = MyCustomListener()
|
||||
|
||||
class MyCustomCrew:
|
||||
# Your crew implementation...
|
||||
|
||||
def crew(self):
|
||||
return Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
# ...
|
||||
)
|
||||
```
|
||||
|
||||
#### 플로우 기반 애플리케이션의 경우
|
||||
|
||||
플로우 구현 파일 상단에 리스너를 생성하고 임포트하세요:
|
||||
|
||||
```python
|
||||
# main.py 또는 flow.py 파일에서
|
||||
from crewai.flow import Flow, listen, start
|
||||
from my_listeners import MyCustomListener
|
||||
|
||||
# 리스너 인스턴스 생성
|
||||
my_listener = MyCustomListener()
|
||||
|
||||
class MyCustomFlow(Flow):
|
||||
# 플로우 구현...
|
||||
|
||||
@start()
|
||||
def first_step(self):
|
||||
# ...
|
||||
```
|
||||
|
||||
이렇게 하면 크루 또는 플로우가 실행될 때 리스너가 로드되고 활성화됩니다.
|
||||
|
||||
### 옵션 2: 리스너를 위한 패키지 생성
|
||||
|
||||
여러 개의 리스너가 있는 경우 등 보다 구조적인 접근 방식을 원한다면 다음과 같이 진행하세요:
|
||||
|
||||
1. 리스너를 위한 패키지를 생성합니다:
|
||||
|
||||
```
|
||||
my_project/
|
||||
├── listeners/
|
||||
│ ├── __init__.py
|
||||
│ ├── my_custom_listener.py
|
||||
│ └── another_listener.py
|
||||
```
|
||||
|
||||
2. `my_custom_listener.py`에서 리스너 클래스를 정의하고 인스턴스를 생성합니다:
|
||||
|
||||
```python
|
||||
# my_custom_listener.py
|
||||
from crewai.events import BaseEventListener
|
||||
# ... import events ...
|
||||
|
||||
class MyCustomListener(BaseEventListener):
|
||||
# ... implementation ...
|
||||
|
||||
# 리스너 인스턴스 생성
|
||||
my_custom_listener = MyCustomListener()
|
||||
```
|
||||
|
||||
3. `__init__.py`에서 리스너 인스턴스를 임포트하여 로드되도록 합니다:
|
||||
|
||||
```python
|
||||
# __init__.py
|
||||
from .my_custom_listener import my_custom_listener
|
||||
from .another_listener import another_listener
|
||||
|
||||
# 다른 곳에서 접근이 필요하다면 익스포트할 수도 있습니다
|
||||
__all__ = ['my_custom_listener', 'another_listener']
|
||||
```
|
||||
|
||||
4. Crew나 Flow 파일에서 리스너 패키지를 임포트합니다:
|
||||
|
||||
```python
|
||||
# crew.py 또는 flow.py 파일 내에서
|
||||
import my_project.listeners # 모든 리스너가 로드됩니다
|
||||
|
||||
class MyCustomCrew:
|
||||
# Your crew implementation...
|
||||
```
|
||||
|
||||
이것이 CrewAI 코드베이스에서 서드파티 이벤트 리스너가 등록되는 방식입니다.
|
||||
|
||||
## 사용 가능한 이벤트 유형
|
||||
|
||||
CrewAI는 여러분이 청취할 수 있는 다양한 이벤트를 제공합니다:
|
||||
|
||||
### Crew 이벤트
|
||||
|
||||
- **CrewKickoffStartedEvent**: Crew가 실행을 시작할 때 발생
|
||||
- **CrewKickoffCompletedEvent**: Crew가 실행을 완료할 때 발생
|
||||
- **CrewKickoffFailedEvent**: Crew가 실행을 완료하지 못할 때 발생
|
||||
- **CrewTestStartedEvent**: Crew가 테스트를 시작할 때 발생
|
||||
- **CrewTestCompletedEvent**: Crew가 테스트를 완료할 때 발생
|
||||
- **CrewTestFailedEvent**: Crew가 테스트를 완료하지 못할 때 발생
|
||||
- **CrewTrainStartedEvent**: Crew가 훈련을 시작할 때 발생
|
||||
- **CrewTrainCompletedEvent**: Crew가 훈련을 완료할 때 발생
|
||||
- **CrewTrainFailedEvent**: Crew가 훈련을 완료하지 못할 때 발생
|
||||
- **CrewTestResultEvent**: Crew 테스트 결과가 사용 가능할 때 발생합니다. 품질 점수, 실행 시간, 사용된 모델을 포함합니다.
|
||||
|
||||
### 에이전트 이벤트
|
||||
|
||||
- **AgentExecutionStartedEvent**: 에이전트가 작업 실행을 시작할 때 발생함
|
||||
- **AgentExecutionCompletedEvent**: 에이전트가 작업 실행을 완료할 때 발생함
|
||||
- **AgentExecutionErrorEvent**: 에이전트가 실행 도중 오류를 만날 때 발생함
|
||||
- **LiteAgentExecutionStartedEvent**: LiteAgent가 실행을 시작할 때 발생합니다. 에이전트 정보, 도구, 메시지를 포함합니다.
|
||||
- **LiteAgentExecutionCompletedEvent**: LiteAgent가 실행을 완료할 때 발생합니다. 에이전트 정보와 출력을 포함합니다.
|
||||
- **LiteAgentExecutionErrorEvent**: LiteAgent가 실행 중 오류를 만날 때 발생합니다. 에이전트 정보와 오류 메시지를 포함합니다.
|
||||
- **AgentEvaluationStartedEvent**: 에이전트 평가가 시작될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수를 포함합니다.
|
||||
- **AgentEvaluationCompletedEvent**: 에이전트 평가가 완료될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 메트릭 카테고리, 점수를 포함합니다.
|
||||
- **AgentEvaluationFailedEvent**: 에이전트 평가가 실패할 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 오류 메시지를 포함합니다.
|
||||
|
||||
### 작업 이벤트
|
||||
|
||||
- **TaskStartedEvent**: 작업이 실행을 시작할 때 발생
|
||||
- **TaskCompletedEvent**: 작업이 실행을 완료할 때 발생
|
||||
- **TaskFailedEvent**: 작업이 실행을 완료하지 못할 때 발생
|
||||
- **TaskEvaluationEvent**: 작업이 평가될 때 발생
|
||||
|
||||
### 도구 사용 이벤트
|
||||
|
||||
- **ToolUsageStartedEvent**: 도구 실행이 시작될 때 발생함
|
||||
- **ToolUsageFinishedEvent**: 도구 실행이 완료될 때 발생함
|
||||
- **ToolUsageErrorEvent**: 도구 실행 중 오류가 발생할 때 발생함
|
||||
- **ToolValidateInputErrorEvent**: 도구 입력 검증 중 오류가 발생할 때 발생함
|
||||
- **ToolExecutionErrorEvent**: 도구 실행 중 오류가 발생할 때 발생함
|
||||
- **ToolSelectionErrorEvent**: 도구 선택 시 오류가 발생할 때 발생함
|
||||
|
||||
### MCP 이벤트
|
||||
|
||||
- **MCPConnectionStartedEvent**: MCP 서버 연결을 시작할 때 발생합니다. 서버 이름, URL, 전송 유형, 연결 시간 초과, 재연결 시도 여부를 포함합니다.
|
||||
- **MCPConnectionCompletedEvent**: MCP 서버에 성공적으로 연결될 때 발생합니다. 서버 이름, 연결 시간(밀리초), 재연결 여부를 포함합니다.
|
||||
- **MCPConnectionFailedEvent**: MCP 서버 연결이 실패할 때 발생합니다. 서버 이름, 오류 메시지, 오류 유형(`timeout`, `authentication`, `network` 등)을 포함합니다.
|
||||
- **MCPToolExecutionStartedEvent**: MCP 도구 실행을 시작할 때 발생합니다. 서버 이름, 도구 이름, 도구 인수를 포함합니다.
|
||||
- **MCPToolExecutionCompletedEvent**: MCP 도구 실행이 성공적으로 완료될 때 발생합니다. 서버 이름, 도구 이름, 결과, 실행 시간(밀리초)을 포함합니다.
|
||||
- **MCPToolExecutionFailedEvent**: MCP 도구 실행이 실패할 때 발생합니다. 서버 이름, 도구 이름, 오류 메시지, 오류 유형(`timeout`, `validation`, `server_error` 등)을 포함합니다.
|
||||
- **MCPConfigFetchFailedEvent**: MCP 서버 구성을 가져오는 데 실패할 때 발생합니다(예: 계정에서 MCP가 연결되지 않았거나, API 오류, 구성을 가져온 후 연결 실패). slug, 오류 메시지, 오류 유형(`not_connected`, `api_error`, `connection_failed`)을 포함합니다.
|
||||
|
||||
### 지식 이벤트
|
||||
|
||||
- **KnowledgeRetrievalStartedEvent**: 지식 검색이 시작될 때 발생
|
||||
- **KnowledgeRetrievalCompletedEvent**: 지식 검색이 완료될 때 발생
|
||||
- **KnowledgeQueryStartedEvent**: 지식 쿼리가 시작될 때 발생
|
||||
- **KnowledgeQueryCompletedEvent**: 지식 쿼리가 완료될 때 발생
|
||||
- **KnowledgeQueryFailedEvent**: 지식 쿼리가 실패할 때 발생
|
||||
- **KnowledgeSearchQueryFailedEvent**: 지식 검색 쿼리가 실패할 때 발생
|
||||
|
||||
### LLM 가드레일 이벤트
|
||||
|
||||
- **LLMGuardrailStartedEvent**: 가드레일 검증이 시작될 때 발생합니다. 적용되는 가드레일에 대한 세부 정보와 재시도 횟수를 포함합니다.
|
||||
- **LLMGuardrailCompletedEvent**: 가드레일 검증이 완료될 때 발생합니다. 검증의 성공/실패, 결과 및 오류 메시지(있는 경우)에 대한 세부 정보를 포함합니다.
|
||||
- **LLMGuardrailFailedEvent**: 가드레일 검증이 실패할 때 발생합니다. 오류 메시지와 재시도 횟수를 포함합니다.
|
||||
|
||||
### Flow 이벤트
|
||||
|
||||
- **FlowCreatedEvent**: Flow가 생성될 때 발생
|
||||
- **FlowStartedEvent**: Flow가 실행을 시작할 때 발생
|
||||
- **FlowFinishedEvent**: Flow가 실행을 완료할 때 발생
|
||||
- **FlowPausedEvent**: 사람의 피드백을 기다리며 Flow가 일시 중지될 때 발생합니다. Flow 이름, Flow ID, 메서드 이름, 현재 상태, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.
|
||||
- **FlowPlotEvent**: Flow가 플롯될 때 발생
|
||||
- **MethodExecutionStartedEvent**: Flow 메서드가 실행을 시작할 때 발생
|
||||
- **MethodExecutionFinishedEvent**: Flow 메서드가 실행을 완료할 때 발생
|
||||
- **MethodExecutionFailedEvent**: Flow 메서드가 실행을 완료하지 못할 때 발생
|
||||
- **MethodExecutionPausedEvent**: 사람의 피드백을 기다리며 Flow 메서드가 일시 중지될 때 발생합니다. Flow 이름, 메서드 이름, 현재 상태, Flow ID, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.
|
||||
|
||||
### Human In The Loop 이벤트
|
||||
|
||||
- **FlowInputRequestedEvent**: `Flow.ask()`를 통해 Flow가 사용자 입력을 요청할 때 발생합니다. Flow 이름, 메서드 이름, 사용자에게 표시되는 질문 또는 프롬프트, 선택적 메타데이터(예: 사용자 ID, 채널, 세션 컨텍스트)를 포함합니다.
|
||||
- **FlowInputReceivedEvent**: `Flow.ask()` 이후 사용자 입력이 수신될 때 발생합니다. Flow 이름, 메서드 이름, 원래 질문, 사용자의 응답(시간 초과 시 `None`), 선택적 요청 메타데이터, 프로바이더의 선택적 응답 메타데이터(예: 응답자, 스레드 ID, 타임스탬프)를 포함합니다.
|
||||
- **HumanFeedbackRequestedEvent**: `@human_feedback` 데코레이터가 적용된 메서드가 사람 리뷰어의 입력을 필요로 할 때 발생합니다. Flow 이름, 메서드 이름, 사람에게 검토를 위해 표시되는 메서드 출력, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.
|
||||
- **HumanFeedbackReceivedEvent**: `@human_feedback` 데코레이터가 적용된 메서드에 대해 사람이 피드백을 제공할 때 발생합니다. Flow 이름, 메서드 이름, 사람이 제공한 원본 텍스트 피드백, 축약된 결과 문자열(emit이 지정된 경우)을 포함합니다.
|
||||
|
||||
### LLM 이벤트
|
||||
|
||||
- **LLMCallStartedEvent**: LLM 호출이 시작될 때 발생
|
||||
- **LLMCallCompletedEvent**: LLM 호출이 완료될 때 발생
|
||||
- **LLMCallFailedEvent**: LLM 호출이 실패할 때 발생
|
||||
- **LLMStreamChunkEvent**: 스트리밍 LLM 응답 중 각 청크를 받을 때마다 발생
|
||||
- **LLMThinkingChunkEvent**: thinking 모델에서 사고/추론 청크가 수신될 때 발생합니다. 청크 텍스트와 선택적 응답 ID를 포함합니다.
|
||||
|
||||
### 메모리 이벤트
|
||||
|
||||
- **MemoryQueryStartedEvent**: 메모리 쿼리가 시작될 때 발생합니다. 쿼리, limit, 선택적 score threshold를 포함합니다.
|
||||
- **MemoryQueryCompletedEvent**: 메모리 쿼리가 성공적으로 완료될 때 발생합니다. 쿼리, 결과, limit, score threshold, 쿼리 실행 시간을 포함합니다.
|
||||
- **MemoryQueryFailedEvent**: 메모리 쿼리 실행에 실패할 때 발생합니다. 쿼리, limit, score threshold, 오류 메시지를 포함합니다.
|
||||
- **MemorySaveStartedEvent**: 메모리 저장 작업이 시작될 때 발생합니다. 저장할 값, 메타데이터, 선택적 agent 역할을 포함합니다.
|
||||
- **MemorySaveCompletedEvent**: 메모리 저장 작업이 성공적으로 완료될 때 발생합니다. 저장된 값, 메타데이터, agent 역할, 저장 실행 시간을 포함합니다.
|
||||
- **MemorySaveFailedEvent**: 메모리 저장 작업에 실패할 때 발생합니다. 값, 메타데이터, agent 역할, 오류 메시지를 포함합니다.
|
||||
- **MemoryRetrievalStartedEvent**: 태스크 프롬프트를 위한 메모리 검색이 시작될 때 발생합니다. 선택적 태스크 ID를 포함합니다.
|
||||
- **MemoryRetrievalCompletedEvent**: 태스크 프롬프트를 위한 메모리 검색이 성공적으로 완료될 때 발생합니다. 태스크 ID, 메모리 내용, 검색 실행 시간을 포함합니다.
|
||||
- **MemoryRetrievalFailedEvent**: 태스크 프롬프트를 위한 메모리 검색이 실패할 때 발생합니다. 선택적 태스크 ID와 오류 메시지를 포함합니다.
|
||||
|
||||
### 추론 이벤트
|
||||
|
||||
- **AgentReasoningStartedEvent**: 에이전트가 태스크에 대한 추론을 시작할 때 발생합니다. 에이전트 역할, 태스크 ID, 시도 횟수를 포함합니다.
|
||||
- **AgentReasoningCompletedEvent**: 에이전트가 추론 과정을 마칠 때 발생합니다. 에이전트 역할, 태스크 ID, 생성된 계획, 에이전트가 진행할 준비가 되었는지 여부를 포함합니다.
|
||||
- **AgentReasoningFailedEvent**: 추론 과정이 실패할 때 발생합니다. 에이전트 역할, 태스크 ID, 오류 메시지를 포함합니다.
|
||||
|
||||
### 관찰 이벤트
|
||||
|
||||
- **StepObservationStartedEvent**: Planner가 단계 결과를 관찰하기 시작할 때 발생합니다. 매 단계 실행 후, 관찰 LLM 호출 전에 발생합니다. 에이전트 역할, 단계 번호, 단계 설명을 포함합니다.
|
||||
- **StepObservationCompletedEvent**: Planner가 단계 결과 관찰을 마칠 때 발생합니다. 단계 성공 여부, 학습된 핵심 정보, 남은 계획의 유효성, 전체 재계획 필요 여부, 제안된 개선 사항을 포함합니다.
|
||||
- **StepObservationFailedEvent**: 관찰 LLM 호출 자체가 실패할 때 발생합니다. 시스템은 기본적으로 계획을 계속 진행합니다. 오류 메시지를 포함합니다.
|
||||
- **PlanRefinementEvent**: Planner가 전체 재계획 없이 다음 단계 설명을 개선할 때 발생합니다. 개선된 단계 수와 적용된 개선 사항을 포함합니다.
|
||||
- **PlanReplanTriggeredEvent**: 남은 계획이 근본적으로 잘못된 것으로 판단되어 Planner가 전체 재계획을 트리거할 때 발생합니다. 재계획 이유, 재계획 횟수, 보존된 완료 단계 수를 포함합니다.
|
||||
- **GoalAchievedEarlyEvent**: Planner가 목표가 조기에 달성되었음을 감지하고 나머지 단계를 건너뛸 때 발생합니다. 남은 단계 수와 완료된 단계 수를 포함합니다.
|
||||
|
||||
### A2A (Agent-to-Agent) 이벤트
|
||||
|
||||
#### 위임 이벤트
|
||||
|
||||
- **A2ADelegationStartedEvent**: A2A 위임이 시작될 때 발생합니다. 엔드포인트 URL, 태스크 설명, 에이전트 ID, 컨텍스트 ID, 멀티턴 여부, 턴 번호, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 선택적 skill ID를 포함합니다.
|
||||
- **A2ADelegationCompletedEvent**: A2A 위임이 완료될 때 발생합니다. 완료 상태(`completed`, `input_required`, `failed` 등), 결과, 오류 메시지, 컨텍스트 ID, agent card 메타데이터를 포함합니다.
|
||||
- **A2AParallelDelegationStartedEvent**: 여러 A2A 에이전트로의 병렬 위임이 시작될 때 발생합니다. 엔드포인트 목록과 태스크 설명을 포함합니다.
|
||||
- **A2AParallelDelegationCompletedEvent**: 여러 A2A 에이전트로의 병렬 위임이 완료될 때 발생합니다. 엔드포인트 목록, 성공 수, 실패 수, 결과 요약을 포함합니다.
|
||||
|
||||
#### 대화 이벤트
|
||||
|
||||
- **A2AConversationStartedEvent**: 멀티턴 A2A 대화 시작 시 한 번 발생합니다. 첫 번째 메시지 교환 전에 발생합니다. 에이전트 ID, 엔드포인트, 컨텍스트 ID, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보를 포함합니다.
|
||||
- **A2AMessageSentEvent**: A2A 에이전트에 메시지가 전송될 때 발생합니다. 메시지 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 멀티턴 여부를 포함합니다.
|
||||
- **A2AResponseReceivedEvent**: A2A 에이전트로부터 응답이 수신될 때 발생합니다. 응답 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 상태, 최종 응답 여부를 포함합니다.
|
||||
- **A2AConversationCompletedEvent**: 멀티턴 A2A 대화 종료 시 한 번 발생합니다. 최종 상태(`completed` 또는 `failed`), 최종 결과, 오류 메시지, 컨텍스트 ID, 총 턴 수를 포함합니다.
|
||||
|
||||
#### 스트리밍 이벤트
|
||||
|
||||
- **A2AStreamingStartedEvent**: A2A 위임을 위한 스트리밍 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 엔드포인트, 턴 번호, 멀티턴 여부를 포함합니다.
|
||||
- **A2AStreamingChunkEvent**: 스트리밍 청크가 수신될 때 발생합니다. 청크 텍스트, 청크 인덱스, 최종 청크 여부, 태스크 ID, 컨텍스트 ID, 턴 번호를 포함합니다.
|
||||
|
||||
#### 폴링 및 푸시 알림 이벤트
|
||||
|
||||
- **A2APollingStartedEvent**: A2A 위임을 위한 폴링 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 폴링 간격(초), 엔드포인트를 포함합니다.
|
||||
- **A2APollingStatusEvent**: 각 폴링 반복 시 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 태스크 상태, 경과 시간, 폴링 횟수를 포함합니다.
|
||||
- **A2APushNotificationRegisteredEvent**: 푸시 알림 콜백이 등록될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 엔드포인트를 포함합니다.
|
||||
- **A2APushNotificationReceivedEvent**: 원격 A2A 에이전트로부터 푸시 알림이 수신될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 상태를 포함합니다.
|
||||
- **A2APushNotificationSentEvent**: 콜백 URL로 푸시 알림이 전송될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 상태, 전달 성공 여부, 선택적 오류 메시지를 포함합니다.
|
||||
- **A2APushNotificationTimeoutEvent**: 푸시 알림 대기가 시간 초과될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 시간 초과 시간(초)을 포함합니다.
|
||||
|
||||
#### 연결 및 인증 이벤트
|
||||
|
||||
- **A2AAgentCardFetchedEvent**: agent card가 성공적으로 가져올 때 발생합니다. 엔드포인트, 에이전트 이름, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 캐시 여부, 가져오기 시간(밀리초)을 포함합니다.
|
||||
- **A2AAuthenticationFailedEvent**: A2A 에이전트 인증이 실패할 때 발생합니다. 엔드포인트, 시도된 인증 유형(예: `bearer`, `oauth2`, `api_key`), 오류 메시지, HTTP 상태 코드를 포함합니다.
|
||||
- **A2AConnectionErrorEvent**: A2A 통신 중 연결 오류가 발생할 때 발생합니다. 엔드포인트, 오류 메시지, 오류 유형(예: `timeout`, `connection_refused`, `dns_error`), HTTP 상태 코드, 시도 중인 작업을 포함합니다.
|
||||
- **A2ATransportNegotiatedEvent**: A2A 에이전트와 전송 프로토콜이 협상될 때 발생합니다. 협상된 전송, 협상된 URL, 선택 소스(`client_preferred`, `server_preferred`, `fallback`), 클라이언트/서버 지원 전송을 포함합니다.
|
||||
- **A2AContentTypeNegotiatedEvent**: A2A 에이전트와 콘텐츠 유형이 협상될 때 발생합니다. 클라이언트/서버 입출력 모드, 협상된 입출력 모드, 협상 성공 여부를 포함합니다.
|
||||
|
||||
#### 아티팩트 이벤트
|
||||
|
||||
- **A2AArtifactReceivedEvent**: 원격 A2A 에이전트로부터 아티팩트가 수신될 때 발생합니다. 태스크 ID, 아티팩트 ID, 아티팩트 이름, 설명, MIME 유형, 크기(바이트), 콘텐츠 추가 여부를 포함합니다.
|
||||
|
||||
#### 서버 태스크 이벤트
|
||||
|
||||
- **A2AServerTaskStartedEvent**: A2A 서버 태스크 실행이 시작될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다.
|
||||
- **A2AServerTaskCompletedEvent**: A2A 서버 태스크 실행이 완료될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 결과를 포함합니다.
|
||||
- **A2AServerTaskCanceledEvent**: A2A 서버 태스크 실행이 취소될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다.
|
||||
- **A2AServerTaskFailedEvent**: A2A 서버 태스크 실행이 실패할 때 발생합니다. 태스크 ID, 컨텍스트 ID, 오류 메시지를 포함합니다.
|
||||
|
||||
#### 컨텍스트 수명 주기 이벤트
|
||||
|
||||
- **A2AContextCreatedEvent**: A2A 컨텍스트가 생성될 때 발생합니다. 컨텍스트는 대화 또는 워크플로우에서 관련 태스크를 그룹화합니다. 컨텍스트 ID와 생성 타임스탬프를 포함합니다.
|
||||
- **A2AContextExpiredEvent**: TTL로 인해 A2A 컨텍스트가 만료될 때 발생합니다. 컨텍스트 ID, 생성 타임스탬프, 수명(초), 태스크 수를 포함합니다.
|
||||
- **A2AContextIdleEvent**: A2A 컨텍스트가 유휴 상태가 될 때(설정된 임계값 동안 활동 없음) 발생합니다. 컨텍스트 ID, 유휴 시간(초), 태스크 수를 포함합니다.
|
||||
- **A2AContextCompletedEvent**: A2A 컨텍스트의 모든 태스크가 완료될 때 발생합니다. 컨텍스트 ID, 총 태스크 수, 지속 시간(초)을 포함합니다.
|
||||
- **A2AContextPrunedEvent**: A2A 컨텍스트가 정리(삭제)될 때 발생합니다. 컨텍스트 ID, 태스크 수, 수명(초)을 포함합니다.
|
||||
|
||||
## 이벤트 핸들러 구조
|
||||
|
||||
각 이벤트 핸들러는 두 개의 매개변수를 받습니다:
|
||||
|
||||
1. **source**: 이벤트를 발생시킨 객체
|
||||
2. **event**: 이벤트별 데이터를 포함하는 이벤트 인스턴스
|
||||
|
||||
이벤트 객체의 구조는 이벤트 타입에 따라 다르지만, 모든 이벤트는 `BaseEvent`를 상속하며 다음을 포함합니다:
|
||||
|
||||
- **timestamp**: 이벤트가 발생한 시간
|
||||
- **type**: 이벤트 타입을 나타내는 문자열 식별자
|
||||
|
||||
추가 필드는 이벤트 타입에 따라 다릅니다. 예를 들어, `CrewKickoffCompletedEvent`에는 `crew_name`과 `output` 필드가 포함됩니다.
|
||||
|
||||
|
||||
## 고급 사용법: Scoped Handlers
|
||||
|
||||
임시 이벤트 처리가 필요한 경우(테스트 또는 특정 작업에 유용함), `scoped_handlers` 컨텍스트 관리자를 사용할 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai.events import crewai_event_bus, CrewKickoffStartedEvent
|
||||
|
||||
with crewai_event_bus.scoped_handlers():
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def temp_handler(source, event):
|
||||
print("This handler only exists within this context")
|
||||
|
||||
# Do something that emits events
|
||||
|
||||
# 컨텍스트 밖에서는 임시 핸들러가 제거됩니다
|
||||
```
|
||||
|
||||
## 사용 사례
|
||||
|
||||
이벤트 리스너는 다양한 목적으로 사용할 수 있습니다:
|
||||
|
||||
1. **로깅 및 모니터링**: Crew의 실행을 추적하고 중요한 이벤트를 기록합니다
|
||||
2. **분석**: Crew의 성능과 동작에 대한 데이터를 수집합니다
|
||||
3. **디버깅**: 특정 문제를 디버깅하기 위해 임시 리스너를 설정합니다
|
||||
4. **통합**: CrewAI를 모니터링 플랫폼, 데이터베이스 또는 알림 서비스와 같은 외부 시스템과 연결합니다
|
||||
5. **사용자 정의 동작**: 특정 이벤트에 따라 사용자 정의 동작을 트리거합니다
|
||||
|
||||
## 모범 사례
|
||||
|
||||
1. **핸들러를 가볍게 유지하세요**: 이벤트 핸들러는 경량이어야 하며, 블로킹 작업을 피해야 합니다.
|
||||
2. **오류 처리**: 예외가 메인 실행에 영향을 주지 않도록 이벤트 핸들러에 적절한 오류 처리를 포함하세요.
|
||||
3. **정리**: 리스너가 자원을 할당한다면, 이를 적절하게 정리하는지 확인하세요.
|
||||
4. **선택적 리스닝**: 실제로 처리해야 하는 이벤트에만 리스닝하세요.
|
||||
5. **테스트**: 이벤트 리스너가 예상대로 동작하는지 독립적으로 테스트하세요.
|
||||
|
||||
CrewAI의 이벤트 시스템을 활용하면 기능을 확장하고 기존 인프라와 원활하게 통합할 수 있습니다.
|
||||
267
docs/edge/ko/concepts/files.mdx
Normal file
267
docs/edge/ko/concepts/files.mdx
Normal file
@@ -0,0 +1,267 @@
|
||||
---
|
||||
title: 파일
|
||||
description: 멀티모달 처리를 위해 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 전달하세요.
|
||||
icon: file-image
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI는 네이티브 멀티모달 파일 입력을 지원하여 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 직접 전달할 수 있습니다. 파일은 각 LLM 프로바이더의 API 요구사항에 맞게 자동으로 포맷됩니다.
|
||||
|
||||
<Note type="info" title="선택적 의존성">
|
||||
파일 지원을 위해서는 선택적 `crewai-files` 패키지가 필요합니다. 다음 명령어로 설치하세요:
|
||||
|
||||
```bash
|
||||
uv add 'crewai[file-processing]'
|
||||
```
|
||||
</Note>
|
||||
|
||||
<Note type="warning" title="얼리 액세스">
|
||||
파일 처리 API는 현재 얼리 액세스 단계입니다.
|
||||
</Note>
|
||||
|
||||
## 파일 타입
|
||||
|
||||
CrewAI는 5가지 특정 파일 타입과 타입을 자동 감지하는 일반 `File` 클래스를 지원합니다:
|
||||
|
||||
| 타입 | 클래스 | 사용 사례 |
|
||||
|:-----|:------|:----------|
|
||||
| **이미지** | `ImageFile` | 사진, 스크린샷, 다이어그램, 차트 |
|
||||
| **PDF** | `PDFFile` | 문서, 보고서, 논문 |
|
||||
| **오디오** | `AudioFile` | 음성 녹음, 팟캐스트, 회의 |
|
||||
| **비디오** | `VideoFile` | 화면 녹화, 프레젠테이션 |
|
||||
| **텍스트** | `TextFile` | 코드 파일, 로그, 데이터 파일 |
|
||||
| **일반** | `File` | 콘텐츠에서 타입 자동 감지 |
|
||||
|
||||
```python
|
||||
from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile
|
||||
|
||||
image = ImageFile(source="screenshot.png")
|
||||
pdf = PDFFile(source="report.pdf")
|
||||
audio = AudioFile(source="meeting.mp3")
|
||||
video = VideoFile(source="demo.mp4")
|
||||
text = TextFile(source="data.csv")
|
||||
|
||||
file = File(source="document.pdf")
|
||||
```
|
||||
|
||||
## 파일 소스
|
||||
|
||||
`source` 파라미터는 여러 입력 타입을 받아들이고 적절한 핸들러를 자동으로 감지합니다:
|
||||
|
||||
### 경로에서
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile
|
||||
|
||||
image = ImageFile(source="./images/chart.png")
|
||||
```
|
||||
|
||||
### URL에서
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile
|
||||
|
||||
image = ImageFile(source="https://example.com/image.png")
|
||||
```
|
||||
|
||||
### 바이트에서
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile, FileBytes
|
||||
|
||||
image_bytes = download_image_from_api()
|
||||
image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
|
||||
image = ImageFile(source=image_bytes)
|
||||
```
|
||||
|
||||
## 파일 사용하기
|
||||
|
||||
파일은 여러 레벨에서 전달할 수 있으며, 더 구체적인 레벨이 우선순위를 가집니다.
|
||||
|
||||
### Crew와 함께
|
||||
|
||||
crew를 킥오프할 때 파일을 전달합니다:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
from crewai_files import ImageFile
|
||||
|
||||
crew = Crew(agents=[analyst], tasks=[analysis_task])
|
||||
|
||||
result = crew.kickoff(
|
||||
inputs={"topic": "Q4 Sales"},
|
||||
input_files={
|
||||
"chart": ImageFile(source="sales_chart.png"),
|
||||
"report": PDFFile(source="quarterly_report.pdf"),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Task와 함께
|
||||
|
||||
특정 작업에 파일을 첨부합니다:
|
||||
|
||||
```python
|
||||
from crewai import Task
|
||||
from crewai_files import ImageFile
|
||||
|
||||
task = Task(
|
||||
description="매출 차트를 분석하고 {chart}에서 트렌드를 파악하세요",
|
||||
expected_output="주요 트렌드 요약",
|
||||
input_files={
|
||||
"chart": ImageFile(source="sales_chart.png"),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Flow와 함께
|
||||
|
||||
flow에 파일을 전달하면 자동으로 crew에 상속됩니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start
|
||||
from crewai_files import ImageFile
|
||||
|
||||
class AnalysisFlow(Flow):
|
||||
@start()
|
||||
def analyze(self):
|
||||
return self.analysis_crew.kickoff()
|
||||
|
||||
flow = AnalysisFlow()
|
||||
result = flow.kickoff(
|
||||
input_files={"image": ImageFile(source="data.png")}
|
||||
)
|
||||
```
|
||||
|
||||
### 단독 에이전트와 함께
|
||||
|
||||
에이전트 킥오프에 직접 파일을 전달합니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_files import ImageFile
|
||||
|
||||
agent = Agent(
|
||||
role="Image Analyst",
|
||||
goal="Analyze images",
|
||||
backstory="Expert at visual analysis",
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
result = agent.kickoff(
|
||||
messages="What's in this image?",
|
||||
input_files={"photo": ImageFile(source="photo.jpg")},
|
||||
)
|
||||
```
|
||||
|
||||
## 파일 우선순위
|
||||
|
||||
여러 레벨에서 파일이 전달될 때, 더 구체적인 레벨이 상위 레벨을 오버라이드합니다:
|
||||
|
||||
```
|
||||
Flow input_files < Crew input_files < Task input_files
|
||||
```
|
||||
|
||||
예를 들어, Flow와 Task 모두 `"chart"`라는 이름의 파일을 정의하면, Task의 버전이 사용됩니다.
|
||||
|
||||
## 프로바이더 지원
|
||||
|
||||
각 프로바이더는 서로 다른 파일 타입을 지원합니다. CrewAI는 각 프로바이더의 API에 맞게 파일을 자동으로 포맷합니다.
|
||||
|
||||
| 프로바이더 | 이미지 | PDF | 오디오 | 비디오 | 텍스트 |
|
||||
|:---------|:-----:|:---:|:-----:|:-----:|:----:|
|
||||
| **OpenAI** (completions API) | ✓ | | | | |
|
||||
| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | |
|
||||
| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
|
||||
| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
|
||||
| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |
|
||||
|
||||
<Note type="info" title="최대 파일 지원을 위한 Gemini">
|
||||
Google Gemini 모델은 비디오를 포함한 모든 파일 타입을 지원합니다 (최대 1시간, 2GB). 비디오 콘텐츠를 처리해야 할 때 Gemini를 사용하세요.
|
||||
</Note>
|
||||
|
||||
<Note type="warning" title="지원되지 않는 파일 타입">
|
||||
프로바이더가 지원하지 않는 파일 타입을 전달하면 (예: OpenAI에 비디오) `UnsupportedFileTypeError`가 발생합니다. 처리해야 하는 파일 타입에 따라 프로바이더를 선택하세요.
|
||||
</Note>
|
||||
|
||||
## 파일 전송 방식
|
||||
|
||||
CrewAI는 각 프로바이더에 파일을 전송하는 최적의 방법을 자동으로 선택합니다:
|
||||
|
||||
| 방식 | 설명 | 사용 조건 |
|
||||
|:-------|:------------|:----------|
|
||||
| **인라인 Base64** | 파일이 요청에 직접 임베드됨 | 작은 파일 (일반적으로 < 5MB) |
|
||||
| **파일 업로드 API** | 파일이 별도로 업로드되고 ID로 참조됨 | 임계값을 초과하는 큰 파일 |
|
||||
| **URL 참조** | 직접 URL이 모델에 전달됨 | 파일 소스가 이미 URL인 경우 |
|
||||
|
||||
### 프로바이더 전송 방식
|
||||
|
||||
| 프로바이더 | 인라인 Base64 | 파일 업로드 API | URL 참조 |
|
||||
|:---------|:-------------:|:---------------:|:--------------:|
|
||||
| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
|
||||
| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
|
||||
| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
|
||||
| **AWS Bedrock** | ✓ | | ✓ (S3 URI) |
|
||||
| **Azure OpenAI** | ✓ | | ✓ |
|
||||
|
||||
<Note type="info" title="자동 최적화">
|
||||
이를 직접 관리할 필요가 없습니다. CrewAI는 파일 크기와 프로바이더 기능에 따라 가장 효율적인 방법을 자동으로 사용합니다. 파일 업로드 API가 없는 프로바이더는 모든 파일에 인라인 base64를 사용합니다.
|
||||
</Note>
|
||||
|
||||
## 파일 처리 모드
|
||||
|
||||
프로바이더 제한을 초과할 때 파일 처리 방식을 제어합니다:
|
||||
|
||||
```python
|
||||
from crewai_files import ImageFile, PDFFile
|
||||
|
||||
image = ImageFile(source="large.png", mode="strict")
|
||||
image = ImageFile(source="large.png", mode="auto")
|
||||
image = ImageFile(source="large.png", mode="warn")
|
||||
pdf = PDFFile(source="large.pdf", mode="chunk")
|
||||
```
|
||||
|
||||
## 프로바이더 제약사항
|
||||
|
||||
각 프로바이더는 파일 크기와 규격에 대한 특정 제한이 있습니다:
|
||||
|
||||
### OpenAI
|
||||
- **이미지**: 최대 20 MB, 요청당 최대 10개 이미지
|
||||
- **PDF**: 최대 32 MB, 최대 100 페이지
|
||||
- **오디오**: 최대 25 MB, 최대 25분
|
||||
|
||||
### Anthropic
|
||||
- **이미지**: 최대 5 MB, 최대 8000x8000 픽셀, 최대 100개 이미지
|
||||
- **PDF**: 최대 32 MB, 최대 100 페이지
|
||||
|
||||
### Google Gemini
|
||||
- **이미지**: 최대 100 MB
|
||||
- **PDF**: 최대 50 MB
|
||||
- **오디오**: 최대 100 MB, 최대 9.5시간
|
||||
- **비디오**: 최대 2 GB, 최대 1시간
|
||||
|
||||
### AWS Bedrock
|
||||
- **이미지**: 최대 4.5 MB, 최대 8000x8000 픽셀
|
||||
- **PDF**: 최대 3.75 MB, 최대 100 페이지
|
||||
|
||||
## 프롬프트에서 파일 참조하기
|
||||
|
||||
작업 설명에서 파일의 키 이름을 사용하여 파일을 참조합니다:
|
||||
|
||||
```python
|
||||
task = Task(
|
||||
description="""
|
||||
제공된 자료를 분석하세요:
|
||||
1. {sales_chart}에서 차트 검토
|
||||
2. {quarterly_report}의 데이터와 교차 참조
|
||||
3. 주요 발견사항 요약
|
||||
""",
|
||||
expected_output="주요 인사이트가 포함된 분석 요약",
|
||||
input_files={
|
||||
"sales_chart": ImageFile(source="chart.png"),
|
||||
"quarterly_report": PDFFile(source="report.pdf"),
|
||||
}
|
||||
)
|
||||
```
|
||||
1063
docs/edge/ko/concepts/flows.mdx
Normal file
1063
docs/edge/ko/concepts/flows.mdx
Normal file
File diff suppressed because it is too large
Load Diff
962
docs/edge/ko/concepts/knowledge.mdx
Normal file
962
docs/edge/ko/concepts/knowledge.mdx
Normal file
@@ -0,0 +1,962 @@
|
||||
---
|
||||
title: Knowledge
|
||||
description: CrewAI에서 knowledge란 무엇이며 어떻게 사용하는지 알아봅니다.
|
||||
icon: book
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Knowledge in CrewAI는 AI 에이전트가 작업 중에 외부 정보 소스에 접근하고 이를 활용할 수 있게 해주는 강력한 시스템입니다.
|
||||
이는 에이전트에게 작업할 때 참고할 수 있는 참조 도서관을 제공하는 것과 같습니다.
|
||||
|
||||
<Info>
|
||||
Knowledge를 사용함으로써 얻는 주요 이점:
|
||||
- 에이전트에게 도메인 특화 정보를 제공
|
||||
- 실제 데이터를 통한 의사 결정 지원
|
||||
- 대화 전체의 맥락 유지
|
||||
- 응답을 사실 기반 정보에 근거
|
||||
</Info>
|
||||
|
||||
## 빠른 시작 예제
|
||||
|
||||
<Tip>
|
||||
파일 기반 Knowledge Sources의 경우, 프로젝트의 루트에 `knowledge` 디렉토리를 생성하고 그 안에 파일을 배치해야 합니다.
|
||||
또한, 소스를 생성할 때는 `knowledge` 디렉토리로부터의 상대 경로를 사용하세요.
|
||||
</Tip>
|
||||
|
||||
### 기본 문자열 지식 예제
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Task, Crew, Process, LLM
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# Create a knowledge source
|
||||
content = "Users name is John. He is 30 years old and lives in San Francisco."
|
||||
string_source = StringKnowledgeSource(content=content)
|
||||
|
||||
# Create an LLM with a temperature of 0 to ensure deterministic outputs
|
||||
llm = LLM(model="gpt-4o-mini", temperature=0)
|
||||
|
||||
# Create an agent with the knowledge store
|
||||
agent = Agent(
|
||||
role="About User",
|
||||
goal="You know everything about the user.",
|
||||
backstory="You are a master at understanding people and their preferences.",
|
||||
verbose=True,
|
||||
allow_delegation=False,
|
||||
llm=llm,
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Answer the following questions about the user: {question}",
|
||||
expected_output="An answer to the question.",
|
||||
agent=agent,
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
knowledge_sources=[string_source], # Enable knowledge by adding the sources here
|
||||
)
|
||||
|
||||
result = crew.kickoff(inputs={"question": "What city does John live in and how old is he?"})
|
||||
```
|
||||
|
||||
### 웹 콘텐츠 지식 예시
|
||||
|
||||
<Note>
|
||||
다음 예시가 작동하려면 `docling`을 설치해야 합니다: `uv add docling`
|
||||
</Note>
|
||||
|
||||
```python Code
|
||||
from crewai import LLM, Agent, Crew, Process, Task
|
||||
from crewai.knowledge.source.crew_docling_source import CrewDoclingSource
|
||||
|
||||
# Create a knowledge source from web content
|
||||
content_source = CrewDoclingSource(
|
||||
file_paths=[
|
||||
"https://lilianweng.github.io/posts/2024-11-28-reward-hacking",
|
||||
"https://lilianweng.github.io/posts/2024-07-07-hallucination",
|
||||
],
|
||||
)
|
||||
|
||||
# Create an LLM with a temperature of 0 to ensure deterministic outputs
|
||||
llm = LLM(model="gpt-4o-mini", temperature=0)
|
||||
|
||||
# Create an agent with the knowledge store
|
||||
agent = Agent(
|
||||
role="About papers",
|
||||
goal="You know everything about the papers.",
|
||||
backstory="You are a master at understanding papers and their content.",
|
||||
verbose=True,
|
||||
allow_delegation=False,
|
||||
llm=llm,
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Answer the following questions about the papers: {question}",
|
||||
expected_output="An answer to the question.",
|
||||
agent=agent,
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[task],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
knowledge_sources=[content_source],
|
||||
)
|
||||
|
||||
result = crew.kickoff(
|
||||
inputs={"question": "What is the reward hacking paper about? Be sure to provide sources."}
|
||||
)
|
||||
```
|
||||
|
||||
## 지원되는 Knowledge Sources
|
||||
|
||||
CrewAI는 다양한 유형의 knowledge source를 기본적으로 지원합니다:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="텍스트 소스" icon="text">
|
||||
- 원시 문자열
|
||||
- 텍스트 파일 (.txt)
|
||||
- PDF 문서
|
||||
</Card>
|
||||
<Card title="구조화된 데이터" icon="table">
|
||||
- CSV 파일
|
||||
- 엑셀 스프레드시트
|
||||
- JSON 문서
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### 텍스트 파일 지식 소스
|
||||
```python
|
||||
from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource
|
||||
|
||||
text_source = TextFileKnowledgeSource(
|
||||
file_paths=["document.txt", "another.txt"]
|
||||
)
|
||||
```
|
||||
|
||||
### PDF 지식 소스
|
||||
```python
|
||||
from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource
|
||||
|
||||
pdf_source = PDFKnowledgeSource(
|
||||
file_paths=["document.pdf", "another.pdf"]
|
||||
)
|
||||
```
|
||||
|
||||
### CSV 지식 소스
|
||||
```python
|
||||
from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource
|
||||
|
||||
csv_source = CSVKnowledgeSource(
|
||||
file_paths=["data.csv"]
|
||||
)
|
||||
```
|
||||
|
||||
### Excel 지식 소스
|
||||
```python
|
||||
from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource
|
||||
|
||||
excel_source = ExcelKnowledgeSource(
|
||||
file_paths=["spreadsheet.xlsx"]
|
||||
)
|
||||
```
|
||||
|
||||
### JSON 지식 소스
|
||||
```python
|
||||
from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource
|
||||
|
||||
json_source = JSONKnowledgeSource(
|
||||
file_paths=["data.json"]
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
반드시 ./knowledge 폴더를 생성해 주세요. 모든 소스 파일(예: .txt, .pdf, .xlsx, .json)은 중앙 집중식 관리를 위해 이 폴더에 보관해야 합니다.
|
||||
</Note>
|
||||
|
||||
## Agent vs Crew Knowledge: 완벽 가이드
|
||||
|
||||
<Info>
|
||||
**Knowledge 레벨 이해하기**: CrewAI는 agent와 crew 두 가지 레벨의 knowledge를 지원합니다. 이 섹션에서는 각각이 어떻게 동작하는지, 언제 초기화되는지, 그리고 dependency에 대한 일반적인 오해를 명확히 설명합니다.
|
||||
</Info>
|
||||
|
||||
### 지식 초기화가 실제로 작동하는 방식
|
||||
|
||||
다음은 지식을 사용할 때 실제로 발생하는 일입니다:
|
||||
|
||||
#### 에이전트 수준 지식 (독립적)
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# Agent with its own knowledge - NO crew knowledge needed
|
||||
specialist_knowledge = StringKnowledgeSource(
|
||||
content="Specialized technical information for this agent only"
|
||||
)
|
||||
|
||||
specialist_agent = Agent(
|
||||
role="Technical Specialist",
|
||||
goal="Provide technical expertise",
|
||||
backstory="Expert in specialized technical domains",
|
||||
knowledge_sources=[specialist_knowledge] # Agent-specific knowledge
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Answer technical questions",
|
||||
agent=specialist_agent,
|
||||
expected_output="Technical answer"
|
||||
)
|
||||
|
||||
# No crew-level knowledge required
|
||||
crew = Crew(
|
||||
agents=[specialist_agent],
|
||||
tasks=[task]
|
||||
)
|
||||
|
||||
result = crew.kickoff() # Agent knowledge works independently
|
||||
```
|
||||
|
||||
#### `crew.kickoff()` 중에 일어나는 일
|
||||
|
||||
`crew.kickoff()`를 호출하면 다음과 같은 순서로 동작합니다:
|
||||
|
||||
```python
|
||||
# During kickoff
|
||||
for agent in self.agents:
|
||||
agent.crew = self # Agent gets reference to crew
|
||||
agent.set_knowledge(crew_embedder=self.embedder) # Agent knowledge initialized
|
||||
agent.create_agent_executor()
|
||||
```
|
||||
|
||||
#### 스토리지 독립성
|
||||
|
||||
각 knowledge 수준은 독립적인 스토리지 컬렉션을 사용합니다:
|
||||
|
||||
```python
|
||||
# Agent knowledge storage
|
||||
agent_collection_name = agent.role # e.g., "Technical Specialist"
|
||||
|
||||
# Crew knowledge storage
|
||||
crew_collection_name = "crew"
|
||||
|
||||
# Both stored in same ChromaDB instance but different collections
|
||||
# Path: ~/.local/share/CrewAI/{project}/knowledge/
|
||||
# ├── crew/ # Crew knowledge collection
|
||||
# ├── Technical Specialist/ # Agent knowledge collection
|
||||
# └── Another Agent Role/ # Another agent's collection
|
||||
```
|
||||
|
||||
### 전체 작동 예제
|
||||
|
||||
#### 예시 1: Agent-Only Knowledge
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# Agent-specific knowledge
|
||||
agent_knowledge = StringKnowledgeSource(
|
||||
content="Agent-specific information that only this agent needs"
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
role="Specialist",
|
||||
goal="Use specialized knowledge",
|
||||
backstory="Expert with specific knowledge",
|
||||
knowledge_sources=[agent_knowledge],
|
||||
embedder={ # Agent can have its own embedder
|
||||
"provider": "openai",
|
||||
"config": {"model": "text-embedding-3-small"}
|
||||
}
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Answer using your specialized knowledge",
|
||||
agent=agent,
|
||||
expected_output="Answer based on agent knowledge"
|
||||
)
|
||||
|
||||
# No crew knowledge needed
|
||||
crew = Crew(agents=[agent], tasks=[task])
|
||||
result = crew.kickoff() # Works perfectly
|
||||
```
|
||||
|
||||
#### 예시 2: 에이전트 및 크루 지식 모두
|
||||
|
||||
```python
|
||||
# Crew-wide knowledge (shared by all agents)
|
||||
crew_knowledge = StringKnowledgeSource(
|
||||
content="Company policies and general information for all agents"
|
||||
)
|
||||
|
||||
# Agent-specific knowledge
|
||||
specialist_knowledge = StringKnowledgeSource(
|
||||
content="Technical specifications only the specialist needs"
|
||||
)
|
||||
|
||||
specialist = Agent(
|
||||
role="Technical Specialist",
|
||||
goal="Provide technical expertise",
|
||||
backstory="Technical expert",
|
||||
knowledge_sources=[specialist_knowledge] # Agent-specific
|
||||
)
|
||||
|
||||
generalist = Agent(
|
||||
role="General Assistant",
|
||||
goal="Provide general assistance",
|
||||
backstory="General helper"
|
||||
# No agent-specific knowledge
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[specialist, generalist],
|
||||
tasks=[...],
|
||||
knowledge_sources=[crew_knowledge] # Crew-wide knowledge
|
||||
)
|
||||
|
||||
# Result:
|
||||
# - specialist gets: crew_knowledge + specialist_knowledge
|
||||
# - generalist gets: crew_knowledge only
|
||||
```
|
||||
|
||||
#### 예제 3: 서로 다른 지식을 가진 다중 에이전트
|
||||
```python
|
||||
# Different knowledge for different agents
|
||||
sales_knowledge = StringKnowledgeSource(content="Sales procedures and pricing")
|
||||
tech_knowledge = StringKnowledgeSource(content="Technical documentation")
|
||||
support_knowledge = StringKnowledgeSource(content="Support procedures")
|
||||
|
||||
sales_agent = Agent(
|
||||
role="Sales Representative",
|
||||
knowledge_sources=[sales_knowledge],
|
||||
embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}
|
||||
)
|
||||
|
||||
tech_agent = Agent(
|
||||
role="Technical Expert",
|
||||
knowledge_sources=[tech_knowledge],
|
||||
embedder={"provider": "ollama", "config": {"model": "mxbai-embed-large"}}
|
||||
)
|
||||
|
||||
support_agent = Agent(
|
||||
role="Support Specialist",
|
||||
knowledge_sources=[support_knowledge]
|
||||
# Will use crew embedder as fallback
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[sales_agent, tech_agent, support_agent],
|
||||
tasks=[...],
|
||||
embedder={ # Fallback embedder for agents without their own
|
||||
"provider": "google",
|
||||
"config": {"model": "text-embedding-004"}
|
||||
}
|
||||
)
|
||||
|
||||
# Each agent gets only their specific knowledge
|
||||
# Each can use different embedding providers
|
||||
```
|
||||
|
||||
<Tip>
|
||||
벡터 데이터베이스에서 도구를 사용한 검색과 달리, 사전에 지식이 탑재된 에이전트는 검색 퍼소나나 태스크가 필요하지 않습니다.
|
||||
에이전트나 crew가 동작하는 데 필요한 관련 지식 소스만 추가하면 됩니다.
|
||||
|
||||
지식 소스는 에이전트 또는 crew 레벨에 추가할 수 있습니다.
|
||||
crew 레벨 지식 소스는 **crew 내 모든 에이전트**가 사용하게 됩니다.
|
||||
에이전트 레벨 지식 소스는 해당 지식이 사전 탑재된 **특정 에이전트**만 사용하게 됩니다.
|
||||
</Tip>
|
||||
|
||||
## Knowledge 구성
|
||||
|
||||
crew 또는 agent에 대해 knowledge 구성을 할 수 있습니다.
|
||||
|
||||
```python Code
|
||||
from crewai.knowledge.knowledge_config import KnowledgeConfig
|
||||
|
||||
knowledge_config = KnowledgeConfig(results_limit=10, score_threshold=0.5)
|
||||
|
||||
agent = Agent(
|
||||
...
|
||||
knowledge_config=knowledge_config
|
||||
)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`results_limit`: 반환할 관련 문서의 개수입니다. 기본값은 3입니다.
|
||||
`score_threshold`: 문서가 관련성이 있다고 간주되기 위한 최소 점수입니다. 기본값은 0.35입니다.
|
||||
</Tip>
|
||||
|
||||
## 지원되는 Knowledge 매개변수
|
||||
|
||||
<ParamField body="sources" type="List[BaseKnowledgeSource]" required="Yes">
|
||||
저장 및 쿼리할 콘텐츠를 제공하는 knowledge source들의 리스트입니다. PDF, CSV, Excel, JSON, 텍스트 파일 또는 문자열 콘텐츠를 포함할 수 있습니다.
|
||||
</ParamField>
|
||||
<ParamField body="collection_name" type="str">
|
||||
knowledge가 저장될 컬렉션의 이름입니다. 서로 다른 knowledge 세트를 식별하는 데 사용됩니다. 제공하지 않을 경우 기본값은 "knowledge"입니다.
|
||||
</ParamField>
|
||||
<ParamField body="storage" type="Optional[KnowledgeStorage]">
|
||||
knowledge가 저장되고 검색되는 방식을 관리하기 위한 커스텀 저장소 구성입니다. 별도로 제공하지 않는 경우 기본 storage가 생성됩니다.
|
||||
</ParamField>
|
||||
|
||||
## 지식 저장 투명성
|
||||
|
||||
<Info>
|
||||
**지식 저장 이해하기**: CrewAI는 ChromaDB를 사용하여 벡터 저장소에 지식 소스를 플랫폼별 디렉토리에 자동으로 저장합니다. 이러한 위치와 기본값을 이해하면 프로덕션 배포, 디버깅, 저장소 관리에 도움이 됩니다.
|
||||
</Info>
|
||||
|
||||
### CrewAI가 Knowledge 파일을 저장하는 위치
|
||||
|
||||
기본적으로 CrewAI는 memory와 동일한 저장 시스템을 사용하여, knowledge를 플랫폼별 디렉터리에 저장합니다.
|
||||
|
||||
#### 플랫폼별 기본 저장 위치
|
||||
|
||||
**macOS:**
|
||||
```
|
||||
~/Library/Application Support/CrewAI/{project_name}/
|
||||
└── knowledge/ # Knowledge ChromaDB files
|
||||
├── chroma.sqlite3 # ChromaDB metadata
|
||||
├── {collection_id}/ # Vector embeddings
|
||||
└── knowledge_{collection}/ # Named collections
|
||||
```
|
||||
|
||||
**Linux:**
|
||||
```
|
||||
~/.local/share/CrewAI/{project_name}/
|
||||
└── knowledge/
|
||||
├── chroma.sqlite3
|
||||
├── {collection_id}/
|
||||
└── knowledge_{collection}/
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
C:\Users\{username}\AppData\Local\CrewAI\{project_name}\
|
||||
└── knowledge\
|
||||
├── chroma.sqlite3
|
||||
├── {collection_id}\
|
||||
└── knowledge_{collection}\
|
||||
```
|
||||
|
||||
### 지식 저장 위치 찾기
|
||||
|
||||
CrewAI가 지식 파일을 저장하는 위치를 정확히 확인하려면:
|
||||
|
||||
```python
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
import os
|
||||
|
||||
# Get the knowledge storage path
|
||||
knowledge_path = os.path.join(db_storage_path(), "knowledge")
|
||||
print(f"Knowledge storage location: {knowledge_path}")
|
||||
|
||||
# List knowledge collections and files
|
||||
if os.path.exists(knowledge_path):
|
||||
print("\nKnowledge storage contents:")
|
||||
for item in os.listdir(knowledge_path):
|
||||
item_path = os.path.join(knowledge_path, item)
|
||||
if os.path.isdir(item_path):
|
||||
print(f"📁 Collection: {item}/")
|
||||
# Show collection contents
|
||||
try:
|
||||
for subitem in os.listdir(item_path):
|
||||
print(f" └── {subitem}")
|
||||
except PermissionError:
|
||||
print(f" └── (permission denied)")
|
||||
else:
|
||||
print(f"📄 {item}")
|
||||
else:
|
||||
print("No knowledge storage found yet.")
|
||||
```
|
||||
|
||||
### 지식 저장 위치 제어
|
||||
|
||||
#### 옵션 1: 환경 변수 (권장)
|
||||
```python
|
||||
import os
|
||||
from crewai import Crew
|
||||
|
||||
# Set custom storage location for all CrewAI data
|
||||
os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage"
|
||||
|
||||
# All knowledge will now be stored in ./my_project_storage/knowledge/
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
knowledge_sources=[...]
|
||||
)
|
||||
```
|
||||
|
||||
#### 옵션 2: 사용자 지정 Knowledge 저장소
|
||||
```python
|
||||
from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# Create custom storage with specific embedder
|
||||
custom_storage = KnowledgeStorage(
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {"model": "mxbai-embed-large"}
|
||||
},
|
||||
collection_name="my_custom_knowledge"
|
||||
)
|
||||
|
||||
# Use with knowledge sources
|
||||
knowledge_source = StringKnowledgeSource(
|
||||
content="Your knowledge content here"
|
||||
)
|
||||
knowledge_source.storage = custom_storage
|
||||
```
|
||||
|
||||
#### 옵션 3: 프로젝트별 Knowledge 저장소
|
||||
```python
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
# Store knowledge in project directory
|
||||
project_root = Path(__file__).parent
|
||||
knowledge_dir = project_root / "knowledge_storage"
|
||||
|
||||
os.environ["CREWAI_STORAGE_DIR"] = str(knowledge_dir)
|
||||
|
||||
# Now all knowledge will be stored in your project directory
|
||||
```
|
||||
|
||||
### 기본 임베딩 제공자 동작
|
||||
|
||||
<Info>
|
||||
**기본 임베딩 제공자**: CrewAI는 다른 LLM 제공자를 사용할 때도 지식 저장을 위해 기본적으로 OpenAI 임베딩(`text-embedding-3-small`)을 사용합니다. 설정에 맞게 쉽게 이 옵션을 커스터마이즈할 수 있습니다.
|
||||
</Info>
|
||||
|
||||
#### 기본 동작 이해하기
|
||||
```python
|
||||
from crewai import Agent, Crew, LLM
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# When using Claude as your LLM...
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
llm=LLM(provider="anthropic", model="claude-3-sonnet") # Using Claude
|
||||
)
|
||||
|
||||
# CrewAI will still use OpenAI embeddings by default for knowledge
|
||||
# This ensures consistency but may not match your LLM provider preference
|
||||
knowledge_source = StringKnowledgeSource(content="Research data...")
|
||||
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[...],
|
||||
knowledge_sources=[knowledge_source]
|
||||
# Default: Uses OpenAI embeddings even with Claude LLM
|
||||
)
|
||||
```
|
||||
|
||||
#### 지식 임베딩 공급자 사용자 정의
|
||||
```python
|
||||
# Option 1: Voyage AI 사용 (Claude 사용자에게 Anthropic이 권장)
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[...],
|
||||
knowledge_sources=[knowledge_source],
|
||||
embedder={
|
||||
"provider": "voyageai", # Claude 사용자에게 권장
|
||||
"config": {
|
||||
"api_key": "your-voyage-api-key",
|
||||
"model": "voyage-3" # 최고 품질을 원하면 "voyage-3-large" 사용
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Option 2: 로컬 임베딩 사용 (외부 API 호출 없음)
|
||||
crew = Crew(
|
||||
agents=[agent],
|
||||
tasks=[...],
|
||||
knowledge_sources=[knowledge_source],
|
||||
embedder={
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model": "mxbai-embed-large",
|
||||
"url": "http://localhost:11434/api/embeddings"
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
# Option 3: 에이전트 수준의 임베딩 사용자 정의
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
knowledge_sources=[knowledge_source],
|
||||
embedder={
|
||||
"provider": "google",
|
||||
"config": {
|
||||
"model": "models/text-embedding-004",
|
||||
"api_key": "your-google-key"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
#### Azure OpenAI 임베딩 구성
|
||||
|
||||
Azure OpenAI 임베딩을 사용할 때:
|
||||
1. 먼저 Azure 플랫폼에 임베딩 모델을 배포했는지 확인하세요.
|
||||
2. 그런 다음 다음과 같은 구성을 사용해야 합니다:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
knowledge_sources=[knowledge_source],
|
||||
embedder={
|
||||
"provider": "azure",
|
||||
"config": {
|
||||
"api_key": "your-azure-api-key",
|
||||
"model": "text-embedding-ada-002", # change to the model you are using and is deployed in Azure
|
||||
"api_base": "https://your-azure-endpoint.openai.azure.com/",
|
||||
"api_version": "2024-02-01"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## 고급 기능
|
||||
|
||||
### 쿼리 리라이팅
|
||||
|
||||
CrewAI는 지식 검색을 최적화하기 위해 지능형 쿼리 리라이팅 메커니즘을 구현합니다. 에이전트가 지식 소스를 검색해야 할 때, 원시 태스크 프롬프트는 자동으로 더 효과적인 검색 쿼리로 변환됩니다.
|
||||
|
||||
#### 쿼리 재작성 방식
|
||||
|
||||
1. 에이전트가 knowledge 소스를 사용할 수 있을 때 작업을 실행하면 `_get_knowledge_search_query` 메서드가 트리거됩니다.
|
||||
2. 에이전트의 LLM을 사용하여 원래 작업 프롬프트를 최적화된 검색 쿼리로 변환합니다.
|
||||
3. 이 최적화된 쿼리는 knowledge 소스에서 관련 정보를 검색하는 데 사용됩니다.
|
||||
|
||||
#### 쿼리 리라이트(Query Rewriting)의 이점
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="향상된 검색 정확도" icon="bullseye-arrow">
|
||||
주요 개념에 집중하고 불필요한 내용을 제거함으로써, 쿼리 리라이트는 보다 관련성 높은 정보를 검색할 수 있게 도와줍니다.
|
||||
</Card>
|
||||
<Card title="컨텍스트 인식" icon="brain">
|
||||
리라이트된 쿼리는 벡터 데이터베이스 검색을 위해 더욱 구체적이고 컨텍스트를 인식할 수 있도록 설계되어 있습니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
#### 예시
|
||||
|
||||
```python
|
||||
# Original task prompt
|
||||
task_prompt = "Answer the following questions about the user's favorite movies: What movie did John watch last week? Format your answer in JSON."
|
||||
|
||||
# Behind the scenes, this might be rewritten as:
|
||||
rewritten_query = "What movies did John watch last week?"
|
||||
```
|
||||
|
||||
재작성된 쿼리는 핵심 정보 요구에 더 집중하며, 출력 형식에 대한 불필요한 지시사항을 제거합니다.
|
||||
|
||||
<Tip>
|
||||
이 메커니즘은 완전히 자동으로 동작하며 사용자가 별도의 설정을 할 필요가 없습니다. agent의 LLM을 사용하여 쿼리 재작성을 수행하므로, 더 강력한 LLM을 사용할 경우 재작성된 쿼리의 품질이 향상될 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
### Knowledge 이벤트
|
||||
|
||||
CrewAI는 knowledge 검색 과정에서 이벤트를 발생시키며, 이벤트 시스템을 사용하여 이를 감지할 수 있습니다. 이러한 이벤트를 통해 에이전트가 knowledge를 어떻게 검색하고 사용하는지 모니터링, 디버깅, 분석할 수 있습니다.
|
||||
|
||||
#### 사용 가능한 Knowledge 이벤트
|
||||
|
||||
- **KnowledgeRetrievalStartedEvent**: 에이전트가 소스에서 knowledge를 검색하기 시작할 때 발생
|
||||
- **KnowledgeRetrievalCompletedEvent**: knowledge 검색이 완료되었을 때 발생하며, 사용된 쿼리와 검색된 콘텐츠를 포함
|
||||
- **KnowledgeQueryStartedEvent**: knowledge 소스에 쿼리를 시작할 때 발생
|
||||
- **KnowledgeQueryCompletedEvent**: 쿼리가 성공적으로 완료되었을 때 발생
|
||||
- **KnowledgeQueryFailedEvent**: knowledge 소스에 대한 쿼리가 실패했을 때 발생
|
||||
- **KnowledgeSearchQueryFailedEvent**: 검색 쿼리가 실패했을 때 발생
|
||||
|
||||
#### 예시: Knowledge Retrieval 모니터링
|
||||
|
||||
```python
|
||||
from crewai.events import (
|
||||
KnowledgeRetrievalStartedEvent,
|
||||
KnowledgeRetrievalCompletedEvent,
|
||||
BaseEventListener,
|
||||
)
|
||||
|
||||
class KnowledgeMonitorListener(BaseEventListener):
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(KnowledgeRetrievalStartedEvent)
|
||||
def on_knowledge_retrieval_started(source, event):
|
||||
print(f"Agent '{event.agent.role}' started retrieving knowledge")
|
||||
|
||||
@crewai_event_bus.on(KnowledgeRetrievalCompletedEvent)
|
||||
def on_knowledge_retrieval_completed(source, event):
|
||||
print(f"Agent '{event.agent.role}' completed knowledge retrieval")
|
||||
print(f"Query: {event.query}")
|
||||
print(f"Retrieved {len(event.retrieved_knowledge)} knowledge chunks")
|
||||
|
||||
# Create an instance of your listener
|
||||
knowledge_monitor = KnowledgeMonitorListener()
|
||||
```
|
||||
|
||||
이벤트 사용에 대한 자세한 내용은 [이벤트 리스너](/ko/concepts/event-listener) 문서를 참고하세요.
|
||||
|
||||
### 맞춤형 지식 소스
|
||||
|
||||
CrewAI를 사용하면 `BaseKnowledgeSource` 클래스를 확장하여 모든 유형의 데이터에 대한 맞춤형 지식 소스를 만들 수 있습니다. 이제 우주 뉴스 기사를 가져오고 처리하는 실용적인 예제를 만들어보겠습니다.
|
||||
|
||||
최근 우주 탐사 동향은 다음과 같습니다. 최신 우주 뉴스 기사들을 기반으로 정리하였습니다:
|
||||
|
||||
1. SpaceX가 2023년 11월 17일 오전에 예정된, 두 번째 Starship/Super Heavy 통합 발사를 위한 최종 규제 승인을 받았습니다. 이는 SpaceX의 우주 탐사 및 우주 식민화에 대한 야심찬 계획에서 중요한 단계입니다. [출처: SpaceNews](https://spacenews.com/starship-cleared-for-nov-17-launch/)
|
||||
|
||||
2. SpaceX는 미국 연방통신위원회(FCC)에 1세대 차세대 Starlink Gen2 위성의 첫 발사를 시작할 계획임을 알렸습니다. 이는 전 세계에 고속 인터넷을 제공하는 Starlink 위성 인터넷 서비스의 주요 업그레이드입니다. [출처: Teslarati](https://www.teslarati.com/spacex-first-starlink-gen2-satellite-launch-2022/)
|
||||
|
||||
3. AI 스타트업 Synthetaic이 시리즈 B 펀딩에서 1,500만 달러를 유치했습니다. 이 회사는 인공 지능을 사용하여 우주 및 공중 센서에서 데이터를 분석하며, 이는 우주 탐사와 위성 기술에 큰 응용 가능성이 있습니다. [출처: SpaceNews](https://spacenews.com/ai-startup-synthetaic-raises-15-million-in-series-b-funding/)
|
||||
|
||||
4. 미 우주군(Space Force)은 미국 인도-태평양 사령부(Indo-Pacific Command) 내에 부대를 공식적으로 창설하여 인도-태평양 지역에 항구적인 존재감을 확보하였습니다. 이는 우주 안보 및 지정학에 중대한 영향을 미칠 수 있습니다. [출처: SpaceNews](https://spacenews.com/space-force-establishes-permanent-presence-in-indo-pacific-region/)
|
||||
|
||||
5. 우주 추적 및 데이터 분석 기업 Slingshot Aerospace는 저지구 궤도(LEO) 커버리지를 확대하기 위해 지상 광학 망원경 네트워크를 확장하고 있습니다. 이는 저지구 궤도의 위성 및 우주 잔해 추적과 분석 능력을 향상시킬 수 있습니다. [출처: SpaceNews](https://spacenews.com/slingshots-space-tracking-network-to-extend-coverage-of-low-earth-orbit/)
|
||||
|
||||
6. 중국 국가자연과학기금위원회는 연구자들이 초대형 우주선 조립을 연구하기 위한 5개년 프로젝트를 발표했습니다. 이는 우주선 기술과 우주 탐사 역량의 비약적인 발전을 가져올 수 있습니다. [출처: SpaceNews](https://spacenews.com/china-researching-challenges-of-kilometer-scale-ultra-large-spacecraft/)
|
||||
|
||||
7. 스탠포드 대학교의 AEroSpace Autonomy Research 센터(CAESAR)는 우주선 자율성에 초점을 맞추고 있습니다. 센터는 2024년 5월 22일에 업계, 학계, 정부 간 협력을 촉진하기 위한 시작 행사를 개최하였습니다. 이는 자율 우주선 기술의 발전에 중대한 기여를 할 수 있습니다. [출처: SpaceNews](https://spacenews.com/stanford-center-focuses-on-spacecraft-autonomy/)
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
## 디버깅 및 문제 해결
|
||||
|
||||
### 지식 문제 디버깅
|
||||
|
||||
#### 에이전트 지식 초기화 확인
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
knowledge_source = StringKnowledgeSource(content="Test knowledge")
|
||||
|
||||
agent = Agent(
|
||||
role="Test Agent",
|
||||
goal="Test knowledge",
|
||||
backstory="Testing",
|
||||
knowledge_sources=[knowledge_source]
|
||||
)
|
||||
|
||||
crew = Crew(agents=[agent], tasks=[Task(...)])
|
||||
|
||||
# Before kickoff - knowledge not initialized
|
||||
print(f"Before kickoff - Agent knowledge: {getattr(agent, 'knowledge', None)}")
|
||||
|
||||
crew.kickoff()
|
||||
|
||||
# After kickoff - knowledge initialized
|
||||
print(f"After kickoff - Agent knowledge: {agent.knowledge}")
|
||||
print(f"Agent knowledge collection: {agent.knowledge.storage.collection_name}")
|
||||
print(f"Number of sources: {len(agent.knowledge.sources)}")
|
||||
```
|
||||
|
||||
#### Knowledge 저장 위치 확인
|
||||
|
||||
```python
|
||||
import os
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
|
||||
# Check storage structure
|
||||
storage_path = db_storage_path()
|
||||
knowledge_path = os.path.join(storage_path, "knowledge")
|
||||
|
||||
if os.path.exists(knowledge_path):
|
||||
print("Knowledge collections found:")
|
||||
for collection in os.listdir(knowledge_path):
|
||||
collection_path = os.path.join(knowledge_path, collection)
|
||||
if os.path.isdir(collection_path):
|
||||
print(f" - {collection}/")
|
||||
# Show collection contents
|
||||
for item in os.listdir(collection_path):
|
||||
print(f" └── {item}")
|
||||
```
|
||||
|
||||
#### 테스트 지식 검색
|
||||
```python
|
||||
# Test agent knowledge retrieval
|
||||
if hasattr(agent, 'knowledge') and agent.knowledge:
|
||||
test_query = ["test query"]
|
||||
results = agent.knowledge.query(test_query)
|
||||
print(f"Agent knowledge results: {len(results)} documents found")
|
||||
|
||||
# Test crew knowledge retrieval (if exists)
|
||||
if hasattr(crew, 'knowledge') and crew.knowledge:
|
||||
crew_results = crew.query_knowledge(test_query)
|
||||
print(f"Crew knowledge results: {len(crew_results)} documents found")
|
||||
```
|
||||
|
||||
#### 지식 컬렉션 검사하기
|
||||
```python
|
||||
import chromadb
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
import os
|
||||
|
||||
# Connect to CrewAI's knowledge ChromaDB
|
||||
knowledge_path = os.path.join(db_storage_path(), "knowledge")
|
||||
|
||||
if os.path.exists(knowledge_path):
|
||||
client = chromadb.PersistentClient(path=knowledge_path)
|
||||
collections = client.list_collections()
|
||||
|
||||
print("Knowledge Collections:")
|
||||
for collection in collections:
|
||||
print(f" - {collection.name}: {collection.count()} documents")
|
||||
|
||||
# Sample a few documents to verify content
|
||||
if collection.count() > 0:
|
||||
sample = collection.peek(limit=2)
|
||||
print(f" Sample content: {sample['documents'][0][:100]}...")
|
||||
else:
|
||||
print("No knowledge storage found")
|
||||
```
|
||||
|
||||
#### 지식 처리 확인
|
||||
```python
|
||||
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
|
||||
|
||||
# Create a test knowledge source
|
||||
test_source = StringKnowledgeSource(
|
||||
content="Test knowledge content for debugging",
|
||||
chunk_size=100, # Small chunks for testing
|
||||
chunk_overlap=20
|
||||
)
|
||||
|
||||
# Check chunking behavior
|
||||
print(f"Original content length: {len(test_source.content)}")
|
||||
print(f"Chunk size: {test_source.chunk_size}")
|
||||
print(f"Chunk overlap: {test_source.chunk_overlap}")
|
||||
|
||||
# Process and inspect chunks
|
||||
test_source.add()
|
||||
print(f"Number of chunks created: {len(test_source.chunks)}")
|
||||
for i, chunk in enumerate(test_source.chunks[:3]): # Show first 3 chunks
|
||||
print(f"Chunk {i+1}: {chunk[:50]}...")
|
||||
```
|
||||
|
||||
### 일반적인 Knowledge Storage 문제
|
||||
|
||||
**"파일을 찾을 수 없음" 오류:**
|
||||
```python
|
||||
# Ensure files are in the correct location
|
||||
from crewai.utilities.constants import KNOWLEDGE_DIRECTORY
|
||||
import os
|
||||
|
||||
knowledge_dir = KNOWLEDGE_DIRECTORY # Usually "knowledge"
|
||||
file_path = os.path.join(knowledge_dir, "your_file.pdf")
|
||||
|
||||
if not os.path.exists(file_path):
|
||||
print(f"File not found: {file_path}")
|
||||
print(f"Current working directory: {os.getcwd()}")
|
||||
print(f"Expected knowledge directory: {os.path.abspath(knowledge_dir)}")
|
||||
```
|
||||
|
||||
**"Embedding dimension mismatch" 오류:**
|
||||
```python
|
||||
# This happens when switching embedding providers
|
||||
# Reset knowledge storage to clear old embeddings
|
||||
crew.reset_memories(command_type='knowledge')
|
||||
|
||||
# Or use consistent embedding providers
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
knowledge_sources=[...],
|
||||
embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}
|
||||
)
|
||||
```
|
||||
|
||||
**"ChromaDB permission denied" 오류:**
|
||||
```bash
|
||||
# Fix storage permissions
|
||||
chmod -R 755 ~/.local/share/CrewAI/
|
||||
```
|
||||
|
||||
**Knowledge가 여러 번 실행 시 유지되지 않음:**
|
||||
```python
|
||||
# Verify storage location consistency
|
||||
import os
|
||||
from crewai.utilities.paths import db_storage_path
|
||||
|
||||
print("CREWAI_STORAGE_DIR:", os.getenv("CREWAI_STORAGE_DIR"))
|
||||
print("Computed storage path:", db_storage_path())
|
||||
print("Knowledge path:", os.path.join(db_storage_path(), "knowledge"))
|
||||
```
|
||||
|
||||
### 지식 초기화 명령어
|
||||
|
||||
```python
|
||||
# Reset only agent-specific knowledge
|
||||
crew.reset_memories(command_type='agent_knowledge')
|
||||
|
||||
# Reset both crew and agent knowledge
|
||||
crew.reset_memories(command_type='knowledge')
|
||||
|
||||
# CLI commands
|
||||
# crewai reset-memories --agent-knowledge # Agent knowledge only
|
||||
# crewai reset-memories --knowledge # All knowledge
|
||||
```
|
||||
|
||||
### 지식 초기화
|
||||
|
||||
CrewAI에 저장된 지식을 초기화해야 하는 경우, `crewai reset-memories` 명령어를 `--knowledge` 옵션과 함께 사용할 수 있습니다.
|
||||
|
||||
```bash Command
|
||||
crewai reset-memories --knowledge
|
||||
```
|
||||
|
||||
이 기능은 지식 소스를 업데이트했고, 에이전트들이 최신 정보를 사용하도록 보장하고 싶을 때 유용합니다.
|
||||
|
||||
## 베스트 프랙티스
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="콘텐츠 구성">
|
||||
- 콘텐츠 유형에 맞는 적절한 청크 크기를 유지하세요
|
||||
- 컨텍스트 보존을 위해 콘텐츠 중복을 고려하세요
|
||||
- 관련 정보를 별도의 지식 소스로 체계화하세요
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="성능 팁">
|
||||
- 콘텐츠의 복잡성에 따라 청크 크기를 조정하세요
|
||||
- 적절한 임베딩 모델을 설정하세요
|
||||
- 더 빠른 처리를 위해 로컬 임베딩 프로바이더 사용을 고려하세요
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="원타임 지식">
|
||||
- CrewAI에서 제공하는 일반적인 파일 구조에서는 kickoff가 트리거될 때마다 knowledge 소스가 임베딩됩니다.
|
||||
- knowledge 소스가 크면, 매번 동일한 데이터가 임베딩되어 비효율성과 지연이 발생합니다.
|
||||
- 이를 해결하려면 knowledge_sources 파라미터 대신 knowledge 파라미터를 직접 초기화하세요.
|
||||
- 전체 아이디어를 얻으려면 이 이슈를 참고하세요 [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="지식 관리">
|
||||
- 역할별 정보에는 agent 레벨의 knowledge를 사용하세요
|
||||
- 모든 agent가 필요로 하는 공유 정보에는 crew 레벨의 knowledge를 사용하세요
|
||||
- 서로 다른 임베딩 전략이 필요하다면 agent 레벨에서 embedder를 설정하세요
|
||||
- agent 역할을 설명적으로 유지하여 일관된 콜렉션 이름을 사용하세요
|
||||
- kickoff 후 agent.knowledge를 확인하여 knowledge 초기화를 테스트하세요
|
||||
- 지식이 저장되는 위치를 모니터링하여 storage 위치를 파악하세요
|
||||
- 올바른 명령 유형을 사용하여 적절하게 knowledge를 초기화(리셋)하세요
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="프로덕션 환경 베스트 프랙티스">
|
||||
- 프로덕션에서는 `CREWAI_STORAGE_DIR`를 지정된 위치로 설정하세요
|
||||
- LLM 구성과 맞도록 임베딩 프로바이더를 명확히 선택하고, API 키 충돌을 방지하세요
|
||||
- 문서가 추가될수록 knowledge storage 용량을 모니터링하세요
|
||||
- 도메인 또는 목적에 따라 knowledge 소스를 콜렉션 이름으로 체계화하세요
|
||||
- 지식 디렉터리를 백업 및 배포 전략에 포함시키세요
|
||||
- knowledge 파일과 storage 디렉터리에 적절한 파일 권한을 부여하세요
|
||||
- API 키와 민감한 설정에는 환경 변수를 사용하세요
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
1163
docs/edge/ko/concepts/llms.mdx
Normal file
1163
docs/edge/ko/concepts/llms.mdx
Normal file
File diff suppressed because it is too large
Load Diff
878
docs/edge/ko/concepts/memory.mdx
Normal file
878
docs/edge/ko/concepts/memory.mdx
Normal file
@@ -0,0 +1,878 @@
|
||||
---
|
||||
title: 메모리
|
||||
description: CrewAI의 통합 메모리 시스템을 활용하여 에이전트 역량을 강화합니다.
|
||||
icon: database
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI는 **통합 메모리 시스템**을 제공합니다 -- 단기, 장기, 엔터티, 외부 메모리 유형을 하나의 지능형 API인 단일 `Memory` 클래스로 대체합니다. 메모리는 저장 시 LLM을 사용하여 콘텐츠를 분석하고(범위, 카테고리, 중요도 추론) 의미 유사도, 최신성, 중요도를 혼합한 복합 점수로 적응형 깊이 recall을 지원합니다.
|
||||
|
||||
메모리를 네 가지 방법으로 사용할 수 있습니다: **독립 실행**(스크립트, 노트북), **Crew와 함께**, **에이전트와 함께**, 또는 **Flow 내부에서**.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# 저장 -- LLM이 scope, categories, importance를 추론
|
||||
memory.remember("We decided to use PostgreSQL for the user database.")
|
||||
|
||||
# 검색 -- 복합 점수(의미 + 최신성 + 중요도)로 결과 순위 매기기
|
||||
matches = memory.recall("What database did we choose?")
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# 빠르게 변하는 프로젝트를 위한 점수 조정
|
||||
memory = Memory(recency_weight=0.5, recency_half_life_days=7)
|
||||
|
||||
# 삭제
|
||||
memory.forget(scope="/project/old")
|
||||
|
||||
# 자동 구성된 scope 트리 탐색
|
||||
print(memory.tree())
|
||||
print(memory.info("/"))
|
||||
```
|
||||
|
||||
## 메모리를 사용하는 네 가지 방법
|
||||
|
||||
### 독립 실행
|
||||
|
||||
스크립트, 노트북, CLI 도구 또는 독립 지식 베이스로 메모리를 사용합니다 -- 에이전트나 crew가 필요하지 않습니다.
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# 지식 구축
|
||||
memory.remember("The API rate limit is 1000 requests per minute.")
|
||||
memory.remember("Our staging environment uses port 8080.")
|
||||
memory.remember("The team agreed to use feature flags for all new releases.")
|
||||
|
||||
# 나중에 필요한 것을 recall
|
||||
matches = memory.recall("What are our API limits?", limit=5)
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# 긴 텍스트에서 원자적 사실 추출
|
||||
raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL
|
||||
next quarter. The budget is $50k. Sarah will lead the migration."""
|
||||
|
||||
facts = memory.extract_memories(raw)
|
||||
# ["Migration from MySQL to PostgreSQL planned for next quarter",
|
||||
# "Database migration budget is $50k",
|
||||
# "Sarah will lead the database migration"]
|
||||
|
||||
for fact in facts:
|
||||
memory.remember(fact)
|
||||
```
|
||||
|
||||
### Crew와 함께 사용
|
||||
|
||||
기본 설정은 `memory=True`를 전달하고, 사용자 정의 동작은 설정된 `Memory` 인스턴스를 전달합니다.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Agent, Task, Process, Memory
|
||||
|
||||
# 옵션 1: 기본 메모리
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
process=Process.sequential,
|
||||
memory=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
# 옵션 2: 조정된 점수가 있는 사용자 정의 메모리
|
||||
memory = Memory(
|
||||
recency_weight=0.4,
|
||||
semantic_weight=0.4,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=14,
|
||||
)
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
memory=memory,
|
||||
)
|
||||
```
|
||||
|
||||
`memory=True`일 때 crew는 기본 `Memory()`를 생성하고 crew의 `embedder` 설정을 자동으로 전달합니다. crew의 모든 에이전트는 자체 메모리가 없는 한 crew의 메모리를 공유합니다.
|
||||
|
||||
각 작업 후 crew는 자동으로 작업 출력에서 개별 사실을 추출하여 저장합니다. 각 작업 전에 에이전트는 메모리에서 관련 컨텍스트를 recall하여 작업 프롬프트에 주입합니다.
|
||||
|
||||
### 에이전트와 함께 사용
|
||||
|
||||
에이전트는 crew의 공유 메모리(기본값)를 사용하거나 비공개 컨텍스트를 위한 범위 지정 뷰를 받을 수 있습니다.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# 연구원은 비공개 scope를 받음 -- /agent/researcher만 볼 수 있음
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Find and analyze information",
|
||||
backstory="Expert researcher with attention to detail",
|
||||
memory=memory.scope("/agent/researcher"),
|
||||
)
|
||||
|
||||
# 작성자는 crew 공유 메모리 사용 (에이전트 수준 메모리 미설정)
|
||||
writer = Agent(
|
||||
role="Writer",
|
||||
goal="Produce clear, well-structured content",
|
||||
backstory="Experienced technical writer",
|
||||
# memory 미설정 -- crew에 메모리가 활성화되면 crew._memory 사용
|
||||
)
|
||||
```
|
||||
|
||||
이 패턴은 연구원에게 비공개 발견을 제공하면서 작성자는 crew 공유 메모리에서 읽습니다.
|
||||
|
||||
### Flow와 함께 사용
|
||||
|
||||
모든 Flow에는 내장 메모리가 있습니다. 모든 flow 메서드 내부에서 `self.remember()`, `self.recall()`, `self.extract_memories()`를 사용하세요.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
|
||||
class ResearchFlow(Flow):
|
||||
@start()
|
||||
def gather_data(self):
|
||||
findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k."
|
||||
self.remember(findings, scope="/research/databases")
|
||||
return findings
|
||||
|
||||
@listen(gather_data)
|
||||
def write_report(self, findings):
|
||||
# 컨텍스트를 제공하기 위해 과거 연구 recall
|
||||
past = self.recall("database performance benchmarks")
|
||||
context = "\n".join(f"- {m.record.content}" for m in past)
|
||||
return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}"
|
||||
```
|
||||
|
||||
Flow에서의 메모리에 대한 자세한 내용은 [Flows 문서](/concepts/flows)를 참조하세요.
|
||||
|
||||
|
||||
## 계층적 범위(Scopes)
|
||||
|
||||
### 범위란 무엇인가
|
||||
|
||||
메모리는 파일 시스템과 유사한 계층적 scope 트리로 구성됩니다. 각 scope는 `/`, `/project/alpha` 또는 `/agent/researcher/findings`와 같은 경로입니다.
|
||||
|
||||
```
|
||||
/
|
||||
/company
|
||||
/company/engineering
|
||||
/company/product
|
||||
/project
|
||||
/project/alpha
|
||||
/project/beta
|
||||
/agent
|
||||
/agent/researcher
|
||||
/agent/writer
|
||||
```
|
||||
|
||||
범위는 **컨텍스트 의존적 메모리**를 제공합니다 -- 범위 내에서 recall하면 해당 트리 분기만 검색하여 정밀도와 성능을 모두 향상시킵니다.
|
||||
|
||||
### 범위 추론 작동 방식
|
||||
|
||||
`remember()` 호출 시 scope를 지정하지 않으면 LLM이 콘텐츠와 기존 scope 트리를 분석한 후 최적의 배치를 제안합니다. 적합한 기존 scope가 없으면 새로 생성합니다. 시간이 지남에 따라 scope 트리는 콘텐츠 자체에서 유기적으로 성장합니다 -- 미리 스키마를 설계할 필요가 없습니다.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# LLM이 콘텐츠에서 scope 추론
|
||||
memory.remember("We chose PostgreSQL for the user database.")
|
||||
# -> /project/decisions 또는 /engineering/database 아래에 배치될 수 있음
|
||||
|
||||
# scope를 명시적으로 지정할 수도 있음
|
||||
memory.remember("Sprint velocity is 42 points", scope="/team/metrics")
|
||||
```
|
||||
|
||||
### 범위 트리 시각화
|
||||
|
||||
```python
|
||||
print(memory.tree())
|
||||
# / (15 records)
|
||||
# /project (8 records)
|
||||
# /project/alpha (5 records)
|
||||
# /project/beta (3 records)
|
||||
# /agent (7 records)
|
||||
# /agent/researcher (4 records)
|
||||
# /agent/writer (3 records)
|
||||
|
||||
print(memory.info("/project/alpha"))
|
||||
# ScopeInfo(path='/project/alpha', record_count=5,
|
||||
# categories=['architecture', 'database'],
|
||||
# oldest_record=datetime(...), newest_record=datetime(...),
|
||||
# child_scopes=[])
|
||||
```
|
||||
|
||||
### MemoryScope: 하위 트리 뷰
|
||||
|
||||
`MemoryScope`는 모든 연산을 트리의 한 분기로 제한합니다. 이를 사용하는 에이전트나 코드는 해당 하위 트리 내에서만 보고 쓸 수 있습니다.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# 특정 에이전트를 위한 scope 생성
|
||||
agent_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# 모든 것이 /agent/researcher 기준으로 상대적
|
||||
agent_memory.remember("Found three relevant papers on LLM memory.")
|
||||
# -> /agent/researcher 아래에 저장
|
||||
|
||||
agent_memory.recall("relevant papers")
|
||||
# -> /agent/researcher 아래에서만 검색
|
||||
|
||||
# subscope로 더 좁히기
|
||||
project_memory = agent_memory.subscope("project-alpha")
|
||||
# -> /agent/researcher/project-alpha
|
||||
```
|
||||
|
||||
### 범위 설계 모범 사례
|
||||
|
||||
- **평평하게 시작하고 LLM이 구성하게 하세요.** 범위 계층 구조를 미리 과도하게 설계하지 마세요. `memory.remember(content)`로 시작하고 콘텐츠가 축적됨에 따라 LLM의 scope 추론이 구조를 만들게 하세요.
|
||||
|
||||
- **`/{엔터티_유형}/{식별자}` 패턴을 사용하세요.** `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp` 같은 패턴에서 자연스러운 계층 구조가 나타납니다.
|
||||
|
||||
- **데이터 유형이 아닌 관심사별로 scope를 지정하세요.** `/decisions/project/alpha` 대신 `/project/alpha/decisions`를 사용하세요. 이렇게 하면 관련 콘텐츠가 함께 유지됩니다.
|
||||
|
||||
- **깊이를 얕게 유지하세요 (2-3 수준).** 깊이 중첩된 scope는 너무 희소해집니다. `/project/alpha/architecture`는 좋지만 `/project/alpha/architecture/decisions/databases/postgresql`은 너무 깊습니다.
|
||||
|
||||
- **알 때는 명시적 scope를, 모를 때는 LLM 추론을 사용하세요.** 알려진 프로젝트 결정을 저장할 때는 `scope="/project/alpha/decisions"`를 전달하세요. 자유 형식 에이전트 출력을 저장할 때는 scope를 생략하고 LLM이 결정하게 하세요.
|
||||
|
||||
### 사용 사례 예시
|
||||
|
||||
**다중 프로젝트 팀:**
|
||||
```python
|
||||
memory = Memory()
|
||||
# 각 프로젝트가 자체 분기를 가짐
|
||||
memory.remember("Using microservices architecture", scope="/project/alpha/architecture")
|
||||
memory.remember("GraphQL API for client apps", scope="/project/beta/api")
|
||||
|
||||
# 모든 프로젝트에서 recall
|
||||
memory.recall("API design decisions")
|
||||
|
||||
# 특정 프로젝트 내에서만
|
||||
memory.recall("API design", scope="/project/beta")
|
||||
```
|
||||
|
||||
**공유 지식과 에이전트별 비공개 컨텍스트:**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# 연구원은 비공개 발견을 가짐
|
||||
researcher_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# 작성자는 자체 scope와 공유 회사 지식에서 읽을 수 있음
|
||||
writer_view = memory.slice(
|
||||
scopes=["/agent/writer", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
```
|
||||
|
||||
**고객 지원 (고객별 컨텍스트):**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# 각 고객이 격리된 컨텍스트를 가짐
|
||||
memory.remember("Prefers email communication", scope="/customer/acme-corp")
|
||||
memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp")
|
||||
|
||||
# 공유 제품 문서는 모든 에이전트가 접근 가능
|
||||
memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs")
|
||||
```
|
||||
|
||||
|
||||
## 메모리 슬라이스
|
||||
|
||||
### 슬라이스란 무엇인가
|
||||
|
||||
`MemorySlice`는 여러 개의 분리된 scope에 대한 뷰입니다. 하나의 하위 트리로 제한하는 scope와 달리, 슬라이스는 여러 분기에서 동시에 recall할 수 있게 합니다.
|
||||
|
||||
### 슬라이스 vs 범위 사용 시기
|
||||
|
||||
- **범위(Scope)**: 에이전트나 코드 블록을 단일 하위 트리로 제한해야 할 때 사용. 예: `/agent/researcher`만 보는 에이전트.
|
||||
- **슬라이스(Slice)**: 여러 분기의 컨텍스트를 결합해야 할 때 사용. 예: 자체 scope와 공유 회사 지식에서 읽는 에이전트.
|
||||
|
||||
### 읽기 전용 슬라이스
|
||||
|
||||
가장 일반적인 패턴: 에이전트에게 여러 분기에 대한 읽기 액세스를 제공하되 공유 영역에 쓰지 못하게 합니다.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# 에이전트는 자체 scope와 회사 지식에서 recall 가능,
|
||||
# 하지만 회사 지식에 쓸 수 없음
|
||||
agent_view = memory.slice(
|
||||
scopes=["/agent/researcher", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
|
||||
matches = agent_view.recall("company security policies", limit=5)
|
||||
# /agent/researcher와 /company/knowledge 모두에서 검색, 결과 병합 및 순위 매기기
|
||||
|
||||
agent_view.remember("new finding") # PermissionError 발생 (읽기 전용)
|
||||
```
|
||||
|
||||
### 읽기/쓰기 슬라이스
|
||||
|
||||
읽기 전용이 비활성화되면 포함된 scope 중 어디에든 쓸 수 있지만, 어떤 scope인지 명시적으로 지정해야 합니다.
|
||||
|
||||
```python
|
||||
view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False)
|
||||
|
||||
# 쓸 때 scope를 반드시 지정
|
||||
view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"])
|
||||
```
|
||||
|
||||
|
||||
## 복합 점수(Composite Scoring)
|
||||
|
||||
Recall 결과는 세 가지 신호의 가중 조합으로 순위가 매겨집니다:
|
||||
|
||||
```
|
||||
composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance
|
||||
```
|
||||
|
||||
여기서:
|
||||
- **similarity** = 벡터 인덱스에서 `1 / (1 + distance)` (0에서 1)
|
||||
- **decay** = `0.5^(age_days / half_life_days)` -- 지수 감쇠 (오늘은 1.0, 반감기에서 0.5)
|
||||
- **importance** = 레코드의 중요도 점수 (0에서 1), 인코딩 시 설정
|
||||
|
||||
`Memory` 생성자에서 직접 설정합니다:
|
||||
|
||||
```python
|
||||
# 스프린트 회고: 최근 메모리 선호, 짧은 반감기
|
||||
memory = Memory(
|
||||
recency_weight=0.5,
|
||||
semantic_weight=0.3,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=7,
|
||||
)
|
||||
|
||||
# 아키텍처 지식 베이스: 중요한 메모리 선호, 긴 반감기
|
||||
memory = Memory(
|
||||
recency_weight=0.1,
|
||||
semantic_weight=0.5,
|
||||
importance_weight=0.4,
|
||||
recency_half_life_days=180,
|
||||
)
|
||||
```
|
||||
|
||||
각 `MemoryMatch`에는 결과가 해당 위치에 순위된 이유를 볼 수 있는 `match_reasons` 목록이 포함됩니다 (예: `["semantic", "recency", "importance"]`).
|
||||
|
||||
|
||||
## LLM 분석 레이어
|
||||
|
||||
메모리는 LLM을 세 가지 방식으로 사용합니다:
|
||||
|
||||
1. **저장 시** -- scope, categories, importance를 생략하면 LLM이 콘텐츠를 분석하여 scope, categories, importance, 메타데이터(엔터티, 날짜, 주제)를 제안합니다.
|
||||
2. **recall 시** -- deep/auto recall의 경우 LLM이 쿼리(키워드, 시간 힌트, 제안 scope, 복잡도)를 분석하여 검색을 안내합니다.
|
||||
3. **메모리 추출** -- `extract_memories(content)`는 원시 텍스트(예: 작업 출력)를 개별 메모리 문장으로 나눕니다. 에이전트는 각 문장에 `remember()`를 호출하기 전에 이를 사용하여 하나의 큰 블록 대신 원자적 사실이 저장되도록 합니다.
|
||||
|
||||
모든 분석은 LLM 실패 시 우아하게 저하됩니다 -- [오류 시 동작](#오류-시-동작)을 참조하세요.
|
||||
|
||||
|
||||
## 메모리 통합
|
||||
|
||||
새 콘텐츠를 저장할 때 인코딩 파이프라인은 자동으로 스토리지에서 유사한 기존 레코드를 확인합니다. 유사도가 `consolidation_threshold`(기본값 0.85) 이상이면 LLM이 처리 방법을 결정합니다:
|
||||
|
||||
- **keep** -- 기존 레코드가 여전히 정확하고 중복이 아닙니다.
|
||||
- **update** -- 기존 레코드를 새 정보로 업데이트해야 합니다 (LLM이 병합된 콘텐츠를 제공).
|
||||
- **delete** -- 기존 레코드가 오래되었거나, 대체되었거나, 모순됩니다.
|
||||
- **insert_new** -- 새 콘텐츠를 별도의 레코드로 삽입해야 하는지 여부.
|
||||
|
||||
이를 통해 중복이 축적되는 것을 방지합니다. 예를 들어, "CrewAI ensures reliable operation"을 세 번 저장하면 통합이 중복을 인식하고 하나의 레코드만 유지합니다.
|
||||
|
||||
### 배치 내 중복 제거
|
||||
|
||||
`remember_many()`를 사용할 때 동일 배치 내의 항목은 스토리지에 도달하기 전에 서로 비교됩니다. 두 항목의 코사인 유사도가 `batch_dedup_threshold`(기본값 0.98) 이상이면 나중 항목이 자동으로 삭제됩니다. 이는 LLM 호출 없이 순수 벡터 연산으로 단일 배치 내의 정확하거나 거의 정확한 중복을 잡아냅니다.
|
||||
|
||||
```python
|
||||
# 2개의 레코드만 저장됨 (세 번째는 첫 번째의 거의 중복)
|
||||
memory.remember_many([
|
||||
"CrewAI supports complex workflows.",
|
||||
"Python is a great language.",
|
||||
"CrewAI supports complex workflows.", # 배치 내 중복 제거로 삭제
|
||||
])
|
||||
```
|
||||
|
||||
|
||||
## 비차단 저장
|
||||
|
||||
`remember_many()`는 **비차단**입니다 -- 인코딩 파이프라인을 백그라운드 스레드에 제출하고 즉시 반환합니다. 이는 메모리가 저장되는 동안 에이전트가 다음 작업을 계속할 수 있음을 의미합니다.
|
||||
|
||||
```python
|
||||
# 즉시 반환 -- 저장은 백그라운드에서 발생
|
||||
memory.remember_many(["Fact A.", "Fact B.", "Fact C."])
|
||||
|
||||
# recall()은 검색 전에 보류 중인 저장을 자동으로 대기
|
||||
matches = memory.recall("facts") # 3개 레코드 모두 확인 가능
|
||||
```
|
||||
|
||||
### 읽기 배리어
|
||||
|
||||
모든 `recall()` 호출은 검색 전에 자동으로 `drain_writes()`를 호출하여 쿼리가 항상 최신 저장된 레코드를 볼 수 있도록 합니다. 이는 투명하게 작동하므로 별도로 신경 쓸 필요가 없습니다.
|
||||
|
||||
### Crew 종료
|
||||
|
||||
crew가 완료되면 `kickoff()`는 `finally` 블록에서 보류 중인 모든 메모리 저장을 드레인하므로, 백그라운드 저장이 진행 중인 상태에서 crew가 완료되더라도 저장이 손실되지 않습니다.
|
||||
|
||||
### 독립 실행 사용
|
||||
|
||||
crew 수명 주기가 없는 스크립트나 노트북에서는 `drain_writes()` 또는 `close()`를 명시적으로 호출하세요:
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
memory.remember_many(["Fact A.", "Fact B."])
|
||||
|
||||
# 옵션 1: 보류 중인 저장 대기
|
||||
memory.drain_writes()
|
||||
|
||||
# 옵션 2: 드레인 후 백그라운드 풀 종료
|
||||
memory.close()
|
||||
```
|
||||
|
||||
|
||||
## 출처 및 개인정보
|
||||
|
||||
모든 메모리 레코드는 출처 추적을 위한 `source` 태그와 접근 제어를 위한 `private` 플래그를 가질 수 있습니다.
|
||||
|
||||
### 출처 추적
|
||||
|
||||
`source` 매개변수는 메모리의 출처를 식별합니다:
|
||||
|
||||
```python
|
||||
# 메모리에 출처 태그 지정
|
||||
memory.remember("User prefers dark mode", source="user:alice")
|
||||
memory.remember("System config updated", source="admin")
|
||||
memory.remember("Agent found a bug", source="agent:debugger")
|
||||
|
||||
# 특정 출처의 메모리만 recall
|
||||
matches = memory.recall("user preferences", source="user:alice")
|
||||
```
|
||||
|
||||
### 비공개 메모리
|
||||
|
||||
비공개 메모리는 `source`가 일치할 때만 recall에서 볼 수 있습니다:
|
||||
|
||||
```python
|
||||
# 비공개 메모리 저장
|
||||
memory.remember("Alice's API key is sk-...", source="user:alice", private=True)
|
||||
|
||||
# 이 recall은 비공개 메모리를 볼 수 있음 (source 일치)
|
||||
matches = memory.recall("API key", source="user:alice")
|
||||
|
||||
# 이 recall은 볼 수 없음 (다른 source)
|
||||
matches = memory.recall("API key", source="user:bob")
|
||||
|
||||
# 관리자 액세스: source에 관계없이 모든 비공개 레코드 보기
|
||||
matches = memory.recall("API key", include_private=True)
|
||||
```
|
||||
|
||||
이는 서로 다른 사용자의 메모리가 격리되어야 하는 다중 사용자 또는 엔터프라이즈 배포에서 특히 유용합니다.
|
||||
|
||||
|
||||
## RecallFlow (딥 Recall)
|
||||
|
||||
`recall()`은 두 가지 깊이를 지원합니다:
|
||||
|
||||
- **`depth="shallow"`** -- 복합 점수를 사용한 직접 벡터 검색. 빠름 (~200ms), LLM 호출 없음.
|
||||
- **`depth="deep"` (기본값)** -- 다단계 RecallFlow 실행: 쿼리 분석, scope 선택, 병렬 벡터 검색, 신뢰도 기반 라우팅, 신뢰도가 낮을 때 선택적 재귀 탐색.
|
||||
|
||||
**스마트 LLM 건너뛰기**: `query_analysis_threshold`(기본값 200자)보다 짧은 쿼리는 deep 모드에서도 LLM 쿼리 분석을 완전히 건너뜁니다. "What database do we use?"와 같은 짧은 쿼리는 이미 좋은 검색 구문이므로 LLM 분석이 큰 가치를 더하지 않습니다. 이를 통해 일반적인 짧은 쿼리에서 recall당 ~1-3초를 절약합니다. 긴 쿼리(예: 전체 작업 설명)만 대상 하위 쿼리로의 LLM 분석을 거칩니다.
|
||||
|
||||
```python
|
||||
# Shallow: 순수 벡터 검색, LLM 없음
|
||||
matches = memory.recall("What did we decide?", limit=10, depth="shallow")
|
||||
|
||||
# Deep (기본값): 긴 쿼리에 대한 LLM 분석을 포함한 지능형 검색
|
||||
matches = memory.recall(
|
||||
"Summarize all architecture decisions from this quarter",
|
||||
limit=10,
|
||||
depth="deep",
|
||||
)
|
||||
```
|
||||
|
||||
RecallFlow 라우터를 제어하는 신뢰도 임계값은 설정 가능합니다:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
confidence_threshold_high=0.9, # 매우 확신할 때만 합성
|
||||
confidence_threshold_low=0.4, # 더 적극적으로 깊이 탐색
|
||||
exploration_budget=2, # 최대 2라운드 탐색 허용
|
||||
query_analysis_threshold=200, # 이보다 짧은 쿼리는 LLM 건너뛰기
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Embedder 설정
|
||||
|
||||
메모리는 의미 검색을 위해 텍스트를 벡터로 변환하는 임베딩 모델이 필요합니다. 세 가지 방법으로 설정할 수 있습니다.
|
||||
|
||||
### Memory에 직접 전달
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
# 설정 dict로
|
||||
memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}})
|
||||
|
||||
# 사전 구축된 callable로
|
||||
from crewai.rag.embeddings.factory import build_embedder
|
||||
embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}})
|
||||
memory = Memory(embedder=embedder)
|
||||
```
|
||||
|
||||
### Crew Embedder 설정으로
|
||||
|
||||
`memory=True` 사용 시 crew의 `embedder` 설정이 전달됩니다:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}},
|
||||
)
|
||||
```
|
||||
|
||||
### 제공자 예시
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenAI (기본)">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model_name": "text-embedding-3-small",
|
||||
# "api_key": "sk-...", # 또는 OPENAI_API_KEY 환경 변수 설정
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ollama (로컬, 비공개)">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model_name": "mxbai-embed-large",
|
||||
"url": "http://localhost:11434/api/embeddings",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azure OpenAI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "azure",
|
||||
"config": {
|
||||
"deployment_id": "your-embedding-deployment",
|
||||
"api_key": "your-azure-api-key",
|
||||
"api_base": "https://your-resource.openai.azure.com",
|
||||
"api_version": "2024-02-01",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google AI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "google-generativeai",
|
||||
"config": {
|
||||
"model_name": "gemini-embedding-001",
|
||||
# "api_key": "...", # 또는 GOOGLE_API_KEY 환경 변수 설정
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google Vertex AI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "google-vertex",
|
||||
"config": {
|
||||
"model_name": "gemini-embedding-001",
|
||||
"project_id": "your-gcp-project-id",
|
||||
"location": "us-central1",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cohere">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "cohere",
|
||||
"config": {
|
||||
"model_name": "embed-english-v3.0",
|
||||
# "api_key": "...", # 또는 COHERE_API_KEY 환경 변수 설정
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="VoyageAI">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "voyageai",
|
||||
"config": {
|
||||
"model": "voyage-3",
|
||||
# "api_key": "...", # 또는 VOYAGE_API_KEY 환경 변수 설정
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="AWS Bedrock">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "amazon-bedrock",
|
||||
"config": {
|
||||
"model_name": "amazon.titan-embed-text-v1",
|
||||
# 기본 AWS 자격 증명 사용 (boto3 세션)
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Hugging Face">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "huggingface",
|
||||
"config": {
|
||||
"model_name": "sentence-transformers/all-MiniLM-L6-v2",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Jina">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "jina",
|
||||
"config": {
|
||||
"model_name": "jina-embeddings-v2-base-en",
|
||||
# "api_key": "...", # 또는 JINA_API_KEY 환경 변수 설정
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="IBM WatsonX">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "watsonx",
|
||||
"config": {
|
||||
"model_id": "ibm/slate-30m-english-rtrvr",
|
||||
"api_key": "your-watsonx-api-key",
|
||||
"project_id": "your-project-id",
|
||||
"url": "https://us-south.ml.cloud.ibm.com",
|
||||
},
|
||||
})
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="사용자 정의 Embedder">
|
||||
```python
|
||||
# 문자열 목록을 받아 벡터 목록을 반환하는 callable 전달
|
||||
def my_embedder(texts: list[str]) -> list[list[float]]:
|
||||
# 임베딩 로직
|
||||
return [[0.1, 0.2, ...] for _ in texts]
|
||||
|
||||
memory = Memory(embedder=my_embedder)
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 제공자 참조
|
||||
|
||||
| 제공자 | 키 | 일반적인 모델 | 참고 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| OpenAI | `openai` | `text-embedding-3-small` | 기본값. `OPENAI_API_KEY` 설정. |
|
||||
| Ollama | `ollama` | `mxbai-embed-large` | 로컬, API 키 불필요. |
|
||||
| Azure OpenAI | `azure` | `text-embedding-ada-002` | `deployment_id` 필요. |
|
||||
| Google AI | `google-generativeai` | `gemini-embedding-001` | `GOOGLE_API_KEY` 설정. |
|
||||
| Google Vertex | `google-vertex` | `gemini-embedding-001` | `project_id` 필요. |
|
||||
| Cohere | `cohere` | `embed-english-v3.0` | 강력한 다국어 지원. |
|
||||
| VoyageAI | `voyageai` | `voyage-3` | 검색에 최적화. |
|
||||
| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | boto3 자격 증명 사용. |
|
||||
| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | 로컬 sentence-transformers. |
|
||||
| Jina | `jina` | `jina-embeddings-v2-base-en` | `JINA_API_KEY` 설정. |
|
||||
| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | `project_id` 필요. |
|
||||
| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | 로컬, API 키 불필요. |
|
||||
| Custom | `custom` | -- | `embedding_callable` 필요. |
|
||||
|
||||
|
||||
## LLM 설정
|
||||
|
||||
메모리는 저장 분석(scope, categories, importance 추론), 통합 결정, 딥 recall 쿼리 분석에 LLM을 사용합니다. 사용할 모델을 설정할 수 있습니다.
|
||||
|
||||
```python
|
||||
from crewai import Memory, LLM
|
||||
|
||||
# 기본값: gpt-4o-mini
|
||||
memory = Memory()
|
||||
|
||||
# 다른 OpenAI 모델 사용
|
||||
memory = Memory(llm="gpt-4o")
|
||||
|
||||
# Anthropic 사용
|
||||
memory = Memory(llm="anthropic/claude-3-haiku-20240307")
|
||||
|
||||
# 완전한 로컬/비공개 분석을 위해 Ollama 사용
|
||||
memory = Memory(llm="ollama/llama3.2")
|
||||
|
||||
# Google Gemini 사용
|
||||
memory = Memory(llm="gemini/gemini-2.0-flash")
|
||||
|
||||
# 사용자 정의 설정이 있는 사전 구성된 LLM 인스턴스 전달
|
||||
llm = LLM(model="gpt-4o", temperature=0)
|
||||
memory = Memory(llm=llm)
|
||||
```
|
||||
|
||||
LLM은 **지연 초기화**됩니다 -- 처음 필요할 때만 생성됩니다. 즉, API 키가 설정되지 않아도 `Memory()` 생성 시에는 실패하지 않습니다. 오류는 LLM이 실제로 호출될 때만 발생합니다(예: 명시적 scope/categories 없이 저장할 때 또는 딥 recall 중).
|
||||
|
||||
완전한 오프라인/비공개 운영을 위해 LLM과 embedder 모두에 로컬 모델을 사용하세요:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
llm="ollama/llama3.2",
|
||||
embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## 스토리지 백엔드
|
||||
|
||||
- **기본값**: LanceDB, `./.crewai/memory` 아래에 저장 (또는 환경 변수가 설정된 경우 `$CREWAI_STORAGE_DIR/memory`, 또는 `storage="path/to/dir"`로 전달한 경로).
|
||||
- **사용자 정의 백엔드**: `StorageBackend` 프로토콜을 구현하고(`crewai.memory.storage.backend` 참조) `Memory(storage=your_backend)`에 인스턴스를 전달합니다.
|
||||
|
||||
|
||||
## 탐색(Discovery)
|
||||
|
||||
scope 계층 구조, 카테고리, 레코드를 검사합니다:
|
||||
|
||||
```python
|
||||
memory.tree() # scope 및 레코드 수의 포맷된 트리
|
||||
memory.tree("/project", max_depth=2) # 하위 트리 뷰
|
||||
memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest
|
||||
memory.list_scopes("/") # 직계 자식 scope
|
||||
memory.list_categories() # 카테고리 이름 및 개수
|
||||
memory.list_records(scope="/project/alpha", limit=20) # scope의 레코드, 최신순
|
||||
```
|
||||
|
||||
|
||||
## 오류 시 동작
|
||||
|
||||
분석 중 LLM이 실패하면(네트워크 오류, 속도 제한, 잘못된 응답) 메모리는 우아하게 저하됩니다:
|
||||
|
||||
- **저장 분석** -- 경고가 로깅되고 메모리는 기본 scope `/`, 빈 categories, importance `0.5`로 저장됩니다.
|
||||
- **메모리 추출** -- 전체 콘텐츠가 단일 메모리로 저장되어 누락되지 않습니다.
|
||||
- **쿼리 분석** -- recall은 단순 scope 선택 및 벡터 검색으로 폴백하여 결과를 계속 반환합니다.
|
||||
|
||||
이러한 분석 실패에서는 예외가 발생하지 않으며, 스토리지 또는 embedder 실패만 예외를 발생시킵니다.
|
||||
|
||||
|
||||
## 개인정보 참고
|
||||
|
||||
메모리 콘텐츠는 분석을 위해 설정된 LLM으로 전송됩니다(저장 시 scope/categories/importance, 쿼리 분석 및 선택적 딥 recall). 민감한 데이터의 경우 로컬 LLM(예: Ollama)을 사용하거나 제공자가 규정 요구 사항을 충족하는지 확인하세요.
|
||||
|
||||
|
||||
## 메모리 이벤트
|
||||
|
||||
모든 메모리 연산은 `source_type="unified_memory"`로 이벤트를 발생시킵니다. 시간, 오류, 콘텐츠를 수신할 수 있습니다.
|
||||
|
||||
| 이벤트 | 설명 | 주요 속성 |
|
||||
| :---- | :---------- | :------------- |
|
||||
| **MemoryQueryStartedEvent** | 쿼리 시작 | `query`, `limit` |
|
||||
| **MemoryQueryCompletedEvent** | 쿼리 성공 | `query`, `results`, `query_time_ms` |
|
||||
| **MemoryQueryFailedEvent** | 쿼리 실패 | `query`, `error` |
|
||||
| **MemorySaveStartedEvent** | 저장 시작 | `value`, `metadata` |
|
||||
| **MemorySaveCompletedEvent** | 저장 성공 | `value`, `save_time_ms` |
|
||||
| **MemorySaveFailedEvent** | 저장 실패 | `value`, `error` |
|
||||
| **MemoryRetrievalStartedEvent** | 에이전트 검색 시작 | `task_id` |
|
||||
| **MemoryRetrievalCompletedEvent** | 에이전트 검색 완료 | `task_id`, `memory_content`, `retrieval_time_ms` |
|
||||
|
||||
예: 쿼리 시간 모니터링:
|
||||
|
||||
```python
|
||||
from crewai.events import BaseEventListener, MemoryQueryCompletedEvent
|
||||
|
||||
class MemoryMonitor(BaseEventListener):
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(MemoryQueryCompletedEvent)
|
||||
def on_done(source, event):
|
||||
if getattr(event, "source_type", None) == "unified_memory":
|
||||
print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms")
|
||||
```
|
||||
|
||||
|
||||
## 문제 해결
|
||||
|
||||
**메모리가 유지되지 않나요?**
|
||||
- 저장 경로에 쓰기 권한이 있는지 확인하세요(기본값 `./.crewai/memory`). 다른 디렉터리를 사용하려면 `storage="./your_path"`를 전달하거나 `CREWAI_STORAGE_DIR` 환경 변수를 설정하세요.
|
||||
- crew 사용 시 `memory=True` 또는 `memory=Memory(...)`가 설정되었는지 확인하세요.
|
||||
|
||||
**recall이 느린가요?**
|
||||
- 일상적인 에이전트 컨텍스트에는 `depth="shallow"`를 사용하세요. 복잡한 쿼리에만 `depth="deep"`을 사용하세요.
|
||||
- 더 많은 쿼리에서 LLM 분석을 건너뛰려면 `query_analysis_threshold`를 높이세요.
|
||||
|
||||
**로그에 LLM 분석 오류가 있나요?**
|
||||
- 메모리는 안전한 기본값으로 계속 저장/recall합니다. 전체 LLM 분석을 원하면 API 키, 속도 제한, 모델 가용성을 확인하세요.
|
||||
|
||||
**로그에 백그라운드 저장 오류가 있나요?**
|
||||
- 메모리 저장은 백그라운드 스레드에서 실행됩니다. 오류는 `MemorySaveFailedEvent`로 발생하지만 에이전트를 중단시키지 않습니다. 근본 원인(보통 LLM 또는 embedder 연결 문제)은 로그를 확인하세요.
|
||||
|
||||
**동시 쓰기 충돌이 있나요?**
|
||||
- LanceDB 연산은 공유 잠금으로 직렬화되며 충돌 시 자동으로 재시도됩니다. 이는 동일 데이터베이스를 가리키는 여러 `Memory` 인스턴스(예: 에이전트 메모리 + crew 메모리)를 처리합니다. 별도의 조치가 필요하지 않습니다.
|
||||
|
||||
**터미널에서 메모리 탐색:**
|
||||
```bash
|
||||
crewai memory # TUI 브라우저 열기
|
||||
crewai memory --storage-path ./my_memory # 특정 디렉터리 지정
|
||||
```
|
||||
|
||||
**메모리 초기화(예: 테스트용):**
|
||||
```python
|
||||
crew.reset_memories(command_type="memory") # 통합 메모리 초기화
|
||||
# 또는 Memory 인스턴스에서:
|
||||
memory.reset() # 모든 scope
|
||||
memory.reset(scope="/project/old") # 해당 하위 트리만
|
||||
```
|
||||
|
||||
|
||||
## 설정 참조
|
||||
|
||||
모든 설정은 `Memory(...)`에 키워드 인수로 전달됩니다. 모든 매개변수에는 합리적인 기본값이 있습니다.
|
||||
|
||||
| 매개변수 | 기본값 | 설명 |
|
||||
| :--- | :--- | :--- |
|
||||
| `llm` | `"gpt-4o-mini"` | 분석용 LLM (모델 이름 또는 `BaseLLM` 인스턴스). |
|
||||
| `storage` | `"lancedb"` | 스토리지 백엔드 (`"lancedb"`, 경로 문자열 또는 `StorageBackend` 인스턴스). |
|
||||
| `embedder` | `None` (OpenAI 기본값) | Embedder (설정 dict, callable 또는 `None`으로 기본 OpenAI). |
|
||||
| `recency_weight` | `0.3` | 복합 점수에서 최신성 가중치. |
|
||||
| `semantic_weight` | `0.5` | 복합 점수에서 의미 유사도 가중치. |
|
||||
| `importance_weight` | `0.2` | 복합 점수에서 중요도 가중치. |
|
||||
| `recency_half_life_days` | `30` | 최신성 점수가 절반으로 줄어드는 일수(지수 감쇠). |
|
||||
| `consolidation_threshold` | `0.85` | 저장 시 통합이 트리거되는 유사도. `1.0`으로 설정하면 비활성화. |
|
||||
| `consolidation_limit` | `5` | 통합 중 비교할 기존 레코드 최대 수. |
|
||||
| `default_importance` | `0.5` | 미제공 시 및 LLM 분석이 생략될 때 할당되는 중요도. |
|
||||
| `batch_dedup_threshold` | `0.98` | `remember_many()` 배치 내 거의 중복 삭제를 위한 코사인 유사도. |
|
||||
| `confidence_threshold_high` | `0.8` | recall 신뢰도가 이 값 이상이면 결과를 직접 반환. |
|
||||
| `confidence_threshold_low` | `0.5` | recall 신뢰도가 이 값 미만이면 더 깊은 탐색 트리거. |
|
||||
| `complex_query_threshold` | `0.7` | 복잡한 쿼리의 경우 이 신뢰도 미만에서 더 깊이 탐색. |
|
||||
| `exploration_budget` | `1` | 딥 recall 중 LLM 기반 탐색 라운드 수. |
|
||||
| `query_analysis_threshold` | `200` | 이 길이(문자 수)보다 짧은 쿼리는 딥 recall 중 LLM 분석을 건너뜀. |
|
||||
153
docs/edge/ko/concepts/planning.mdx
Normal file
153
docs/edge/ko/concepts/planning.mdx
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: 계획
|
||||
description: CrewAI Crew에 계획을 추가하고 성능을 향상시키는 방법을 알아보세요.
|
||||
icon: ruler-combined
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI의 planning 기능을 통해 crew에 계획 수립 기능을 추가할 수 있습니다. 해당 기능을 활성화하면, 각 Crew 반복 전에 모든 Crew 정보가 AgentPlanner로 전송되어 작업이 단계별로 계획되며, 이 계획이 각 작업 설명에 추가됩니다.
|
||||
|
||||
### Planning 기능 사용하기
|
||||
|
||||
Planning 기능을 시작하는 것은 매우 간단합니다. 필요한 유일한 단계는 Crew에 `planning=True`를 추가하는 것입니다:
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
from crewai import Crew, Agent, Task, Process
|
||||
|
||||
# Assemble your crew with planning capabilities
|
||||
my_crew = Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
planning=True,
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
이 시점부터 crew는 planning이 활성화되며, 각 반복 전에 작업이 계획됩니다.
|
||||
|
||||
<Warning>
|
||||
Planning이 활성화되면, crewAI는 planning을 위해 기본 LLM으로 `gpt-4o-mini`를 사용합니다. 이 기능은 유효한 OpenAI API 키가 필요합니다. 에이전트가 서로 다른 LLM을 사용할 수도 있기 때문에, OpenAI API 키가 설정되어 있지 않거나 LLM API 호출과 관련된 예상치 못한 동작이 발생할 경우 혼란을 일으킬 수 있습니다.
|
||||
</Warning>
|
||||
|
||||
#### LLM 계획하기
|
||||
|
||||
이제 작업을 계획할 때 사용할 LLM을 정의할 수 있습니다.
|
||||
|
||||
기본 사례 예제를 실행하면 아래와 같은 출력이 나타나는데, 이는 AgentPlanner의 출력으로, 에이전트 작업에 추가할 단계별 논리를 생성합니다.
|
||||
|
||||
<CodeGroup>
|
||||
```python Code
|
||||
from crewai import Crew, Agent, Task, Process
|
||||
|
||||
# Assemble your crew with planning capabilities and custom LLM
|
||||
my_crew = Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
planning=True,
|
||||
planning_llm="gpt-4o"
|
||||
)
|
||||
|
||||
# Run the crew
|
||||
my_crew.kickoff()
|
||||
```
|
||||
|
||||
```markdown Result
|
||||
[2024-07-15 16:49:11][INFO]: Planning the crew execution
|
||||
**작업 실행을 위한 단계별 계획**
|
||||
|
||||
**작업 번호 1: AI LLM에 대해 철저히 조사하기**
|
||||
|
||||
**에이전트:** AI LLMs 시니어 데이터 리서처
|
||||
|
||||
**에이전트 목표:** AI LLM의 최신 개발 동향 파악
|
||||
|
||||
**작업 예상 결과:** AI LLM에 대한 가장 관련성 높은 정보 10가지가 포함된 리스트
|
||||
|
||||
**작업 도구:** 명시되지 않음
|
||||
|
||||
**에이전트 도구:** 명시되지 않음
|
||||
|
||||
**단계별 계획:**
|
||||
|
||||
1. **조사 범위 정의:**
|
||||
|
||||
- 아키텍처의 발전, 사용 사례, 윤리적 고려사항, 성능 측정 기준 등 AI LLM의 특정 영역을 결정합니다.
|
||||
|
||||
2. **신뢰할 수 있는 출처 식별:**
|
||||
|
||||
- 학술지, 산업 리포트, 컨퍼런스(예: NeurIPS, ACL), AI 연구소(예: OpenAI, Google AI), 온라인 데이터베이스(예: IEEE Xplore, arXiv) 등 AI 연구를 위한 평판 좋은 출처를 나열합니다.
|
||||
|
||||
3. **데이터 수집:**
|
||||
|
||||
- 2024년 및 2025년 초에 발표된 최신 논문, 기사, 리포트를 검색합니다.
|
||||
- "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025"와 같은 키워드를 사용합니다.
|
||||
|
||||
4. **발견 사항 분석:**
|
||||
|
||||
- 각 출처에서 핵심 내용을 읽고 요약합니다.
|
||||
- 지난 1년간 소개된 새로운 기술, 모델, 애플리케이션 등을 강조합니다.
|
||||
|
||||
5. **정보 정리:**
|
||||
|
||||
- 정보를 관련 주제별로 분류합니다(예: 새로운 아키텍처, 윤리적 영향, 실세계 적용 등).
|
||||
- 각 핵심 포인트는 간결하면서도 정보가 풍부하도록 합니다.
|
||||
|
||||
6. **리스트 작성:**
|
||||
|
||||
- 가장 관련성 높은 10가지 정보를 불릿 포인트로 정리합니다.
|
||||
- 리스트가 명확하고 적절한지 검토합니다.
|
||||
|
||||
**예상 결과:**
|
||||
|
||||
AI LLM에 대한 가장 관련성 높은 정보 10가지를 담은 불릿 포인트 리스트.
|
||||
|
||||
---
|
||||
|
||||
**작업 번호 2: 받은 컨텍스트를 검토하고 각 주제를 리포트의 전체 섹션으로 확장하기**
|
||||
|
||||
**에이전트:** AI LLMs 리포팅 애널리스트
|
||||
|
||||
**에이전트 목표:** AI LLM 데이터 분석 및 연구 결과를 기반으로 상세 리포트를 작성
|
||||
|
||||
**작업 예상 결과:** 주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이)
|
||||
|
||||
**작업 도구:** 명시되지 않음
|
||||
|
||||
**에이전트 도구:** 명시되지 않음
|
||||
|
||||
**단계별 계획:**
|
||||
|
||||
1. **불릿 포인트 검토:**
|
||||
- AI LLMs 시니어 데이터 리서처가 제공한 10가지 불릿 포인트 리스트를 꼼꼼히 읽습니다.
|
||||
|
||||
2. **리포트 개요 작성:**
|
||||
- 각 불릿 포인트를 주요 섹션 제목으로 삼아 개요를 만듭니다.
|
||||
- 각 주요 제목 아래 하위 섹션을 기획하여 해당 주제의 다양한 측면을 다룹니다.
|
||||
|
||||
3. **추가 세부 사항 조사:**
|
||||
- 각 불릿 포인트별로, 더 자세한 정보를 수집하기 위해 필요 시 추가 조사를 진행합니다.
|
||||
- 각 섹션을 뒷받침할 사례 연구, 예시, 통계자료 등을 찾습니다.
|
||||
|
||||
4. **상세 섹션 작성:**
|
||||
- 각 불릿 포인트를 포괄적인 섹션으로 확장합니다.
|
||||
- 각 섹션에는 도입, 상세 설명, 예시, 결론이 포함되어야 합니다.
|
||||
- 제목, 부제목, 리스트, 강조 등 마크다운 포맷을 사용합니다.
|
||||
|
||||
5. **검토 및 편집:**
|
||||
- 리포트의 명확성, 일관성, 정확성을 위해 교정합니다.
|
||||
- 리포트가 각 섹션에서 논리적으로 자연스럽게 흐르는지 확인합니다.
|
||||
- 마크다운 기준에 맞게 포맷을 맞춥니다.
|
||||
|
||||
6. **리포트 최종화:**
|
||||
- 모든 섹션이 확장되고 상세하게 작성되어 완전한 리포트가 되었는지 확인합니다.
|
||||
- 포맷을 다시 확인하고 필요한 경우 수정합니다.
|
||||
|
||||
**예상 결과:**
|
||||
주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이).
|
||||
```
|
||||
</CodeGroup>
|
||||
66
docs/edge/ko/concepts/processes.mdx
Normal file
66
docs/edge/ko/concepts/processes.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 프로세스
|
||||
description: CrewAI에서 프로세스를 통한 워크플로우 관리에 대한 상세 가이드와 최신 구현 세부 사항.
|
||||
icon: bars-staggered
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
<Tip>
|
||||
프로세스는 에이전트에 의해 작업이 실행되도록 조정하며, 이는 인간 팀에서의 프로젝트 관리와 유사합니다.
|
||||
이러한 프로세스는 작업이 미리 정의된 전략에 따라 효율적으로 분배되고 실행되도록 보장합니다.
|
||||
</Tip>
|
||||
|
||||
## 프로세스 구현
|
||||
|
||||
- **순차적(Sequential)**: 작업을 순차적으로 실행하여 작업이 질서 있게 진행되도록 보장합니다.
|
||||
- **계층적(Hierarchical)**: 작업을 관리 계층 구조로 조직하며, 작업은 체계적인 명령 체계를 기반으로 위임 및 실행됩니다. 계층적 프로세스를 활성화하려면 매니저 언어 모델(`manager_llm`) 또는 커스텀 매니저 에이전트(`manager_agent`)를 crew에서 지정해야 하며, 이를 통해 매니저가 작업을 생성하고 관리할 수 있도록 지원합니다.
|
||||
|
||||
## 팀워크에서 프로세스의 역할
|
||||
프로세스는 개별 에이전트가 통합된 단위로 작동할 수 있도록 하여, 공통된 목표를 효율적이고 일관성 있게 달성하도록 노력하는 과정을 간소화합니다.
|
||||
|
||||
## 프로세스를 Crew에 할당하기
|
||||
프로세스를 crew에 할당하려면, crew 생성 시 프로세스 유형을 지정하여 실행 전략을 설정합니다. 계층적 프로세스의 경우, 매니저 에이전트에 대해 `manager_llm` 또는 `manager_agent`를 반드시 정의해야 합니다.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Example: Creating a crew with a sequential process
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
# Example: Creating a crew with a hierarchical process
|
||||
# Ensure to provide a manager_llm or manager_agent
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.hierarchical,
|
||||
manager_llm="gpt-4o"
|
||||
# or
|
||||
# manager_agent=my_manager_agent
|
||||
)
|
||||
```
|
||||
**참고:** `Crew` 객체를 생성하기 전에 반드시 `my_agents`와 `my_tasks`가 정의되어 있어야 하며, 계층적 프로세스의 경우 `manager_llm` 또는 `manager_agent` 중 하나도 필요합니다.
|
||||
|
||||
## 순차적 프로세스
|
||||
|
||||
이 방법은 동적인 팀 워크플로우를 반영하며, 작업을 신중하고 체계적으로 진행합니다. 작업 수행은 작업 목록에 정의된 순서를 따르며, 한 작업의 출력이 다음 작업의 컨텍스트로 사용됩니다.
|
||||
|
||||
작업 컨텍스트를 사용자 지정하려면, `Task` 클래스의 `context` 매개변수를 사용하여 이후 작업에 컨텍스트로 사용될 출력을 지정하세요.
|
||||
|
||||
## 계층적 프로세스
|
||||
|
||||
기업의 계층 구조를 모방하는 CrewAI는 사용자 지정 관리자 에이전트를 지정하거나 자동으로 생성할 수 있으며, 이때 관리자 언어 모델(`manager_llm`)의 지정을 요구합니다. 이 에이전트는 계획 수립, 위임, 검증 등 작업 실행을 감독합니다. 작업은 미리 할당되지 않으며, 관리자가 에이전트의 역량에 따라 작업을 분배하고, 산출물을 검토하며, 작업 완료 여부를 평가합니다.
|
||||
|
||||
## Process 클래스: 상세 개요
|
||||
|
||||
`Process` 클래스는 열거형(`Enum`)으로 구현되어 타입 안전성을 보장하며, 프로세스 값을 정의된 타입(`sequential`, `hierarchical`)으로 제한합니다.
|
||||
|
||||
## 결론
|
||||
|
||||
CrewAI 내의 프로세스를 통해 촉진되는 구조화된 협업은 에이전트 간 체계적인 팀워크를 가능하게 하는 데 매우 중요합니다.
|
||||
이 문서는 최신 기능과 향상 사항을 반영하도록 업데이트되었으며, 사용자가 가장 최신이고 포괄적인 정보를 이용할 수 있도록 보장합니다.
|
||||
162
docs/edge/ko/concepts/production-architecture.mdx
Normal file
162
docs/edge/ko/concepts/production-architecture.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: 프로덕션 아키텍처
|
||||
description: CrewAI로 프로덕션 수준의 AI 애플리케이션을 구축하기 위한 모범 사례
|
||||
icon: server
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# Flow 우선 사고방식 (Flow-First Mindset)
|
||||
|
||||
CrewAI로 프로덕션 AI 애플리케이션을 구축할 때는 **Flow로 시작하는 것을 권장합니다**.
|
||||
|
||||
개별 Crews나 Agents를 실행하는 것도 가능하지만, 이를 Flow로 감싸면 견고하고 확장 가능한 애플리케이션에 필요한 구조를 제공합니다.
|
||||
|
||||
## 왜 Flows인가?
|
||||
|
||||
1. **상태 관리 (State Management)**: Flows는 애플리케이션의 여러 단계에 걸쳐 상태를 관리하는 내장된 방법을 제공합니다. 이는 Crews 간에 데이터를 전달하고, 컨텍스트를 유지하며, 사용자 입력을 처리하는 데 중요합니다.
|
||||
2. **제어 (Control)**: Flows를 사용하면 루프, 조건문, 분기 로직을 포함한 정확한 실행 경로를 정의할 수 있습니다. 이는 예외 상황을 처리하고 애플리케이션이 예측 가능하게 동작하도록 보장하는 데 필수적입니다.
|
||||
3. **관측 가능성 (Observability)**: Flows는 실행을 추적하고, 문제를 디버깅하며, 성능을 모니터링하기 쉽게 만드는 명확한 구조를 제공합니다. 자세한 통찰력을 얻으려면 [CrewAI Tracing](/ko/observability/tracing)을 사용하는 것이 좋습니다. `crewai login`을 실행하여 무료 관측 가능성 기능을 활성화하세요.
|
||||
|
||||
## 아키텍처
|
||||
|
||||
일반적인 프로덕션 CrewAI 애플리케이션은 다음과 같습니다:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start((시작)) --> Flow[Flow 오케스트레이터]
|
||||
Flow --> State{상태 관리}
|
||||
State --> Step1[1단계: 데이터 수집]
|
||||
Step1 --> Crew1[연구 Crew]
|
||||
Crew1 --> State
|
||||
State --> Step2{조건 확인}
|
||||
Step2 -- "유효함" --> Step3[3단계: 실행]
|
||||
Step3 --> Crew2[액션 Crew]
|
||||
Step2 -- "유효하지 않음" --> End((종료))
|
||||
Crew2 --> End
|
||||
```
|
||||
|
||||
### 1. Flow 클래스
|
||||
`Flow` 클래스는 진입점입니다. 상태 스키마와 로직을 실행하는 메서드를 정의합니다.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AppState(BaseModel):
|
||||
user_input: str = ""
|
||||
research_results: str = ""
|
||||
final_report: str = ""
|
||||
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
@start()
|
||||
def gather_input(self):
|
||||
# ... 입력 받는 로직 ...
|
||||
pass
|
||||
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
# ... Crew 트리거 ...
|
||||
pass
|
||||
```
|
||||
|
||||
### 2. 상태 관리 (State Management)
|
||||
Pydantic 모델을 사용하여 상태를 정의하세요. 이는 타입 안전성을 보장하고 각 단계에서 어떤 데이터를 사용할 수 있는지 명확하게 합니다.
|
||||
|
||||
- **최소한으로 유지**: 단계 간에 유지해야 할 것만 저장하세요.
|
||||
- **구조화된 데이터 사용**: 가능하면 비구조화된 딕셔너리는 피하세요.
|
||||
|
||||
### 3. 작업 단위로서의 Crews
|
||||
복잡한 작업은 Crews에게 위임하세요. Crew는 특정 목표(예: "주제 연구", "블로그 게시물 작성")에 집중해야 합니다.
|
||||
|
||||
- **Crews를 과도하게 설계하지 마세요**: 집중력을 유지하세요.
|
||||
- **상태를 명시적으로 전달하세요**: Flow 상태에서 필요한 데이터를 Crew 입력으로 전달하세요.
|
||||
|
||||
```python
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
crew = ResearchCrew()
|
||||
result = crew.kickoff(inputs={"topic": self.state.user_input})
|
||||
self.state.research_results = result.raw
|
||||
```
|
||||
|
||||
## Control Primitives
|
||||
|
||||
CrewAI의 Control Primitives를 활용하여 Crew에 견고함과 제어력을 더하세요.
|
||||
|
||||
### 1. Task Guardrails
|
||||
[Task Guardrails](/ko/concepts/tasks#task-guardrails)를 사용하여 작업 결과가 수락되기 전에 유효성을 검사하세요. 이를 통해 agent가 고품질 결과를 생성하도록 보장할 수 있습니다.
|
||||
|
||||
```python
|
||||
def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
if len(result.raw) < 100:
|
||||
return (False, "Content is too short. Please expand.")
|
||||
return (True, result.raw)
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
guardrail=validate_content
|
||||
)
|
||||
```
|
||||
|
||||
### 2. 구조화된 출력 (Structured Outputs)
|
||||
작업 간에 데이터를 전달하거나 애플리케이션으로 전달할 때는 항상 구조화된 출력(`output_pydantic` 또는 `output_json`)을 사용하세요. 이는 파싱 오류를 방지하고 타입 안전성을 보장합니다.
|
||||
|
||||
```python
|
||||
class ResearchResult(BaseModel):
|
||||
summary: str
|
||||
sources: List[str]
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
output_pydantic=ResearchResult
|
||||
)
|
||||
```
|
||||
|
||||
### 3. LLM Hooks
|
||||
[LLM Hooks](/ko/learn/llm-hooks)를 사용하여 LLM으로 전송되기 전에 메시지를 검사하거나 수정하고, 응답을 정리(sanitize)하세요.
|
||||
|
||||
```python
|
||||
@before_llm_call
|
||||
def log_request(context):
|
||||
print(f"Agent {context.agent.role} is calling the LLM...")
|
||||
```
|
||||
|
||||
## 배포 패턴
|
||||
|
||||
Flow를 배포할 때 다음을 고려하세요:
|
||||
|
||||
### CrewAI Enterprise
|
||||
Flow를 배포하는 가장 쉬운 방법은 CrewAI Enterprise를 사용하는 것입니다. 인프라, 인증 및 모니터링을 대신 처리합니다.
|
||||
|
||||
시작하려면 [배포 가이드](/ko/enterprise/guides/deploy-to-amp)를 확인하세요.
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
|
||||
### 비동기 실행 (Async Execution)
|
||||
장기 실행 작업의 경우 `kickoff_async`를 사용하여 API 차단을 방지하세요.
|
||||
|
||||
### 지속성 (Persistence)
|
||||
`@persist` 데코레이터를 사용하여 Flow의 상태를 데이터베이스에 저장하세요. 이를 통해 프로세스가 중단되거나 사람의 입력을 기다려야 할 때 실행을 재개할 수 있습니다.
|
||||
|
||||
```python
|
||||
@persist
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
# ...
|
||||
```
|
||||
|
||||
기본적으로, `@persist`는 `kickoff(inputs={"id": <uuid>})`가 제공될 때 플로우를 재개하여 동일한 `flow_uuid` 기록을 확장합니다. 영속된 플로우를 새 계보로 **포크**하려면 — 이전 실행에서 상태를 하이드레이트하지만 새로운 `state.id` 아래에 기록 — `restore_from_state_id`를 전달하세요:
|
||||
|
||||
```python
|
||||
flow.kickoff(restore_from_state_id="<previous-run-state-id>")
|
||||
```
|
||||
|
||||
새 실행은 새로운 `state.id`(자동 생성, 또는 `inputs["id"]`가 고정된 경우 그 값)를 받아 `@persist` 기록이 원본의 기록을 확장하지 않도록 합니다. `from_checkpoint`와 결합하면 `ValueError`가 발생합니다; 하나의 하이드레이션 소스를 선택하세요.
|
||||
|
||||
## 요약
|
||||
|
||||
- **Flow로 시작하세요.**
|
||||
- **명확한 State를 정의하세요.**
|
||||
- **복잡한 작업에는 Crews를 사용하세요.**
|
||||
- **API와 지속성을 갖추어 배포하세요.**
|
||||
148
docs/edge/ko/concepts/reasoning.mdx
Normal file
148
docs/edge/ko/concepts/reasoning.mdx
Normal file
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: Reasoning
|
||||
description: "에이전트 reasoning을 활성화하고 사용하는 방법을 배워 작업 실행을 향상하세요."
|
||||
icon: brain
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Agent reasoning은 에이전트가 작업을 수행하기 전에 해당 작업을 반성하고 계획을 수립할 수 있도록 해주는 기능입니다. 이를 통해 에이전트는 작업에 더 체계적으로 접근할 수 있으며, 할당된 업무를 수행할 준비가 되었는지 확인할 수 있습니다.
|
||||
|
||||
## 사용 방법
|
||||
|
||||
에이전트에 reasoning을 활성화하려면 에이전트를 생성할 때 `reasoning=True`로 설정하면 됩니다.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze complex datasets and provide insights",
|
||||
backstory="You are an experienced data analyst with expertise in finding patterns in complex data.",
|
||||
reasoning=True, # Enable reasoning
|
||||
max_reasoning_attempts=3 # Optional: Set a maximum number of reasoning attempts
|
||||
)
|
||||
```
|
||||
|
||||
## 작동 방식
|
||||
|
||||
reasoning이 활성화되면, 작업을 실행하기 전에 에이전트는 다음을 수행합니다:
|
||||
|
||||
1. 작업을 반영하고 상세한 계획을 수립합니다.
|
||||
2. 작업을 실행할 준비가 되었는지 평가합니다.
|
||||
3. 준비가 완료되거나 max_reasoning_attempts에 도달할 때까지 필요에 따라 계획을 다듬습니다.
|
||||
4. reasoning 계획을 실행 전에 작업 설명에 삽입합니다.
|
||||
|
||||
이 프로세스는 에이전트가 복잡한 작업을 관리하기 쉬운 단계로 분해하고, 시작하기 전에 잠재적인 문제를 식별하는 데 도움을 줍니다.
|
||||
|
||||
## 구성 옵션
|
||||
|
||||
<ParamField body="reasoning" type="bool" default="False">
|
||||
reasoning 활성화 또는 비활성화
|
||||
</ParamField>
|
||||
|
||||
<ParamField body="max_reasoning_attempts" type="int" default="None">
|
||||
실행을 진행하기 전에 계획을 개선할 최대 시도 횟수입니다. None(기본값)인 경우, agent는 준비될 때까지 계속해서 개선을 시도합니다.
|
||||
</ParamField>
|
||||
|
||||
## 예제
|
||||
|
||||
다음은 전체 예제입니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with reasoning enabled
|
||||
analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data and provide insights",
|
||||
backstory="You are an expert data analyst.",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3 # Optional: Set a limit on reasoning attempts
|
||||
)
|
||||
|
||||
# Create a task
|
||||
analysis_task = Task(
|
||||
description="Analyze the provided sales data and identify key trends.",
|
||||
expected_output="A report highlighting the top 3 sales trends.",
|
||||
agent=analyst
|
||||
)
|
||||
|
||||
# Create a crew and run the task
|
||||
crew = Crew(agents=[analyst], tasks=[analysis_task])
|
||||
result = crew.kickoff()
|
||||
|
||||
print(result)
|
||||
```
|
||||
|
||||
## 오류 처리
|
||||
|
||||
reasoning 프로세스는 견고하게 설계되어 있으며, 오류 처리가 내장되어 있습니다. reasoning 중에 오류가 발생하면, 에이전트는 reasoning 계획 없이 작업을 계속 실행합니다. 이는 reasoning 프로세스가 실패하더라도 작업이 계속 실행될 수 있도록 보장합니다.
|
||||
|
||||
코드에서 발생할 수 있는 오류를 처리하는 방법은 다음과 같습니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task
|
||||
import logging
|
||||
|
||||
# reasoning 오류를 캡처하기 위해 로깅을 설정합니다
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
# reasoning이 활성화된 에이전트를 생성합니다
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data and provide insights",
|
||||
reasoning=True,
|
||||
max_reasoning_attempts=3
|
||||
)
|
||||
|
||||
# 작업을 생성합니다
|
||||
task = Task(
|
||||
description="Analyze the provided sales data and identify key trends.",
|
||||
expected_output="A report highlighting the top 3 sales trends.",
|
||||
agent=agent
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
# reasoning 중 오류가 발생해도 로그에 기록되며 실행은 계속됩니다
|
||||
result = agent.execute_task(task)
|
||||
```
|
||||
|
||||
## 예시 Reasoning 출력
|
||||
|
||||
다음은 데이터 분석 작업을 위한 reasoning 계획의 예시입니다:
|
||||
|
||||
```
|
||||
Task: Analyze the provided sales data and identify key trends.
|
||||
|
||||
Reasoning Plan:
|
||||
I'll analyze the sales data to identify the top 3 trends.
|
||||
|
||||
1. Understanding of the task:
|
||||
I need to analyze sales data to identify key trends that would be valuable for business decision-making.
|
||||
|
||||
2. Key steps I'll take:
|
||||
- First, I'll examine the data structure to understand what fields are available
|
||||
- Then I'll perform exploratory data analysis to identify patterns
|
||||
- Next, I'll analyze sales by time periods to identify temporal trends
|
||||
- I'll also analyze sales by product categories and customer segments
|
||||
- Finally, I'll identify the top 3 most significant trends
|
||||
|
||||
3. Approach to challenges:
|
||||
- If the data has missing values, I'll decide whether to fill or filter them
|
||||
- If the data has outliers, I'll investigate whether they're valid data points or errors
|
||||
- If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns
|
||||
|
||||
4. Use of available tools:
|
||||
- I'll use data analysis tools to explore and visualize the data
|
||||
- I'll use statistical tools to identify significant patterns
|
||||
- I'll use knowledge retrieval to access relevant information about sales analysis
|
||||
|
||||
5. Expected outcome:
|
||||
A concise report highlighting the top 3 sales trends with supporting evidence from the data.
|
||||
|
||||
READY: I am ready to execute the task.
|
||||
```
|
||||
|
||||
이 reasoning 계획은 agent가 작업에 접근하는 방식을 체계적으로 구성하고, 발생할 수 있는 잠재적 문제를 고려하며, 기대되는 결과를 제공하도록 돕습니다.
|
||||
306
docs/edge/ko/concepts/skills.mdx
Normal file
306
docs/edge/ko/concepts/skills.mdx
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
title: 스킬
|
||||
description: 에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지.
|
||||
icon: bolt
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
스킬은 에이전트에게 **도메인별 지침, 가이드라인 및 참조 자료**를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다.
|
||||
|
||||
활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다.
|
||||
|
||||
<Note type="info" title="스킬 vs 도구 — 핵심 구분">
|
||||
**스킬은 도구가 아닙니다.** 이것이 가장 흔한 혼동 포인트입니다.
|
||||
|
||||
- **스킬**은 에이전트의 프롬프트에 *지침과 컨텍스트*를 주입합니다. 에이전트에게 문제에 대해 *어떻게 생각할지*를 알려줍니다.
|
||||
- **도구**는 에이전트에게 행동을 취할 수 있는 *호출 가능한 함수*를 제공합니다 (검색, 파일 읽기, API 호출).
|
||||
|
||||
흔히 **둘 다** 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
### 1. 스킬 디렉터리 생성
|
||||
|
||||
```
|
||||
skills/
|
||||
└── code-review/
|
||||
├── SKILL.md # 필수 — 지침
|
||||
├── references/ # 선택 — 참조 문서
|
||||
│ └── style-guide.md
|
||||
└── scripts/ # 선택 — 실행 가능한 스크립트
|
||||
```
|
||||
|
||||
### 2. SKILL.md 작성
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-review
|
||||
description: Guidelines for conducting thorough code reviews with focus on security and performance.
|
||||
metadata:
|
||||
author: your-team
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
## 코드 리뷰 가이드라인
|
||||
|
||||
코드를 리뷰할 때 이 체크리스트를 따르세요:
|
||||
|
||||
1. **보안**: 인젝션 취약점, 인증 우회, 데이터 노출 확인
|
||||
2. **성능**: N+1 쿼리, 불필요한 할당, 블로킹 호출 확인
|
||||
3. **가독성**: 명확한 네이밍, 적절한 주석, 일관된 스타일 보장
|
||||
4. **테스트**: 새로운 기능에 대한 적절한 테스트 커버리지 확인
|
||||
|
||||
### 심각도 수준
|
||||
- **크리티컬**: 보안 취약점, 데이터 손실 위험 → 머지 차단
|
||||
- **메이저**: 성능 문제, 로직 오류 → 변경 요청
|
||||
- **마이너**: 스타일 문제, 네이밍 제안 → 코멘트와 함께 승인
|
||||
```
|
||||
|
||||
### 3. 에이전트에 연결
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import GithubSearchTool, FileReadTool
|
||||
|
||||
reviewer = Agent(
|
||||
role="Senior Code Reviewer",
|
||||
goal="Review pull requests for quality and security issues",
|
||||
backstory="Staff engineer with expertise in secure coding practices.",
|
||||
skills=["./skills"], # 리뷰 가이드라인 주입
|
||||
tools=[GithubSearchTool(), FileReadTool()], # 에이전트가 코드를 읽을 수 있게 함
|
||||
)
|
||||
```
|
||||
|
||||
이제 에이전트는 **전문성** (스킬에서)과 **기능** (도구에서) 모두를 갖추게 됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 스킬 + 도구: 함께 작동하기
|
||||
|
||||
스킬과 도구가 어떻게 보완하는지 보여주는 일반적인 패턴입니다:
|
||||
|
||||
### 패턴 1: 스킬만 (도메인 전문성, 액션 불필요)
|
||||
|
||||
에이전트가 특정 지침이 필요하지만 외부 서비스를 호출할 필요가 없을 때 사용:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Technical Writer",
|
||||
goal="Write clear API documentation",
|
||||
backstory="Expert technical writer",
|
||||
skills=["./skills/api-docs-style"], # 작성 가이드라인 및 템플릿
|
||||
# 도구 불필요 — 에이전트가 제공된 컨텍스트를 기반으로 작성
|
||||
)
|
||||
```
|
||||
|
||||
### 패턴 2: 도구만 (액션, 특별한 전문성 불필요)
|
||||
|
||||
에이전트가 행동을 취해야 하지만 도메인별 지침이 필요 없을 때 사용:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, ScrapeWebsiteTool
|
||||
|
||||
agent = Agent(
|
||||
role="Web Researcher",
|
||||
goal="Find information about a topic",
|
||||
backstory="Skilled at finding information online",
|
||||
tools=[SerperDevTool(), ScrapeWebsiteTool()], # 검색 및 스크래핑 가능
|
||||
# 스킬 불필요 — 일반 연구에는 특별한 가이드라인이 필요 없음
|
||||
)
|
||||
```
|
||||
|
||||
### 패턴 3: 스킬 + 도구 (전문성 AND 액션)
|
||||
|
||||
가장 일반적인 실제 패턴. 스킬은 작업에 *어떻게* 접근할지를 제공하고, 도구는 에이전트가 *무엇을* 할 수 있는지를 제공합니다:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
analyst = Agent(
|
||||
role="Security Analyst",
|
||||
goal="Audit infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security and compliance",
|
||||
skills=["./skills/security-audit"], # 감사 방법론 및 체크리스트
|
||||
tools=[
|
||||
SerperDevTool(), # 알려진 취약점 조사
|
||||
FileReadTool(), # 설정 파일 읽기
|
||||
CodeInterpreterTool(), # 분석 스크립트 실행
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
### 패턴 4: 스킬 + MCP
|
||||
|
||||
스킬은 도구와 마찬가지로 MCP 서버와 함께 작동합니다:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze customer data and generate reports",
|
||||
backstory="Expert data analyst with strong statistical background",
|
||||
skills=["./skills/data-analysis"], # 분석 방법론
|
||||
mcps=["https://data-warehouse.example.com/sse"], # 원격 데이터 접근
|
||||
)
|
||||
```
|
||||
|
||||
### 패턴 5: 스킬 + 앱
|
||||
|
||||
스킬은 에이전트가 플랫폼 통합을 사용하는 방법을 안내할 수 있습니다:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Customer Support Agent",
|
||||
goal="Respond to customer inquiries professionally",
|
||||
backstory="Experienced support representative",
|
||||
skills=["./skills/support-playbook"], # 응답 템플릿 및 에스컬레이션 규칙
|
||||
apps=["gmail", "zendesk"], # 이메일 전송 및 티켓 업데이트 가능
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 크루 레벨 스킬
|
||||
|
||||
스킬을 크루에 설정하여 **모든 에이전트**에 적용할 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, reviewer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
skills=["./skills"], # 모든 에이전트가 이 스킬을 받음
|
||||
)
|
||||
```
|
||||
|
||||
에이전트 레벨 스킬이 우선합니다 — 동일한 스킬이 양쪽 레벨에서 발견되면 에이전트의 버전이 사용됩니다.
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md 형식
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: 이 스킬이 무엇을 하고 언제 사용하는지에 대한 간단한 설명.
|
||||
license: Apache-2.0 # 선택
|
||||
compatibility: crewai>=0.1.0 # 선택
|
||||
metadata: # 선택
|
||||
author: your-name
|
||||
version: "1.0"
|
||||
allowed-tools: web-search file-read # 선택, 실험적
|
||||
---
|
||||
|
||||
에이전트를 위한 지침이 여기에 들어갑니다. 이 마크다운 본문은
|
||||
스킬이 활성화되면 에이전트의 프롬프트에 주입됩니다.
|
||||
```
|
||||
|
||||
### 프론트매터 필드
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
| :-------------- | :----- | :----------------------------------------------------------------------- |
|
||||
| `name` | 예 | 1–64자. 소문자 영숫자와 하이픈. 디렉터리 이름과 일치 필수. |
|
||||
| `description` | 예 | 1–1024자. 스킬이 무엇을 하고 언제 사용하는지 설명. |
|
||||
| `license` | 아니오 | 라이선스 이름 또는 번들된 라이선스 파일 참조. |
|
||||
| `compatibility` | 아니오 | 최대 500자. 환경 요구 사항 (제품, 패키지, 네트워크). |
|
||||
| `metadata` | 아니오 | 임의의 문자열 키-값 매핑. |
|
||||
| `allowed-tools` | 아니오 | 공백으로 구분된 사전 승인 도구 목록. 실험적. |
|
||||
|
||||
---
|
||||
|
||||
## 디렉터리 구조
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # 필수 — 프론트매터 + 지침
|
||||
├── scripts/ # 선택 — 실행 가능한 스크립트
|
||||
├── references/ # 선택 — 참조 문서
|
||||
└── assets/ # 선택 — 정적 파일 (설정, 데이터)
|
||||
```
|
||||
|
||||
디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 사전 로드된 스킬
|
||||
|
||||
더 세밀한 제어를 위해 프로그래밍 방식으로 스킬을 검색하고 활성화할 수 있습니다:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
from crewai.skills import discover_skills, activate_skill
|
||||
|
||||
# 디렉터리의 모든 스킬 검색
|
||||
skills = discover_skills(Path("./skills"))
|
||||
|
||||
# 활성화 (전체 SKILL.md 본문 로드)
|
||||
activated = [activate_skill(s) for s in skills]
|
||||
|
||||
# 에이전트에 전달
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find relevant information",
|
||||
backstory="An expert researcher.",
|
||||
skills=activated,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 스킬 로드 방식
|
||||
|
||||
스킬은 **점진적 공개**를 사용합니다 — 각 단계에서 필요한 것만 로드합니다:
|
||||
|
||||
| 단계 | 로드되는 내용 | 시점 |
|
||||
| :------- | :------------------------------------ | :------------------ |
|
||||
| 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` |
|
||||
| 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` |
|
||||
|
||||
일반적인 에이전트 실행 중(`skills=["./skills"]`로 디렉터리 경로 전달 시) 스킬은 자동으로 검색되고 활성화됩니다. 점진적 로딩은 프로그래밍 API를 사용할 때만 관련됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 스킬 vs 지식
|
||||
|
||||
스킬과 지식 모두 에이전트의 프롬프트를 수정하지만, 서로 다른 목적을 가지고 있습니다:
|
||||
|
||||
| 측면 | 스킬 | 지식 |
|
||||
| :--- | :--- | :--- |
|
||||
| **제공하는 것** | 지침, 절차, 가이드라인 | 사실, 데이터, 정보 |
|
||||
| **저장 방식** | 마크다운 파일 (SKILL.md) | 벡터 스토어에 임베딩 (ChromaDB) |
|
||||
| **검색 방식** | 전체 본문이 프롬프트에 주입 | 시맨틱 검색으로 관련 청크 찾기 |
|
||||
| **적합한 용도** | 방법론, 체크리스트, 스타일 가이드 | 회사 문서, 제품 정보, 참조 데이터 |
|
||||
| **설정 방법** | `skills=["./skills"]` | `knowledge_sources=[source]` |
|
||||
|
||||
**경험 법칙:** 에이전트가 *프로세스*를 따라야 하면 스킬을 사용하세요. 에이전트가 *데이터*를 참조해야 하면 지식을 사용하세요.
|
||||
|
||||
---
|
||||
|
||||
## 자주 묻는 질문
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="스킬과 도구를 모두 설정해야 하나요?">
|
||||
사용 사례에 따라 다릅니다. 스킬과 도구는 **독립적**입니다 — 둘 중 하나, 둘 다, 또는 아무것도 사용하지 않을 수 있습니다.
|
||||
|
||||
- **스킬만**: 에이전트가 전문성은 필요하지만 외부 액션이 필요 없을 때 (예: 스타일 가이드라인으로 작성)
|
||||
- **도구만**: 에이전트가 액션은 필요하지만 특별한 방법론이 필요 없을 때 (예: 간단한 웹 검색)
|
||||
- **둘 다**: 에이전트가 전문성 AND 액션이 필요할 때 (예: 특정 체크리스트로 보안 감사 AND 코드 스캔 기능)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="스킬이 자동으로 도구를 제공하나요?">
|
||||
**아니요.** SKILL.md의 `allowed-tools` 필드는 실험적 메타데이터일 뿐 — 도구를 프로비저닝하거나 주입하지 않습니다. 항상 `tools=[]`, `mcps=[]` 또는 `apps=[]`를 통해 별도로 도구를 설정해야 합니다.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="에이전트와 크루 모두에 같은 스킬을 설정하면 어떻게 되나요?">
|
||||
에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SKILL.md 본문의 최대 크기는 얼마인가요?">
|
||||
50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
938
docs/edge/ko/concepts/tasks.mdx
Normal file
938
docs/edge/ko/concepts/tasks.mdx
Normal file
@@ -0,0 +1,938 @@
|
||||
---
|
||||
title: 작업
|
||||
description: CrewAI 프레임워크 내에서 작업을 관리하고 생성하는 방법에 대한 자세한 안내서입니다.
|
||||
icon: list-check
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI 프레임워크에서 `Task`는 `Agent`가 완료하는 구체적인 과제입니다.
|
||||
|
||||
Task는 실행을 위한 모든 세부 정보를 제공합니다. 여기에는 설명, 책임 Agent, 필요한 도구 등이 포함되어 다양한 작업 복잡성을 지원합니다.
|
||||
|
||||
CrewAI 내의 Task는 협업이 가능하며, 여러 Agent가 함께 작업해야 할 수도 있습니다. 이는 Task 속성을 통해 관리되며, Crew의 프로세스를 통해 조율되어 팀워크와 효율성을 향상시킵니다.
|
||||
|
||||
<Note type="info" title="엔터프라이즈 기능: 비주얼 Task 빌더">
|
||||
CrewAI 엔터프라이즈에는 복잡한 Task 생성과 연결을 단순화하는 Crew Studio의 비주얼 Task 빌더가 포함되어 있습니다. Task 흐름을 시각적으로 설계하고, 코드를 작성하지 않고도 실시간으로 테스트해 볼 수 있습니다.
|
||||
|
||||
|
||||
|
||||
비주얼 Task 빌더의 주요 기능:
|
||||
- 드래그 앤 드롭 방식의 Task 생성
|
||||
- 시각적 Task 종속성과 흐름 관리
|
||||
- 실시간 테스트 및 검증
|
||||
- 손쉬운 공유 및 협업
|
||||
</Note>
|
||||
|
||||
### 작업 실행 흐름
|
||||
|
||||
작업은 두 가지 방법으로 실행될 수 있습니다:
|
||||
- **순차적**: 작업이 정의된 순서대로 실행됩니다
|
||||
- **계층적**: 작업이 역할과 전문성에 따라 에이전트에게 할당됩니다
|
||||
|
||||
실행 흐름은 crew를 생성할 때 정의됩니다:
|
||||
```python Code
|
||||
crew = Crew(
|
||||
agents=[agent1, agent2],
|
||||
tasks=[task1, task2],
|
||||
process=Process.sequential # or Process.hierarchical
|
||||
)
|
||||
```
|
||||
|
||||
## 태스크 속성
|
||||
|
||||
| 속성 | 매개변수 | 타입 | 설명 |
|
||||
| :------------------------------- | :-------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------ |
|
||||
| **설명** | `description` | `str` | 태스크가 다루는 내용을 명확하고 간결하게 설명합니다. |
|
||||
| **예상 출력** | `expected_output` | `str` | 태스크가 완료된 모습에 대한 구체적인 설명입니다. |
|
||||
| **이름** _(선택 사항)_ | `name` | `Optional[str]` | 태스크의 이름 식별자입니다. |
|
||||
| **에이전트** _(선택 사항)_ | `agent` | `Optional[BaseAgent]` | 태스크 실행을 담당하는 에이전트입니다. |
|
||||
| **도구** _(선택 사항)_ | `tools` | `List[BaseTool]` | 이 태스크를 위해 에이전트가 사용할 수 있는 도구/리소스 목록입니다. |
|
||||
| **컨텍스트** _(선택 사항)_ | `context` | `Optional[List["Task"]]` | 이 태스크의 컨텍스트로 사용될 다른 태스크의 출력입니다. |
|
||||
| **비동기 실행** _(선택 사항)_ | `async_execution` | `Optional[bool]` | 태스크를 비동기적으로 실행할지 여부입니다. 기본값은 False입니다. |
|
||||
| **사용자 입력** _(선택 사항)_ | `human_input` | `Optional[bool]` | 태스크의 최종 답안을 에이전트가 제출한 뒤 사람이 검토할지 여부입니다. 기본값은 False입니다. |
|
||||
| **마크다운** _(선택 사항)_ | `markdown` | `Optional[bool]` | 태스크가 에이전트에게 최종 답안을 마크다운으로 포매팅해서 반환하도록 지시할지 여부입니다. 기본값은 False입니다. |
|
||||
| **설정** _(선택 사항)_ | `config` | `Optional[Dict[str, Any]]` | 태스크별 설정 파라미터입니다. |
|
||||
| **출력 파일** _(선택 사항)_ | `output_file` | `Optional[str]` | 태스크 결과를 저장할 파일 경로입니다. |
|
||||
| **디렉터리 생성** _(선택 사항)_ | `create_directory` | `Optional[bool]` | output_file의 디렉터리가 존재하지 않을 경우 생성할지 여부입니다. 기본값은 True입니다. |
|
||||
| **출력 JSON** _(선택 사항)_ | `output_json` | `Optional[Type[BaseModel]]` | JSON 출력을 구조화하기 위한 Pydantic 모델입니다. |
|
||||
| **Pydantic 출력** _(선택 사항)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | 태스크 출력용 Pydantic 모델입니다. |
|
||||
| **콜백** _(선택 사항)_ | `callback` | `Optional[Any]` | 태스크 완료 후 실행할 함수/객체입니다. |
|
||||
| **가드레일** _(선택 사항)_ | `guardrail` | `Optional[Callable]` | 다음 태스크로 진행하기 전에 태스크 출력을 검증하는 함수입니다. |
|
||||
| **가드레일 최대 재시도** _(선택 사항)_ | `guardrail_max_retries` | `Optional[int]` | 가드레일 검증 실패 시 최대 재시도 횟수입니다. 기본값은 3입니다. |
|
||||
|
||||
## 작업 생성하기
|
||||
|
||||
CrewAI에서 작업을 생성하는 일반적인 방법은 **JSONC 프로젝트 구성(새 crew 권장)** 또는 **코드에서 직접 정의**입니다.
|
||||
|
||||
### JSONC 구성 (권장)
|
||||
|
||||
`crewai create crew <name>`으로 만든 새 프로젝트는 `crew.jsonc`에 태스크를 정의합니다.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Research Crew",
|
||||
"agents": ["researcher", "reporting_analyst"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research_task",
|
||||
"description": "Conduct thorough research about {topic}.",
|
||||
"expected_output": "A list of the most relevant information about {topic}.",
|
||||
"agent": "researcher"
|
||||
},
|
||||
{
|
||||
"name": "reporting_task",
|
||||
"description": "Review the research and expand it into a detailed report.",
|
||||
"expected_output": "A polished markdown report.",
|
||||
"agent": "reporting_analyst",
|
||||
"context": ["research_task"],
|
||||
"markdown": true,
|
||||
"output_file": "report.md"
|
||||
}
|
||||
],
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
각 태스크에는 `description`과 `expected_output`이 필요합니다. `agent` 값은 `agents`에 나열된 에이전트 이름과 일치해야 합니다. `context`는 이전 태스크 이름만 참조할 수 있으며, 이후 태스크 참조는 거부됩니다.
|
||||
|
||||
### 클래식 YAML 구성
|
||||
|
||||
`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `config/tasks.yaml`과 `crew.py`의 `@CrewBase` 클래스를 사용합니다.
|
||||
|
||||
YAML 구성은 기존 Python/YAML 프로젝트와 `@CrewBase` 클래스에서 태스크를 정의하려는 팀을 위해 계속 지원됩니다.
|
||||
|
||||
클래식 프로젝트를 만든 후, `src/<project_name>/config/tasks.yaml` 파일로 이동하여 템플릿을 작업 요구 사항에 맞게 수정하세요.
|
||||
|
||||
<Note>
|
||||
YAML 파일 내 변수(예: `{topic}`)는 크루를 실행할 때 입력값에서 가져온 값으로 대체됩니다:
|
||||
```python Code
|
||||
crew.kickoff(inputs={'topic': 'AI Agents'})
|
||||
```
|
||||
</Note>
|
||||
|
||||
아래는 YAML을 사용하여 작업을 구성하는 방법의 예시입니다:
|
||||
|
||||
```yaml tasks.yaml
|
||||
research_task:
|
||||
description: >
|
||||
Conduct a thorough research about {topic}
|
||||
Make sure you find any interesting and relevant information given
|
||||
the current year is 2025.
|
||||
expected_output: >
|
||||
A list with 10 bullet points of the most relevant information about {topic}
|
||||
agent: researcher
|
||||
|
||||
reporting_task:
|
||||
description: >
|
||||
Review the context you got and expand each topic into a full section for a report.
|
||||
Make sure the report is detailed and contains any and all relevant information.
|
||||
expected_output: >
|
||||
A fully fledge reports with the mains topics, each with a full section of information.
|
||||
Formatted as markdown without '```'
|
||||
agent: reporting_analyst
|
||||
markdown: true
|
||||
output_file: report.md
|
||||
```
|
||||
|
||||
이 YAML 구성을 코드에서 사용하려면 `CrewBase`를 상속받는 크루 클래스를 생성하세요:
|
||||
|
||||
```python crew.py
|
||||
# src/<project_name>/crew.py
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
@CrewBase
|
||||
class LatestAiDevelopmentCrew():
|
||||
"""LatestAiDevelopment crew"""
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'], # type: ignore[index]
|
||||
verbose=True,
|
||||
tools=[SerperDevTool()]
|
||||
)
|
||||
|
||||
@agent
|
||||
def reporting_analyst(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['reporting_analyst'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def research_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['research_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@task
|
||||
def reporting_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['reporting_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=[
|
||||
self.researcher(),
|
||||
self.reporting_analyst()
|
||||
],
|
||||
tasks=[
|
||||
self.research_task(),
|
||||
self.reporting_task()
|
||||
],
|
||||
process=Process.sequential
|
||||
)
|
||||
```
|
||||
|
||||
<Note>
|
||||
YAML 파일(`agents.yaml` 및 `tasks.yaml`)에서 사용하는 이름은 Python 코드의 메서드 이름과 일치해야 합니다.
|
||||
</Note>
|
||||
|
||||
### 코드에서 직접 태스크 정의 (대안)
|
||||
|
||||
또는 YAML 구성 없이 코드에서 직접 태스크를 정의할 수 있습니다:
|
||||
|
||||
```python task.py
|
||||
from crewai import Task
|
||||
|
||||
research_task = Task(
|
||||
description="""
|
||||
Conduct a thorough research about AI Agents.
|
||||
Make sure you find any interesting and relevant information given
|
||||
the current year is 2025.
|
||||
""",
|
||||
expected_output="""
|
||||
A list with 10 bullet points of the most relevant information about AI Agents
|
||||
""",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
reporting_task = Task(
|
||||
description="""
|
||||
Review the context you got and expand each topic into a full section for a report.
|
||||
Make sure the report is detailed and contains any and all relevant information.
|
||||
""",
|
||||
expected_output="""
|
||||
A fully fledge reports with the mains topics, each with a full section of information.
|
||||
""",
|
||||
agent=reporting_analyst,
|
||||
markdown=True, # Enable markdown formatting for the final output
|
||||
output_file="report.md"
|
||||
)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`agent`를 직접 지정하여 할당하거나, 역할·가용성 등에 따라 `hierarchical` CrewAI 프로세스가 자동으로 결정하도록 둘 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
## 작업 결과
|
||||
|
||||
작업 결과를 이해하는 것은 효과적인 AI 워크플로우를 구축하는 데 매우 중요합니다. CrewAI는 여러 출력 형식을 지원하는 `TaskOutput` 클래스를 통해 작업 결과를 구조적으로 처리할 수 있는 방식을 제공합니다. 이 클래스는 작업 간에 출력값을 쉽게 전달할 수 있도록 지원합니다.
|
||||
|
||||
CrewAI 프레임워크에서 작업의 출력은 `TaskOutput` 클래스에 캡슐화되어 있습니다. 이 클래스는 작업의 결과를 구조적으로 접근할 수 있도록 해주며, raw 출력, JSON, Pydantic 모델 등 다양한 형식을 지원합니다.
|
||||
|
||||
기본적으로 `TaskOutput`에는 `raw` 출력만 포함됩니다. 원래의 `Task` 객체가 각각 `output_pydantic` 또는 `output_json`으로 구성된 경우에만 `TaskOutput`에 `pydantic` 또는 `json_dict` 출력이 포함됩니다.
|
||||
|
||||
### 작업 출력 속성
|
||||
|
||||
| 속성 | 파라미터 | 타입 | 설명 |
|
||||
| :---------------- | :----------------- | :------------------------- | :---------------------------------------------------------------------------------------------------- |
|
||||
| **설명** | `description` | `str` | 작업에 대한 설명입니다. |
|
||||
| **요약** | `summary` | `Optional[str]` | 설명의 처음 10단어에서 자동 생성된 작업의 요약입니다. |
|
||||
| **Raw** | `raw` | `str` | 작업의 원시 출력값입니다. 출력의 기본 형식입니다. |
|
||||
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | 작업의 구조화된 출력을 나타내는 Pydantic 모델 객체입니다. |
|
||||
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | 작업의 JSON 출력을 나타내는 딕셔너리입니다. |
|
||||
| **Agent** | `agent` | `str` | 작업을 실행한 agent입니다. |
|
||||
| **Output Format** | `output_format` | `OutputFormat` | 작업 출력의 형식입니다. RAW, JSON, Pydantic 옵션이 있으며, 기본값은 RAW입니다. |
|
||||
|
||||
### 태스크 메서드 및 프로퍼티
|
||||
|
||||
| Method/Property | 설명 |
|
||||
| :-------------- | :------------------------------------------------------------------------------------------------- |
|
||||
| **json** | 출력 포맷이 JSON일 경우 태스크 출력의 JSON 문자열 표현을 반환합니다. |
|
||||
| **to_dict** | JSON 및 Pydantic 출력을 딕셔너리로 변환합니다. |
|
||||
| **str** | 태스크 출력의 문자열 표현을 반환하며, Pydantic을 우선으로 하고 그 다음은 JSON, 그 다음은 raw를 사용합니다. |
|
||||
|
||||
### 작업 출력 액세스
|
||||
|
||||
작업이 실행된 후에는 `Task` 객체의 `output` 속성을 통해 그 출력을 액세스할 수 있습니다. `TaskOutput` 클래스는 이 출력을 다양한 방식으로 상호작용하고 표시할 수 있는 기능을 제공합니다.
|
||||
|
||||
#### 예시
|
||||
|
||||
```python Code
|
||||
# Example task
|
||||
task = Task(
|
||||
description='Find and summarize the latest AI news',
|
||||
expected_output='A bullet list summary of the top 5 most important AI news',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
# Execute the crew
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Accessing the task output
|
||||
task_output = task.output
|
||||
|
||||
print(f"Task Description: {task_output.description}")
|
||||
print(f"Task Summary: {task_output.summary}")
|
||||
print(f"Raw Output: {task_output.raw}")
|
||||
if task_output.json_dict:
|
||||
print(f"JSON Output: {json.dumps(task_output.json_dict, indent=2)}")
|
||||
if task_output.pydantic:
|
||||
print(f"Pydantic Output: {task_output.pydantic}")
|
||||
```
|
||||
|
||||
## 마크다운 출력 포매팅
|
||||
|
||||
`markdown` 매개변수는 작업 출력에 대해 자동 마크다운 포매팅을 활성화합니다. 이 값을 `True`로 설정하면, 작업은 에이전트에게 최종 답변을 올바른 마크다운 문법으로 포매팅하도록 지시합니다.
|
||||
|
||||
### 마크다운(Markdown) 포매팅 사용하기
|
||||
|
||||
```python Code
|
||||
# Example task with markdown formatting enabled
|
||||
formatted_task = Task(
|
||||
description="Create a comprehensive report on AI trends",
|
||||
expected_output="A well-structured report with headers, sections, and bullet points",
|
||||
agent=reporter_agent,
|
||||
markdown=True # Enable automatic markdown formatting
|
||||
)
|
||||
```
|
||||
|
||||
`markdown=True`일 때, 에이전트는 다음과 같이 출력을 포매팅하라는 추가 지시를 받게 됩니다:
|
||||
- 헤더에는 `#` 사용
|
||||
- 볼드체는 `**텍스트**` 사용
|
||||
- 이탤릭체는 `*텍스트*` 사용
|
||||
- 불릿 포인트에는 `-` 또는 `*` 사용
|
||||
- 인라인 코드는 `` `코드` `` 사용
|
||||
- 코드 블록은 ``` ```언어 ``` 사용
|
||||
|
||||
### 마크다운을 활용한 YAML 구성
|
||||
|
||||
```yaml tasks.yaml
|
||||
analysis_task:
|
||||
description: >
|
||||
Analyze the market data and create a detailed report
|
||||
expected_output: >
|
||||
A comprehensive analysis with charts and key findings
|
||||
agent: analyst
|
||||
markdown: true # Enable markdown formatting
|
||||
output_file: analysis.md
|
||||
```
|
||||
|
||||
### 마크다운 출력의 이점
|
||||
|
||||
- **일관된 포맷팅**: 모든 출력이 올바른 마크다운 규칙을 따르도록 보장합니다
|
||||
- **향상된 가독성**: 헤더, 목록, 강조 등으로 구조화된 콘텐츠
|
||||
- **문서화에 적합**: 출력을 문서 시스템에서 바로 사용할 수 있습니다
|
||||
- **크로스 플랫폼 호환성**: 마크다운은 보편적으로 지원됩니다
|
||||
|
||||
<Note>
|
||||
마크다운 포맷팅 지침은 `markdown=True`일 때 작업 프롬프트에 자동으로 추가되므로, 작업 설명에 포맷팅 요구사항을 따로 명시할 필요가 없습니다.
|
||||
</Note>
|
||||
|
||||
## 작업 종속성 및 컨텍스트
|
||||
|
||||
작업은 `context` 속성을 사용하여 다른 작업의 출력에 의존할 수 있습니다. 예를 들어:
|
||||
|
||||
```python Code
|
||||
research_task = Task(
|
||||
description="Research the latest developments in AI",
|
||||
expected_output="A list of recent AI developments",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
analysis_task = Task(
|
||||
description="Analyze the research findings and identify key trends",
|
||||
expected_output="Analysis report of AI trends",
|
||||
agent=analyst,
|
||||
context=[research_task] # This task will wait for research_task to complete
|
||||
)
|
||||
```
|
||||
|
||||
## 작업 가드레일
|
||||
|
||||
작업 가드레일은 작업 출력물을 다음 작업에 전달하기 전에 유효성을 검사하고 변환할 수 있는 방식을 제공합니다. 이 기능은 데이터 품질을 보장하고 에이전트의 출력이 특정 기준을 충족하지 않을 때 피드백을 제공하는 데 도움이 됩니다.
|
||||
|
||||
가드레일은 사용자 지정 유효성 검사 로직을 포함하는 Python 함수로 구현되며, 유효성 검사 프로세스를 완전히 제어할 수 있어 신뢰할 수 있고 결정적인 결과를 보장합니다.
|
||||
|
||||
### 함수 기반 가드레일
|
||||
|
||||
함수 기반 가드레일을 태스크에 추가하려면 `guardrail` 파라미터를 통해 검증 함수를 제공하세요:
|
||||
|
||||
```python Code
|
||||
from typing import Tuple, Union, Dict, Any
|
||||
from crewai import TaskOutput
|
||||
|
||||
def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Validate blog content meets requirements."""
|
||||
try:
|
||||
# Check word count
|
||||
word_count = len(result.split())
|
||||
if word_count > 200:
|
||||
return (False, "Blog content exceeds 200 words")
|
||||
|
||||
# Additional validation logic here
|
||||
return (True, result.strip())
|
||||
except Exception as e:
|
||||
return (False, "Unexpected error during validation")
|
||||
|
||||
blog_task = Task(
|
||||
description="Write a blog post about AI",
|
||||
expected_output="A blog post under 200 words",
|
||||
agent=blog_agent,
|
||||
guardrail=validate_blog_content # Add the guardrail function
|
||||
)
|
||||
```
|
||||
|
||||
### Guardrail 함수 요구사항
|
||||
|
||||
1. **함수 시그니처**:
|
||||
- 정확히 하나의 매개변수(태스크 출력)를 받아야 함
|
||||
- `(bool, Any)` 형태의 튜플을 반환해야 함
|
||||
- 타입 힌트는 권장하지만 필수는 아님
|
||||
|
||||
2. **반환 값**:
|
||||
- 성공 시: `(bool, Any)` 형태의 튜플을 반환. 예: `(True, validated_result)`
|
||||
- 실패 시: `(bool, str)` 형태의 튜플을 반환. 예: `(False, "Error message explain the failure")`
|
||||
|
||||
### 오류 처리 모범 사례
|
||||
|
||||
1. **구조화된 오류 응답**:
|
||||
```python Code
|
||||
from crewai import TaskOutput, LLMGuardrail
|
||||
|
||||
def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
try:
|
||||
# Main validation logic
|
||||
validated_data = perform_validation(result)
|
||||
return (True, validated_data)
|
||||
except ValidationError as e:
|
||||
return (False, f"VALIDATION_ERROR: {str(e)}")
|
||||
except Exception as e:
|
||||
return (False, str(e))
|
||||
```
|
||||
|
||||
2. **오류 범주**:
|
||||
- 구체적인 오류 코드 사용
|
||||
- 관련 컨텍스트 포함
|
||||
- 실행 가능한 피드백 제공
|
||||
|
||||
3. **검증 체인**:
|
||||
```python Code
|
||||
from typing import Any, Dict, List, Tuple, Union
|
||||
from crewai import TaskOutput
|
||||
|
||||
def complex_validation(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Chain multiple validation steps."""
|
||||
# Step 1: Basic validation
|
||||
if not result:
|
||||
return (False, "Empty result")
|
||||
|
||||
# Step 2: Content validation
|
||||
try:
|
||||
validated = validate_content(result)
|
||||
if not validated:
|
||||
return (False, "Invalid content")
|
||||
|
||||
# Step 3: Format validation
|
||||
formatted = format_output(validated)
|
||||
return (True, formatted)
|
||||
except Exception as e:
|
||||
return (False, str(e))
|
||||
```
|
||||
|
||||
### 가드레일 결과 처리
|
||||
|
||||
가드레일이 `(False, error)`를 반환할 때:
|
||||
1. 에러가 에이전트에게 다시 전달됩니다
|
||||
2. 에이전트가 문제를 수정하려고 시도합니다
|
||||
3. 다음 중 하나가 될 때까지 이 과정이 반복됩니다:
|
||||
- 가드레일이 `(True, result)`를 반환함
|
||||
- 최대 재시도 횟수에 도달함
|
||||
|
||||
재시도 처리가 포함된 예시:
|
||||
```python Code
|
||||
from typing import Optional, Tuple, Union
|
||||
from crewai import TaskOutput, Task
|
||||
|
||||
def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
"""Validate and parse JSON output."""
|
||||
try:
|
||||
# Try to parse as JSON
|
||||
data = json.loads(result)
|
||||
return (True, data)
|
||||
except json.JSONDecodeError as e:
|
||||
return (False, "Invalid JSON format")
|
||||
|
||||
task = Task(
|
||||
description="Generate a JSON report",
|
||||
expected_output="A valid JSON object",
|
||||
agent=analyst,
|
||||
guardrail=validate_json_output,
|
||||
guardrail_max_retries=3 # 재시도 횟수 제한
|
||||
)
|
||||
```
|
||||
|
||||
## 작업에서 구조화된 일관된 출력 얻기
|
||||
|
||||
<Note>
|
||||
또한 crew의 마지막 작업의 출력이 실제 crew 자체의 최종 출력이 된다는 점도 중요합니다.
|
||||
</Note>
|
||||
|
||||
### `output_pydantic` 사용하기
|
||||
`output_pydantic` 속성을 사용하면 작업 출력이 준수해야 할 Pydantic 모델을 정의할 수 있습니다. 이를 통해 출력이 구조화될 뿐만 아니라 Pydantic 모델에 따라 유효성 검증도 보장할 수 있습니다.
|
||||
|
||||
다음은 output_pydantic을 사용하는 방법을 보여주는 예제입니다.
|
||||
|
||||
```python Code
|
||||
import json
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class Blog(BaseModel):
|
||||
title: str
|
||||
content: str
|
||||
|
||||
|
||||
blog_agent = Agent(
|
||||
role="Blog Content Generator Agent",
|
||||
goal="Generate a blog title and content",
|
||||
backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""",
|
||||
verbose=False,
|
||||
allow_delegation=False,
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
task1 = Task(
|
||||
description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""",
|
||||
expected_output="A compelling blog title and well-written content.",
|
||||
agent=blog_agent,
|
||||
output_pydantic=Blog,
|
||||
)
|
||||
|
||||
# Instantiate your crew with a sequential process
|
||||
crew = Crew(
|
||||
agents=[blog_agent],
|
||||
tasks=[task1],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Option 1: Accessing Properties Using Dictionary-Style Indexing
|
||||
print("Accessing Properties - Option 1")
|
||||
title = result["title"]
|
||||
content = result["content"]
|
||||
print("Title:", title)
|
||||
print("Content:", content)
|
||||
|
||||
# Option 2: Accessing Properties Directly from the Pydantic Model
|
||||
print("Accessing Properties - Option 2")
|
||||
title = result.pydantic.title
|
||||
content = result.pydantic.content
|
||||
print("Title:", title)
|
||||
print("Content:", content)
|
||||
|
||||
# Option 3: Accessing Properties Using the to_dict() Method
|
||||
print("Accessing Properties - Option 3")
|
||||
output_dict = result.to_dict()
|
||||
title = output_dict["title"]
|
||||
content = output_dict["content"]
|
||||
print("Title:", title)
|
||||
print("Content:", content)
|
||||
|
||||
# Option 4: Printing the Entire Blog Object
|
||||
print("Accessing Properties - Option 5")
|
||||
print("Blog:", result)
|
||||
|
||||
```
|
||||
이 예제에서:
|
||||
* title과 content 필드를 가진 Pydantic 모델 Blog가 정의되어 있습니다.
|
||||
* 작업 task1은 output_pydantic 속성을 사용하여 출력이 Blog 모델을 준수해야 함을 명시합니다.
|
||||
* crew를 실행한 후, 위와 같이 다양한 방법으로 구조화된 출력을 확인할 수 있습니다.
|
||||
|
||||
#### 출력 접근 방법 설명
|
||||
1. 딕셔너리 스타일 인덱싱: `result["field_name"]`을 사용하여 필드를 직접 접근할 수 있습니다. 이는 CrewOutput 클래스가 `__getitem__` 메서드를 구현하고 있기 때문에 가능합니다.
|
||||
2. Pydantic 모델에서 직접 접근: `result.pydantic` 객체에서 속성에 직접 접근할 수 있습니다.
|
||||
3. to_dict() 메서드 사용: 출력을 딕셔너리로 변환한 후 필드에 접근합니다.
|
||||
4. 전체 객체 출력: 단순히 result 객체를 출력하여 구조화된 출력을 확인할 수 있습니다.
|
||||
|
||||
### `output_json` 사용하기
|
||||
`output_json` 속성을 사용하면 예상되는 출력을 JSON 형식으로 정의할 수 있습니다. 이를 통해 태스크의 출력이 쉽게 파싱되고, 애플리케이션에서 사용할 수 있는 유효한 JSON 구조임을 보장합니다.
|
||||
|
||||
다음은 `output_json` 사용 방법을 보여주는 예시입니다:
|
||||
|
||||
```python Code
|
||||
import json
|
||||
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
# Define the Pydantic model for the blog
|
||||
class Blog(BaseModel):
|
||||
title: str
|
||||
content: str
|
||||
|
||||
|
||||
# Define the agent
|
||||
blog_agent = Agent(
|
||||
role="Blog Content Generator Agent",
|
||||
goal="Generate a blog title and content",
|
||||
backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""",
|
||||
verbose=False,
|
||||
allow_delegation=False,
|
||||
llm="gpt-4o",
|
||||
)
|
||||
|
||||
# Define the task with output_json set to the Blog model
|
||||
task1 = Task(
|
||||
description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""",
|
||||
expected_output="A JSON object with 'title' and 'content' fields.",
|
||||
agent=blog_agent,
|
||||
output_json=Blog,
|
||||
)
|
||||
|
||||
# Instantiate the crew with a sequential process
|
||||
crew = Crew(
|
||||
agents=[blog_agent],
|
||||
tasks=[task1],
|
||||
verbose=True,
|
||||
process=Process.sequential,
|
||||
)
|
||||
|
||||
# Kickoff the crew to execute the task
|
||||
result = crew.kickoff()
|
||||
|
||||
# Option 1: Accessing Properties Using Dictionary-Style Indexing
|
||||
print("Accessing Properties - Option 1")
|
||||
title = result["title"]
|
||||
content = result["content"]
|
||||
print("Title:", title)
|
||||
print("Content:", content)
|
||||
|
||||
# Option 2: Printing the Entire Blog Object
|
||||
print("Accessing Properties - Option 2")
|
||||
print("Blog:", result)
|
||||
```
|
||||
|
||||
이 예시에서:
|
||||
* Pydantic 모델인 Blog가 title과 content 필드로 정의되어 있으며, 이는 JSON 출력의 구조를 명시하는 데 사용됩니다.
|
||||
* 태스크 task1은 output_json 속성을 사용하여 Blog 모델에 부합하는 JSON 출력을 기대함을 나타냅니다.
|
||||
* crew를 실행한 후, 두 가지 방식으로 구조화된 JSON 출력을 접근할 수 있습니다.
|
||||
|
||||
#### 출력 접근 방법 설명
|
||||
|
||||
1. 딕셔너리 스타일 인덱싱을 사용하여 속성 접근하기: result["field_name"]과 같이 필드를 직접 접근할 수 있습니다. 이는 CrewOutput 클래스가 __getitem__ 메서드를 구현하고 있어 출력을 딕셔너리처럼 사용할 수 있기 때문입니다. 이 방법에서는 result에서 title과 content를 가져옵니다.
|
||||
2. 전체 블로그 객체 출력하기: result를 출력하면 CrewOutput 객체의 문자열 표현을 얻을 수 있습니다. __str__ 메서드가 JSON 출력을 반환하도록 구현되어 있기 때문에, 전체 출력을 Blog 객체를 나타내는 형식이 잘 갖추어진 문자열로 볼 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
output_pydantic 또는 output_json을 사용하면, 작업의 출력이 일관되고 구조화된 형식으로 생성되므로 애플리케이션 내 또는 여러 작업 간에 데이터를 더 쉽게 처리하고 활용할 수 있습니다.
|
||||
|
||||
## 도구와 작업 통합
|
||||
|
||||
향상된 작업 성능과 에이전트 상호작용을 위해 [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) 및 [LangChain Tools](https://python.langchain.com/docs/integrations/tools)의 도구를 활용하세요.
|
||||
|
||||
## 도구와 함께 Task 생성하기
|
||||
|
||||
```python Code
|
||||
import os
|
||||
os.environ["OPENAI_API_KEY"] = "Your Key"
|
||||
os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
|
||||
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import SerperDevTool
|
||||
|
||||
research_agent = Agent(
|
||||
role='Researcher',
|
||||
goal='Find and summarize the latest AI news',
|
||||
backstory="""You're a researcher at a large company.
|
||||
You're responsible for analyzing data and providing insights
|
||||
to the business.""",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# to perform a semantic search for a specified query from a text's content across the internet
|
||||
search_tool = SerperDevTool()
|
||||
|
||||
task = Task(
|
||||
description='Find and summarize the latest AI news',
|
||||
expected_output='A bullet list summary of the top 5 most important AI news',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
이 예시는 특정 도구와 함께 사용되는 task가 맞춤형 task 실행을 위해 에이전트의 기본 도구 세트를 어떻게 재정의할 수 있는지 보여줍니다.
|
||||
|
||||
## 다른 작업 참조하기
|
||||
|
||||
CrewAI에서는 한 작업의 출력이 자동으로 다음 작업으로 전달되지만, 특정 작업(여러 개 포함)의 출력을 다른 작업의 컨텍스트로 명확하게 지정할 수도 있습니다.
|
||||
|
||||
이는 한 작업이 바로 뒤에 수행되지 않는 다른 작업의 출력에 의존해야 할 때 유용합니다. 이는 작업의 `context` 속성을 통해 수행됩니다:
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
|
||||
research_ai_task = Task(
|
||||
description="Research the latest developments in AI",
|
||||
expected_output="A list of recent AI developments",
|
||||
async_execution=True,
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
research_ops_task = Task(
|
||||
description="Research the latest developments in AI Ops",
|
||||
expected_output="A list of recent AI Ops developments",
|
||||
async_execution=True,
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
write_blog_task = Task(
|
||||
description="Write a full blog post about the importance of AI and its latest news",
|
||||
expected_output="Full blog post that is 4 paragraphs long",
|
||||
agent=writer_agent,
|
||||
context=[research_ai_task, research_ops_task]
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## 비동기 실행
|
||||
|
||||
작업을 비동기로 실행되도록 정의할 수 있습니다. 이는 crew가 해당 작업이 완료될 때까지 기다리지 않고 다음 작업을 계속 진행한다는 것을 의미합니다. 시간이 오래 걸리는 작업이거나, 이후 작업 수행에 필수적이지 않은 작업에 유용합니다.
|
||||
|
||||
이후 작업에서 비동기 작업의 출력이 완료될 때까지 기다리도록 하려면, `context` 속성을 사용할 수 있습니다.
|
||||
|
||||
```python Code
|
||||
#...
|
||||
|
||||
list_ideas = Task(
|
||||
description="List of 5 interesting ideas to explore for an article about AI.",
|
||||
expected_output="Bullet point list of 5 ideas for an article.",
|
||||
agent=researcher,
|
||||
async_execution=True # Will be executed asynchronously
|
||||
)
|
||||
|
||||
list_important_history = Task(
|
||||
description="Research the history of AI and give me the 5 most important events.",
|
||||
expected_output="Bullet point list of 5 important events.",
|
||||
agent=researcher,
|
||||
async_execution=True # Will be executed asynchronously
|
||||
)
|
||||
|
||||
write_article = Task(
|
||||
description="Write an article about AI, its history, and interesting ideas.",
|
||||
expected_output="A 4 paragraph article about AI.",
|
||||
agent=writer,
|
||||
context=[list_ideas, list_important_history] # Will wait for the output of the two tasks to be completed
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## 콜백 메커니즘
|
||||
|
||||
콜백 함수는 작업이 완료된 후 실행되며, 작업 결과에 따라 동작 또는 알림을 트리거할 수 있습니다.
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
|
||||
def callback_function(output: TaskOutput):
|
||||
# Do something after the task is completed
|
||||
# Example: Send an email to the manager
|
||||
print(f"""
|
||||
Task completed!
|
||||
Task: {output.description}
|
||||
Output: {output.raw}
|
||||
""")
|
||||
|
||||
research_task = Task(
|
||||
description='Find and summarize the latest AI news',
|
||||
expected_output='A bullet list summary of the top 5 most important AI news',
|
||||
agent=research_agent,
|
||||
tools=[search_tool],
|
||||
callback=callback_function
|
||||
)
|
||||
|
||||
#...
|
||||
```
|
||||
|
||||
## 특정 Task Output 접근하기
|
||||
|
||||
crew가 실행을 마치면, 해당 task 객체의 `output` 속성을 사용하여 특정 task의 output에 접근할 수 있습니다:
|
||||
|
||||
```python Code
|
||||
# ...
|
||||
task1 = Task(
|
||||
description='Find and summarize the latest AI news',
|
||||
expected_output='A bullet list summary of the top 5 most important AI news',
|
||||
agent=research_agent,
|
||||
tools=[search_tool]
|
||||
)
|
||||
|
||||
#...
|
||||
|
||||
crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[task1, task2, task3],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Returns a TaskOutput object with the description and results of the task
|
||||
print(f"""
|
||||
Task completed!
|
||||
Task: {task1.output.description}
|
||||
Output: {task1.output.raw}
|
||||
""")
|
||||
```
|
||||
|
||||
## 도구 재정의 메커니즘
|
||||
|
||||
작업에서 도구를 지정하면 에이전트의 기능을 동적으로 조정할 수 있어 CrewAI의 유연성이 강조됩니다.
|
||||
|
||||
## 오류 처리 및 검증 메커니즘
|
||||
|
||||
작업을 생성하고 실행하는 동안, 작업 속성의 견고성과 신뢰성을 보장하기 위해 특정 검증 메커니즘이 마련되어 있습니다. 이는 다음에 국한되지 않습니다:
|
||||
|
||||
- 작업마다 한 가지 출력 유형만 설정하여 명확한 출력 기대치를 유지함
|
||||
- 고유 식별자 시스템의 무결성을 유지하기 위해 `id` 속성의 수동 할당을 방지함
|
||||
|
||||
이러한 검증 절차는 crewAI 프레임워크 내에서 작업 실행의 일관성과 신뢰성을 유지하는 데 도움이 됩니다.
|
||||
|
||||
## 파일 저장 시 디렉토리 생성
|
||||
|
||||
`create_directory` 매개변수는 CrewAI가 작업 결과를 파일로 저장할 때 디렉토리를 자동으로 생성할지 여부를 제어합니다. 이 기능은 출력물을 체계적으로 정리하고, 특히 복잡한 프로젝트 계층 구조에서 파일 경로가 올바르게 구조화되도록 보장하는 데 매우 유용합니다.
|
||||
|
||||
### 기본 동작
|
||||
|
||||
기본적으로 `create_directory=True`로 설정되어 있으며, 이는 CrewAI가 출력 파일 경로에 누락된 디렉토리를 자동으로 생성함을 의미합니다:
|
||||
|
||||
```python Code
|
||||
# 기본 동작 - 디렉토리가 자동으로 생성됩니다
|
||||
report_task = Task(
|
||||
description='Generate a comprehensive market analysis report',
|
||||
expected_output='A detailed market analysis with charts and insights',
|
||||
agent=analyst_agent,
|
||||
output_file='reports/2025/market_analysis.md', # 'reports/2025/'가 없으면 생성됩니다
|
||||
markdown=True
|
||||
)
|
||||
```
|
||||
|
||||
### 디렉터리 생성 비활성화
|
||||
|
||||
자동 디렉터리 생성을 방지하고 디렉터리가 이미 존재함을 보장하려면 `create_directory=False`로 설정하세요:
|
||||
|
||||
```python Code
|
||||
# Strict mode - directory must already exist
|
||||
strict_output_task = Task(
|
||||
description='Save critical data that requires existing infrastructure',
|
||||
expected_output='Data saved to pre-configured location',
|
||||
agent=data_agent,
|
||||
output_file='secure/vault/critical_data.json',
|
||||
create_directory=False # Will raise RuntimeError if 'secure/vault/' doesn't exist
|
||||
)
|
||||
```
|
||||
|
||||
### YAML 구성
|
||||
|
||||
이 동작은 YAML 태스크 정의에서도 구성할 수 있습니다:
|
||||
|
||||
```yaml tasks.yaml
|
||||
analysis_task:
|
||||
description: >
|
||||
분기별 재무 분석 생성
|
||||
expected_output: >
|
||||
분기별 인사이트가 포함된 종합 재무 보고서
|
||||
agent: financial_analyst
|
||||
output_file: reports/quarterly/q4_2024_analysis.pdf
|
||||
create_directory: true # 'reports/quarterly/' 디렉토리를 자동으로 생성
|
||||
|
||||
audit_task:
|
||||
description: >
|
||||
컴플라이언스 감사 수행 및 기존 감사 디렉토리에 저장
|
||||
expected_output: >
|
||||
컴플라이언스 감사 보고서
|
||||
agent: auditor
|
||||
output_file: audit/compliance_report.md
|
||||
create_directory: false # 디렉토리가 이미 존재해야 함
|
||||
```
|
||||
|
||||
### 사용 사례
|
||||
|
||||
**자동 디렉토리 생성 (`create_directory=True`):**
|
||||
- 개발 및 프로토타이핑 환경
|
||||
- 날짜 기반 폴더로 동적 보고서 생성
|
||||
- 디렉토리 구조가 달라질 수 있는 자동화된 워크플로우
|
||||
- 사용자별 폴더가 필요한 멀티 테넌트 애플리케이션
|
||||
|
||||
**수동 디렉토리 관리 (`create_directory=False`):**
|
||||
- 엄격한 파일 시스템 제어가 필요한 운영 환경
|
||||
- 디렉토리가 사전 구성되어야 하는 보안 민감 애플리케이션
|
||||
- 특정 권한 요구 사항이 있는 시스템
|
||||
- 디렉토리 생성이 감사되는 규정 준수 환경
|
||||
|
||||
### 오류 처리
|
||||
|
||||
`create_directory=False`이고 디렉토리가 존재하지 않는 경우, CrewAI는 `RuntimeError`를 발생시킵니다:
|
||||
|
||||
```python Code
|
||||
try:
|
||||
result = crew.kickoff()
|
||||
except RuntimeError as e:
|
||||
# Handle missing directory error
|
||||
print(f"Directory creation failed: {e}")
|
||||
# Create directory manually or use fallback location
|
||||
```
|
||||
|
||||
아래 영상을 통해 CrewAI에서 구조화된 출력을 사용하는 방법을 확인하세요:
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/dNpKQk5uxHw"
|
||||
title="CrewAI에서 구조화된 출력 사용하기"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerPolicy="strict-origin-when-cross-origin"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
## 결론
|
||||
|
||||
작업(task)은 CrewAI 에이전트의 행동을 이끄는 원동력입니다.
|
||||
작업과 그 결과를 적절하게 정의함으로써, 에이전트가 독립적으로 또는 협업 단위로 효과적으로 작동할 수 있는 기반을 마련할 수 있습니다.
|
||||
작업에 적합한 도구를 장착하고, 실행 과정을 이해하며, 견고한 검증 절차를 따르는 것은 CrewAI의 잠재력을 극대화하는 데 필수적입니다.
|
||||
이를 통해 에이전트가 할당된 작업에 효과적으로 준비되고, 작업이 의도대로 수행될 수 있습니다.
|
||||
49
docs/edge/ko/concepts/testing.mdx
Normal file
49
docs/edge/ko/concepts/testing.mdx
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: 테스트
|
||||
description: CrewAI Crew를 테스트하고 그 성능을 평가하는 방법을 알아보세요.
|
||||
icon: vial
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
테스트는 개발 프로세스에서 매우 중요한 부분이며, crew가 예상대로 동작하는지 확인하는 것이 필수적입니다. crewAI를 사용하면 내장된 테스트 기능을 통해 crew를 쉽게 테스트하고 성능을 평가할 수 있습니다.
|
||||
|
||||
### 테스트 기능 사용하기
|
||||
|
||||
CLI 명령어 `crewai test`를 추가하여 crew 테스트를 쉽게 할 수 있습니다. 이 명령어는 지정한 반복 횟수만큼 crew를 실행하고, 자세한 성능 지표를 제공합니다. 매개변수로는 `n_iterations`와 `model`이 있으며, 이들은 선택 사항이고 각각 기본값은 2와 `gpt-4o-mini`입니다. 현재는 OpenAI만 지원됩니다.
|
||||
|
||||
```bash
|
||||
crewai test
|
||||
```
|
||||
|
||||
더 많은 반복 횟수로 실행하거나 다른 모델을 사용하려면 다음과 같이 매개변수를 지정할 수 있습니다:
|
||||
|
||||
```bash
|
||||
crewai test --n_iterations 5 --model gpt-4o
|
||||
```
|
||||
|
||||
또는 축약형을 사용할 수 있습니다:
|
||||
|
||||
```bash
|
||||
crewai test -n 5 -m gpt-4o
|
||||
```
|
||||
|
||||
`crewai test` 명령어를 실행하면 crew가 지정한 횟수만큼 실행되고, 수행이 끝나면 성능 지표가 표시됩니다.
|
||||
|
||||
실행 마지막에 표시되는 점수 표는 다음과 같은 지표로 crew의 성능을 보여줍니다:
|
||||
|
||||
<center>**작업 점수 (1-10 높을수록 좋음)**</center>
|
||||
|
||||
| Tasks/Crew/Agents | Run 1 | Run 2 | Avg. Total | Agents | Additional Info |
|
||||
|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------|
|
||||
| Task 1 | 9.0 | 9.5 | **9.2** | Professional Insights | |
|
||||
| | | | | Researcher | |
|
||||
| Task 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | |
|
||||
| Task 3 | 9.0 | 9.0 | **9.0** | Automation Insights | |
|
||||
| | | | | Specialist | |
|
||||
| Task 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist |
|
||||
| Crew | 9.00 | 9.38 | **9.2** | | |
|
||||
| Execution Time (s) | 126 | 145 | **135** | | |
|
||||
|
||||
위 예시는 두 번 실행한 crew의 테스트 결과를 보여주며, 각 작업과 crew 전체의 평균 총점이 포함되어 있습니다.
|
||||
287
docs/edge/ko/concepts/tools.mdx
Normal file
287
docs/edge/ko/concepts/tools.mdx
Normal file
@@ -0,0 +1,287 @@
|
||||
---
|
||||
title: 도구
|
||||
description: CrewAI 프레임워크 내에서 에이전트 협업과 작업 실행을 위해 도구를 이해하고 활용하기.
|
||||
icon: screwdriver-wrench
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI 도구는 에이전트에게 웹 검색, 데이터 분석부터 동료 간 협업 및 작업 위임에 이르기까지 다양한 기능을 제공합니다.
|
||||
이 문서에서는 CrewAI 프레임워크 내에서 이러한 도구를 생성, 통합 및 활용하는 방법과, 협업 도구에 초점을 맞춘 새로운 기능에 대해 설명합니다.
|
||||
|
||||
<Note type="info" title="도구는 다섯 가지 에이전트 기능 유형 중 하나입니다">
|
||||
도구는 에이전트에게 행동을 취할 수 있는 **호출 가능한 함수**를 제공합니다. [MCP](/ko/mcp/overview) (원격 도구 서버), [앱](/ko/concepts/agent-capabilities) (플랫폼 통합), [스킬](/ko/concepts/skills) (도메인 전문성), [지식](/ko/concepts/knowledge) (검색된 사실)과 함께 작동합니다. 각 유형을 언제 사용해야 하는지 알아보려면 [에이전트 기능](/ko/concepts/agent-capabilities) 개요를 참조하세요.
|
||||
</Note>
|
||||
|
||||
## Tool이란 무엇인가?
|
||||
|
||||
CrewAI에서 tool은 에이전트가 다양한 작업을 수행하기 위해 활용할 수 있는 기술 또는 기능입니다.
|
||||
이에는 [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) 및 [LangChain Tools](https://python.langchain.com/docs/integrations/tools)의 tool이 포함되어,
|
||||
간단한 검색부터 복잡한 상호작용, 그리고 에이전트 간의 효과적인 협업까지 모두 가능하게 합니다.
|
||||
|
||||
<Note type="info" title="엔터프라이즈 확장: Tools Repository">
|
||||
CrewAI 엔터프라이즈는 주요 비즈니스 시스템 및 API와의 사전 구축된 통합을 제공하는 종합적인 Tools Repository를 제공합니다. 며칠이 걸리던 엔터프라이즈 tool로 에이전트를 몇 분 만에 배포할 수 있습니다.
|
||||
|
||||
엔터프라이즈 Tools Repository에는 다음이 포함됩니다:
|
||||
- 인기 엔터프라이즈 시스템용 사전 구축 커넥터
|
||||
- 커스텀 tool 생성 인터페이스
|
||||
- 버전 관리 및 공유 기능
|
||||
- 보안 및 규정 준수 기능
|
||||
</Note>
|
||||
|
||||
## 도구의 주요 특징
|
||||
|
||||
- **유틸리티**: 웹 검색, 데이터 분석, 콘텐츠 생성, 에이전트 협업과 같은 작업을 위해 제작됨.
|
||||
- **통합성**: 도구를 워크플로우에 원활하게 통합하여 에이전트의 역량을 강화함.
|
||||
- **맞춤화 가능성**: 맞춤형 도구를 개발하거나 기존 도구를 활용할 수 있는 유연성을 제공하여 에이전트의 특정 요구 사항에 대응함.
|
||||
- **오류 처리**: 원활한 작동을 보장하기 위해 강력한 오류 처리 메커니즘을 포함함.
|
||||
- **캐싱 메커니즘**: 성능 최적화와 중복 작업 감소를 위한 지능형 캐싱 기능을 갖춤.
|
||||
- **비동기 지원**: 동기 및 비동기 도구를 모두 처리하여 논블로킹(Non-blocking) 작업을 가능하게 함.
|
||||
|
||||
## CrewAI 도구 사용하기
|
||||
|
||||
crewAI 도구로 에이전트의 기능을 확장하려면, 우선 추가 도구 패키지를 설치하세요:
|
||||
|
||||
```bash
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
아래는 도구 사용 예시입니다:
|
||||
|
||||
```python Code
|
||||
import os
|
||||
from crewai import Agent, Task, Crew
|
||||
# crewAI 도구 임포트
|
||||
from crewai_tools import (
|
||||
DirectoryReadTool,
|
||||
FileReadTool,
|
||||
SerperDevTool,
|
||||
WebsiteSearchTool
|
||||
)
|
||||
|
||||
# API 키 설정
|
||||
os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API 키
|
||||
os.environ["OPENAI_API_KEY"] = "Your Key"
|
||||
|
||||
# 도구 인스턴스화
|
||||
docs_tool = DirectoryReadTool(directory='./blog-posts')
|
||||
file_tool = FileReadTool()
|
||||
search_tool = SerperDevTool()
|
||||
web_rag_tool = WebsiteSearchTool()
|
||||
|
||||
# 에이전트 생성
|
||||
researcher = Agent(
|
||||
role='Market Research Analyst',
|
||||
goal='Provide up-to-date market analysis of the AI industry',
|
||||
backstory='An expert analyst with a keen eye for market trends.',
|
||||
tools=[search_tool, web_rag_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role='Content Writer',
|
||||
goal='Craft engaging blog posts about the AI industry',
|
||||
backstory='A skilled writer with a passion for technology.',
|
||||
tools=[docs_tool, file_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# 작업 정의
|
||||
research = Task(
|
||||
description='Research the latest trends in the AI industry and provide a summary.',
|
||||
expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.',
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
write = Task(
|
||||
description='Write an engaging blog post about the AI industry, based on the research analyst's summary. Draw inspiration from the latest blog posts in the directory.',
|
||||
expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.',
|
||||
agent=writer,
|
||||
output_file='blog-posts/new_post.md' # 최종 블로그 글이 여기에 저장됩니다
|
||||
)
|
||||
|
||||
# 계획 기능을 활성화하여 crew 구성
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research, write],
|
||||
verbose=True,
|
||||
planning=True, # 계획 기능 활성화
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 사용 가능한 CrewAI 도구
|
||||
|
||||
- **에러 처리**: 모든 도구는 에러 처리 기능이 내장되어 있어, 에이전트가 예외 상황을 우아하게 관리하며 작업을 계속할 수 있습니다.
|
||||
- **캐싱 메커니즘**: 모든 도구는 캐싱을 지원하여, 에이전트가 이전에 얻은 결과를 효율적으로 재사용할 수 있고 외부 자원에 대한 부하를 줄이며 실행 시간을 단축할 수 있습니다. 또한 도구의 `cache_function` 속성을 사용하여 캐싱 메커니즘을 세밀하게 제어할 수 있습니다.
|
||||
|
||||
사용 가능한 도구 목록과 그 설명은 다음과 같습니다:
|
||||
|
||||
| 도구 | 설명 |
|
||||
| :-------------------------------- | :---------------------------------------------------------------------------------------------------- |
|
||||
| **ApifyActorsTool** | 웹 스크래핑 및 자동화 작업을 위해 Apify Actors를 워크플로우에 통합하는 도구입니다. |
|
||||
| **BrowserbaseLoadTool** | 웹 브라우저와 상호작용하고 데이터를 추출하는 도구입니다. |
|
||||
| **CodeDocsSearchTool** | 코드 문서 및 관련 기술 문서를 검색하는 데 최적화된 RAG 도구입니다. |
|
||||
| **CodeInterpreterTool** | 파이썬 코드를 해석하는 도구입니다. |
|
||||
| **ComposioTool** | Composio 도구의 사용을 가능하게 합니다. |
|
||||
| **CSVSearchTool** | CSV 파일 내에서 검색하도록 설계된 RAG 도구이며, 구조화된 데이터를 처리하도록 맞춤화되어 있습니다. |
|
||||
| **DALL-E Tool** | DALL-E API를 사용해 이미지를 생성하는 도구입니다. |
|
||||
| **DirectorySearchTool** | 디렉터리 내에서 검색하는 RAG 도구로, 파일 시스템을 탐색할 때 유용합니다. |
|
||||
| **DOCXSearchTool** | DOCX 문서 내에서 검색하는 데 특화된 RAG 도구로, Word 파일을 처리할 때 이상적입니다. |
|
||||
| **DirectoryReadTool** | 디렉터리 구조와 그 내용을 읽고 처리하도록 지원하는 도구입니다. |
|
||||
| **ExaSearchTool** | 다양한 데이터 소스를 폭넓게 검색하기 위해 설계된 도구입니다. |
|
||||
| **FileReadTool** | 다양한 파일 형식을 지원하며 파일에서 데이터를 읽고 추출할 수 있는 도구입니다. |
|
||||
| **FirecrawlSearchTool** | Firecrawl을 이용해 웹페이지를 검색하고 결과를 반환하는 도구입니다. |
|
||||
| **FirecrawlCrawlWebsiteTool** | Firecrawl을 사용해 웹페이지를 크롤링하는 도구입니다. |
|
||||
| **FirecrawlScrapeWebsiteTool** | Firecrawl을 통해 웹페이지의 URL을 스크래핑하고 그 내용을 반환하는 도구입니다. |
|
||||
| **GithubSearchTool** | GitHub 저장소 내에서 검색하는 RAG 도구로, 코드 및 문서 검색에 유용합니다. |
|
||||
| **SerperDevTool** | 개발 용도로 특화된 도구로, 특정 기능이 개발 중입니다. |
|
||||
| **TXTSearchTool** | 텍스트(.txt) 파일 내에서 검색하는 데 중점을 둔 RAG 도구로, 비구조적 데이터에 적합합니다. |
|
||||
| **JSONSearchTool** | JSON 파일 내에서 검색하도록 설계된 RAG 도구로, 구조화된 데이터 처리에 적합합니다. |
|
||||
| **LlamaIndexTool** | LlamaIndex 도구의 사용을 가능하게 합니다. |
|
||||
| **MDXSearchTool** | 마크다운(MDX) 파일 내에서 검색하도록 맞춤화된 RAG 도구로, 문서화에 유용합니다. |
|
||||
| **PDFSearchTool** | PDF 문서 내에서 검색하는 RAG 도구로, 스캔된 문서를 처리하기에 이상적입니다. |
|
||||
| **PGSearchTool** | PostgreSQL 데이터베이스 내에서 검색하는 데 최적화된 RAG 도구로, 데이터베이스 쿼리에 적합합니다. |
|
||||
| **Vision Tool** | DALL-E API를 사용해 이미지를 생성하는 도구입니다. |
|
||||
| **RagTool** | 다양한 데이터 소스 및 형식을 처리할 수 있는 범용 RAG 도구입니다. |
|
||||
| **ScrapeElementFromWebsiteTool** | 웹사이트에서 특정 요소만 스크래핑할 수 있는 도구로, 목표 데이터 추출에 유용합니다. |
|
||||
| **ScrapeWebsiteTool** | 전체 웹사이트를 스크래핑할 수 있도록 도와주는 도구로, 포괄적인 데이터 수집에 이상적입니다. |
|
||||
| **WebsiteSearchTool** | 웹사이트 콘텐츠를 검색하는 RAG 도구로, 웹 데이터 추출에 최적화되어 있습니다. |
|
||||
| **XMLSearchTool** | XML 파일 내에서 검색하도록 설계된 RAG 도구로, 구조화된 데이터 형식에 적합합니다. |
|
||||
| **YoutubeChannelSearchTool** | 유튜브 채널 내에서 검색하는 RAG 도구로, 동영상 콘텐츠 분석에 유용합니다. |
|
||||
| **YoutubeVideoSearchTool** | 유튜브 동영상 내에서 검색하는 RAG 도구로, 동영상 데이터 추출에 이상적입니다. |
|
||||
|
||||
## 자체 도구 만들기
|
||||
|
||||
<Tip>
|
||||
개발자는 에이전트의 요구에 맞는 `custom tools`를 직접 제작하거나,
|
||||
미리 구축된 옵션을 활용할 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
CrewAI 도구를 만드는 방법에는 두 가지 주요 방법이 있습니다:
|
||||
|
||||
### `BaseTool` 서브클래싱
|
||||
|
||||
```python Code
|
||||
from crewai.tools import BaseTool
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
class MyToolInput(BaseModel):
|
||||
"""Input schema for MyCustomTool."""
|
||||
argument: str = Field(..., description="Description of the argument.")
|
||||
|
||||
class MyCustomTool(BaseTool):
|
||||
name: str = "Name of my tool"
|
||||
description: str = "What this tool does. It's vital for effective utilization."
|
||||
args_schema: Type[BaseModel] = MyToolInput
|
||||
|
||||
def _run(self, argument: str) -> str:
|
||||
# Your tool's logic here
|
||||
return "Tool's result"
|
||||
```
|
||||
|
||||
## 비동기 도구 지원
|
||||
|
||||
CrewAI는 비동기 도구를 지원하여, 네트워크 요청, 파일 I/O 또는 기타 비동기 작업과 같이 메인 실행 스레드를 차단하지 않고 비차단 연산을 수행하는 도구를 구현할 수 있습니다.
|
||||
|
||||
### 비동기 툴 만들기
|
||||
|
||||
비동기 툴을 만드는 방법에는 두 가지가 있습니다:
|
||||
|
||||
#### 1. `tool` 데코레이터를 비동기 함수와 함께 사용하기
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
|
||||
@tool("fetch_data_async")
|
||||
async def fetch_data_async(query: str) -> str:
|
||||
"""Asynchronously fetch data based on the query."""
|
||||
# Simulate async operation
|
||||
await asyncio.sleep(1)
|
||||
return f"Data retrieved for {query}"
|
||||
```
|
||||
|
||||
#### 2. 사용자 지정 Tool 클래스에서 비동기 메서드 구현
|
||||
|
||||
```python Code
|
||||
from crewai.tools import BaseTool
|
||||
|
||||
class AsyncCustomTool(BaseTool):
|
||||
name: str = "async_custom_tool"
|
||||
description: str = "An asynchronous custom tool"
|
||||
|
||||
async def _run(self, query: str = "") -> str:
|
||||
"""Asynchronously run the tool"""
|
||||
# Your async implementation here
|
||||
await asyncio.sleep(1)
|
||||
return f"Processed {query} asynchronously"
|
||||
```
|
||||
|
||||
### 비동기 도구 사용하기
|
||||
|
||||
비동기 도구는 표준 Crew 워크플로우와 Flow 기반 워크플로우 모두에서 원활하게 작동합니다:
|
||||
|
||||
```python Code
|
||||
# In standard Crew
|
||||
agent = Agent(role="researcher", tools=[async_custom_tool])
|
||||
|
||||
# In Flow
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
async def begin(self):
|
||||
crew = Crew(agents=[agent])
|
||||
result = await crew.kickoff_async()
|
||||
return result
|
||||
```
|
||||
|
||||
CrewAI 프레임워크는 동기 및 비동기 도구의 실행을 자동으로 처리하므로, 별도로 호출 방법을 신경 쓸 필요가 없습니다.
|
||||
|
||||
### `tool` 데코레이터 활용하기
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
@tool("Name of my tool")
|
||||
def my_tool(question: str) -> str:
|
||||
"""Clear description for what this tool is useful for, your agent will need this information to use it."""
|
||||
# Function logic here
|
||||
return "Result from your custom tool"
|
||||
```
|
||||
|
||||
### 커스텀 캐싱 메커니즘
|
||||
|
||||
<Tip>
|
||||
도구는 선택적으로 `cache_function`을 구현하여 캐싱 동작을 세밀하게 조정할 수 있습니다.
|
||||
이 함수는 특정 조건에 따라 결과를 언제 캐싱할지 결정하여 캐싱 로직을 정교하게 제어할 수 있도록 합니다.
|
||||
</Tip>
|
||||
|
||||
```python Code
|
||||
from crewai.tools import tool
|
||||
|
||||
@tool
|
||||
def multiplication_tool(first_number: int, second_number: int) -> str:
|
||||
"""Useful for when you need to multiply two numbers together."""
|
||||
return first_number * second_number
|
||||
|
||||
def cache_func(args, result):
|
||||
# In this case, we only cache the result if it's a multiple of 2
|
||||
cache = result % 2 == 0
|
||||
return cache
|
||||
|
||||
multiplication_tool.cache_function = cache_func
|
||||
|
||||
writer1 = Agent(
|
||||
role="Writer",
|
||||
goal="You write lessons of math for kids.",
|
||||
backstory="You're an expert in writing and you love to teach kids but you know nothing of math.",
|
||||
tools=[multiplication_tool],
|
||||
allow_delegation=False,
|
||||
)
|
||||
#...
|
||||
```
|
||||
|
||||
## 결론
|
||||
|
||||
도구는 CrewAI 에이전트의 역량을 확장하는 데 중요한 역할을 하며, 이를 통해 에이전트가 폭넓은 작업을 수행하고 효과적으로 협업할 수 있습니다. CrewAI로 솔루션을 구축할 때는, 맞춤형 또는 기존의 도구를 모두 활용하여 에이전트를 강화하고 AI 생태계를 향상시키세요. 에이전트의 성능과 기능을 최적화하기 위해 오류 처리, 캐싱 메커니즘, 그리고 도구 인자의 유연성도 고려해보시기 바랍니다.
|
||||
132
docs/edge/ko/concepts/training.mdx
Normal file
132
docs/edge/ko/concepts/training.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: 교육
|
||||
description: 피드백을 조기에 제공하여 CrewAI 에이전트를 학습시키고 일관된 결과를 얻는 방법을 알아보세요.
|
||||
icon: dumbbell
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI의 학습 기능을 사용하면 커맨드라인 인터페이스(CLI)를 통해 AI 에이전트를 학습시킬 수 있습니다.
|
||||
`crewai train -n <n_iterations>` 명령어를 실행하면 학습 프로세스의 반복 횟수를 지정할 수 있습니다.
|
||||
|
||||
학습 과정에서 CrewAI는 에이전트의 성능을 최적화하기 위한 다양한 기법과 인간의 피드백을 활용합니다.
|
||||
이를 통해 에이전트는 이해력, 의사결정 능력, 문제 해결 능력을 향상할 수 있습니다.
|
||||
|
||||
### CLI를 사용하여 Crew 학습시키기
|
||||
|
||||
학습 기능을 사용하려면 다음 단계를 따르십시오:
|
||||
|
||||
1. 터미널 또는 명령 프롬프트를 엽니다.
|
||||
2. CrewAI 프로젝트가 위치한 디렉터리로 이동합니다.
|
||||
3. 다음 명령어를 실행합니다:
|
||||
|
||||
```shell
|
||||
crewai train -n <n_iterations> <filename> (optional)
|
||||
```
|
||||
<Tip>
|
||||
`<n_iterations>`를 원하는 학습 반복 횟수로, `<filename>`을 `.pkl`로 끝나는 적절한 파일 이름으로 바꿔 입력하세요.
|
||||
</Tip>
|
||||
|
||||
### 크루를 프로그래밍 방식으로 훈련시키기
|
||||
|
||||
크루를 프로그래밍 방식으로 훈련시키려면 다음 단계를 따르세요:
|
||||
|
||||
1. 훈련을 위한 반복 횟수를 정의합니다.
|
||||
2. 훈련 프로세스에 사용할 입력 파라미터를 지정합니다.
|
||||
3. 잠재적인 오류를 처리하기 위해 try-except 블록 내에서 훈련 명령을 실행합니다.
|
||||
|
||||
```python Code
|
||||
n_iterations = 2
|
||||
inputs = {"topic": "CrewAI Training"}
|
||||
filename = "your_model.pkl"
|
||||
|
||||
try:
|
||||
YourCrewName_Crew().crew().train(
|
||||
n_iterations=n_iterations,
|
||||
inputs=inputs,
|
||||
filename=filename
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
raise Exception(f"An error occurred while training the crew: {e}")
|
||||
```
|
||||
|
||||
### 주요 참고 사항
|
||||
|
||||
- **양의 정수 필수 조건:** 반복 횟수(`n_iterations`)가 양의 정수인지 확인하세요. 이 조건이 충족되지 않으면 코드에서 `ValueError`가 발생합니다.
|
||||
- **파일명 필수 조건:** 파일명이 `.pkl`로 끝나는지 확인하세요. 이 조건이 충족되지 않으면 코드에서 `ValueError`가 발생합니다.
|
||||
- **에러 처리:** 코드는 서브프로세스 오류 및 예기치 않은 예외를 처리하며, 사용자에게 에러 메시지를 제공합니다.
|
||||
|
||||
에이전트의 복잡성에 따라 훈련 과정이 다소 시간이 소요될 수 있으며, 각 반복마다 사용자의 피드백이 필요함을 유의하세요.
|
||||
|
||||
훈련이 완료되면, 에이전트는 향상된 능력과 지식을 갖추게 되어, 더욱 복잡한 작업을 해결하고 일관성 있고 가치 있는 인사이트를 제공할 수 있습니다.
|
||||
|
||||
에이전트를 정기적으로 업데이트하고 재훈련하여 최신 정보와 업계 발전을 반영할 수 있도록 하세요.
|
||||
|
||||
CrewAI와 함께 즐거운 훈련 되세요! 🚀
|
||||
|
||||
## 소형 언어 모델 고려사항
|
||||
|
||||
<Warning>
|
||||
소형 언어 모델(≤7B 파라미터)을 학습 데이터 평가에 사용할 때, 구조화된 출력 생성 및 복잡한 지침 준수에 어려움을 겪을 수 있으니 주의하시기 바랍니다.
|
||||
</Warning>
|
||||
|
||||
### 소형 모델의 학습 평가 한계
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="JSON 출력 정확도" icon="triangle-exclamation">
|
||||
소형 모델은 구조화된 학습 평가에 필요한 유효한 JSON 응답을 생성하는 데 종종 어려움을 겪으며, 이로 인해 파싱 오류와 불완전한 데이터가 발생할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="평가 품질" icon="chart-line">
|
||||
7B 파라미터 미만의 모델은 대형 모델에 비해 더 제한적이고 깊이 있는 추론이 부족한 평가 결과를 제공할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="지침 준수" icon="list-check">
|
||||
복잡한 학습 평가 기준을 소형 모델이 완전히 따르거나 고려하지 못할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="일관성" icon="rotate">
|
||||
소형 모델은 여러 학습 반복 과정에서 평가의 일관성이 부족할 수 있습니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### 학습을 위한 권장 사항
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Best Practice">
|
||||
최적의 학습 품질과 신뢰할 수 있는 평가를 위해 최소 7B 파라미터 이상의 모델을 사용하는 것을 강력히 권장합니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task, LLM
|
||||
|
||||
# Recommended minimum for training evaluation
|
||||
llm = LLM(model="mistral/open-mistral-7b")
|
||||
|
||||
# Better options for reliable training evaluation
|
||||
llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0")
|
||||
llm = LLM(model="gpt-4o")
|
||||
|
||||
# Use this LLM with your agents
|
||||
agent = Agent(
|
||||
role="Training Evaluator",
|
||||
goal="Provide accurate training feedback",
|
||||
llm=llm
|
||||
)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
더 강력한 모델일수록 더 우수한 피드백과 뛰어난 추론을 제공하므로, 더욱 효과적인 학습 반복이 가능합니다.
|
||||
</Tip>
|
||||
</Tab>
|
||||
<Tab title="Small Model Usage">
|
||||
학습 평가를 위해 반드시 소형 모델을 사용해야 한다면 다음과 같은 제약 사항에 유의하세요:
|
||||
|
||||
```python
|
||||
# Using a smaller model (expect some limitations)
|
||||
llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct")
|
||||
```
|
||||
|
||||
<Warning>
|
||||
CrewAI는 소형 모델에 대한 최적화 기능을 포함하고 있지만, 더 많은 인간의 개입이 필요한 덜 신뢰할 수 있고 세밀하지 않은 평가 결과가 발생할 수 있습니다.
|
||||
</Warning>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "자동화 살펴보기"
|
||||
description: "Automations 탭에서 플릿 상태, LLM 소비, 자동화별 동작을 확인합니다."
|
||||
sidebarTitle: "모니터링"
|
||||
icon: "gauge"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (베타) 문서 내비게이션**
|
||||
|
||||
- [개요](/ko/enterprise/features/agent-control-plane/overview)
|
||||
- **모니터링** *(현재 페이지)*
|
||||
- [규칙](/ko/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## 개요
|
||||
|
||||
**Automations** 탭은 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)의 읽기 전용 운영 뷰입니다. 두 개의 메트릭 카드, 인터랙티브 sankey, 그리고 **Automations**와 **Consumption** 두 개의 서브 테이블을 결합해 검색·필터·정렬을 지원합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
모든 차트와 테이블은 오른쪽 상단의 **지난 24시간 / 지난 1주 / 지난 30일** 선택기를 따릅니다. 변화량은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다.
|
||||
|
||||
<Note>
|
||||
행은 **crewAI v1.13 이상**의 deployment에 대해서만 데이터를 표시합니다. 그 이전 deployment는 sankey 아래 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 메트릭에도 기여하지 않습니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요.
|
||||
</Note>
|
||||
|
||||
## 대시보드
|
||||
|
||||
페이지 상단에는 두 개의 메트릭 카드와 인터랙티브 sankey가 있습니다. 어느 카드를 클릭해도 sankey가 다음 두 모드 사이를 전환합니다:
|
||||
|
||||
- **상태 모드** — `전체 자동화 → 상태 버킷(Critical / Warning / Healthy)`. 버킷을 클릭하면 Automations 테이블이 해당 deployment로 필터링됩니다.
|
||||
- **소비 모드** — `모델 공급자 → 자동화 → 총 비용`. 공급자를 클릭하면 Consumption 테이블이 해당 공급자로 필터링됩니다.
|
||||
|
||||
| 카드 | 표시 내용 |
|
||||
|------|---------------|
|
||||
| **Automations** | `active` 자동화(및 전체 개수), 윈도우 내 총 `errors`, 현재 `active executions`(및 윈도우 내 총합), 이전 기간 대비 변화량. |
|
||||
| **Consumption** | 총 `cost`와 `tokens used`, 이전 기간 대비 비용 변화량. |
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Automations 테이블
|
||||
|
||||
**Automations** 서브 탭은 deployment 단위의 플릿 상태 분해입니다. 각 행은 배포된 하나의 crew 또는 flow입니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| 열 | 표시 내용 |
|
||||
|--------|---------------|
|
||||
| **Automation** | deployment 이름과 할당된 태그(예: `production`, `financial`). |
|
||||
| **Last execution** | 가장 최근 실행 이후 경과 시간. |
|
||||
| **Health Status Breakdown** | 윈도우 내 실행에 대한 `Critical` / `Warning` / `Healthy` 비율의 누적 막대. |
|
||||
| **Executions with Errors** | 윈도우 내 총 실패 실행 수. |
|
||||
| **PII detection applied** | deployment별 PII 설정 또는 일치하는 [PII 규칙](/ko/enterprise/features/agent-control-plane/rules)이 활성화된 경우 `Yes`. |
|
||||
| **Executions** | 윈도우 내 총 실행 수. |
|
||||
| **Last updated** | deployment의 마지막 재배포 시점. |
|
||||
| **Crew Version** | deployment가 보고한 `crewai` 버전. `1.13` 미만 버전 옆의 정보 아이콘은 메트릭에 기여할 수 없는 행을 표시합니다. |
|
||||
|
||||
이름으로 검색하고 `Status`(`Healthy` / `Warning` / `Critical`)로 필터링하며, 컬럼 헤더로 정렬할 수 있습니다. deployment 이름을 클릭하면 **Automation 패널**이 열립니다.
|
||||
|
||||
## Consumption 테이블
|
||||
|
||||
**Consumption** 서브 탭은 deployment 단위의 LLM 지출 및 토큰 사용량 분해입니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| 열 | 표시 내용 |
|
||||
|--------|---------------|
|
||||
| **Automation** | deployment 이름. |
|
||||
| **Last execution** | 가장 최근 실행 이후 경과 시간. |
|
||||
| **Tokens used** | 이 자동화가 사용한 LLM 공급자별로 한 행, 이전 기간 대비 변화량 포함. |
|
||||
| **Cost** | LLM 공급자별 비용, 이전 기간 대비 변화량 포함. |
|
||||
| **Total cost** | 모든 공급자의 합계, 변화량 포함. |
|
||||
| **Executions** | 윈도우 내 총 실행 수. |
|
||||
| **Last updated** | deployment의 마지막 재배포 시점. |
|
||||
| **Crew Version** | deployment가 보고한 `crewai` 버전. |
|
||||
|
||||
**LLM provider**로 필터링하고 `Cost`, `Executions` 또는 `Last run`으로 정렬할 수 있습니다.
|
||||
|
||||
<Info>
|
||||
**빈 셀(`—` 또는 `$0.00`)은 보통 deployment가 crewAI v1.13 미만임을 의미합니다.** 위 스크린샷에서 *Automation F*(`1.7.0`)와 *Automation I*(`1.12.2`)는 토큰과 비용이 비어 있습니다. 실행은 여전히 동작하지만, 이 테이블을 채우는 공급자 수준 텔레메트리를 emit하지 않습니다. 이 crew들을 업데이트하고 재배포하면 소비 데이터가 수집되기 시작합니다.
|
||||
</Info>
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — 개요" icon="book-open" href="/ko/enterprise/features/agent-control-plane/overview">
|
||||
ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — 규칙" icon="shield-check" href="/ko/enterprise/features/agent-control-plane/rules">
|
||||
조직 단위 PII Redaction 규칙을 여러 자동화에 적용합니다.
|
||||
</Card>
|
||||
<Card title="Traces" icon="timeline" href="/ko/enterprise/features/traces">
|
||||
개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다.
|
||||
</Card>
|
||||
<Card title="AMP에 배포" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
Agent Control Plane에서 메트릭을 해석하는 데 도움이 필요하시면 지원 팀에 문의하세요.
|
||||
</Card>
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Agent Control Plane 개요
|
||||
description: "라이브 자동화의 통합 운영 허브 — 플릿 상태, LLM 소비, 조직 단위 정책을 한 화면에서."
|
||||
sidebarTitle: 개요
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (베타) 문서 내비게이션**
|
||||
|
||||
- **개요** *(현재 페이지)*
|
||||
- [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
|
||||
- [규칙](/ko/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## 개요
|
||||
|
||||
**Agent Control Plane**(ACP)은 CrewAI AMP에서 실행 중인 모든 워크로드를 위한 운영 허브입니다. **Automations**와 **Rules** 두 개의 탭으로 구성된 단일 화면에서 다음 작업을 할 수 있습니다:
|
||||
|
||||
- 모든 라이브 자동화(crew 또는 flow)의 **상태(health)**를 `Critical` / `Warning` / `Healthy` 분포와 실행 횟수로 모니터링합니다.
|
||||
- 자동화별·공급자별·모델별 **LLM 소비**(토큰 및 비용)를 추적하고, 이전 기간 대비 변화량을 확인합니다.
|
||||
- 임의의 자동화 또는 모델 공급자를 드릴다운하여 시계열 차트와 공급자별 분해를 살펴봅니다.
|
||||
- 조직 전체에 **규칙(Rules)**(현재: PII Redaction)을 적용하여 각 deployment를 개별 편집하지 않고 한 번에 여러 자동화에 정책을 강제합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Note>
|
||||
Agent Control Plane은 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다.
|
||||
</Note>
|
||||
|
||||
두 탭은 서로 다른 두 가지 질문에 답합니다:
|
||||
|
||||
- **Automations** — *"지금 내 플릿은 어떻게 동작하고 있고, 얼마나 비용이 들고 있는가?"* [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)을 참고하세요.
|
||||
- **Rules** — *"정책(예: PII redaction)을 매번 재배포하지 않고 여러 deployment에 어떻게 강제할 수 있는가?"* [규칙](/ko/enterprise/features/agent-control-plane/rules)을 참고하세요.
|
||||
|
||||
## 요구사항
|
||||
|
||||
<Warning>
|
||||
이 페이지에서 자동화에 대한 데이터(상태, 실행, 오류, 토큰, 비용)를 채우려면 **crewAI v1.13 이상**이 필요합니다. 모든 데이터는 `crewai==1.13`에서 활성화된 텔레메트리를 통해 흘러갑니다. 그 이전 deployment는 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 행에도 데이터를 기여하지 않습니다.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
[규칙](/ko/enterprise/features/agent-control-plane/rules)을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 표시됩니다. 모니터링(Automations 탭)은 기능이 활성화된 모든 플랜에서 사용할 수 있습니다.
|
||||
</Warning>
|
||||
|
||||
- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. 사이드바에 보이지 않으면 계정 오너에게 활성화를 요청하세요.
|
||||
- ACP 내부에서는 [RBAC](/ko/enterprise/features/rbac)가 접근 권한을 관리합니다: 대시보드 및 규칙을 보려면 `read`, 규칙을 생성·편집·토글·삭제하려면 `manage` 권한이 필요합니다.
|
||||
- 모든 차트와 테이블은 오른쪽 상단의 시간 선택기를 통해 **지난 24시간**, **지난 1주**, **지난 30일**로 범위를 조정할 수 있습니다. 변화량(`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday` 등)은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다.
|
||||
|
||||
## 여기에서 할 수 있는 일
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="모니터링" icon="gauge" href="/ko/enterprise/features/agent-control-plane/monitoring">
|
||||
메트릭 카드, 인터랙티브 sankey, 자동화별 테이블, 자동화 또는 공급자별 드릴다운 사이드 패널로 플릿 상태와 LLM 지출을 살펴봅니다.
|
||||
</Card>
|
||||
<Card title="규칙" icon="shield-check" href="/ko/enterprise/features/agent-control-plane/rules">
|
||||
도구와 태그로 범위를 지정한 PII Redaction 정책을 조직 단위로 적용합니다. 변경 사항은 다음 실행부터 적용되며 재배포가 필요 없습니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Traces" icon="timeline" href="/ko/enterprise/features/traces">
|
||||
개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/ko/enterprise/features/rbac">
|
||||
누가 Agent Control Plane을 읽을 수 있고 누가 규칙을 편집할 수 있는지 관리합니다.
|
||||
</Card>
|
||||
<Card title="Traces용 PII Redaction" icon="lock" href="/ko/enterprise/features/pii-trace-redactions">
|
||||
규칙이 참조하는 엔티티 카탈로그 및 deployment 단위 PII 설정.
|
||||
</Card>
|
||||
<Card title="AMP에 배포" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
메트릭 해석 또는 규칙 설계에 도움이 필요하시면 지원 팀에 문의하세요.
|
||||
</Card>
|
||||
122
docs/edge/ko/enterprise/features/agent-control-plane/rules.mdx
Normal file
122
docs/edge/ko/enterprise/features/agent-control-plane/rules.mdx
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "규칙 설정하기"
|
||||
description: "한 곳에서 조직 단위 정책을 여러 자동화에 적용합니다."
|
||||
sidebarTitle: "규칙"
|
||||
icon: "shield-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (베타) 문서 내비게이션**
|
||||
|
||||
- [개요](/ko/enterprise/features/agent-control-plane/overview)
|
||||
- [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
|
||||
- **규칙** *(현재 페이지)*
|
||||
</Info>
|
||||
|
||||
## 개요
|
||||
|
||||
규칙(Rules)은 각 deployment를 개별 설정하는 대신, 정책 — 현재: **PII Redaction** — 을 한 번에 여러 자동화에 적용할 수 있게 해줍니다. 관리하려면 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)에서 **Rules** 탭을 엽니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
각 규칙 카드에는 이름, 설명, 규칙이 적용되는 **범위(scope)**(선택된 도구와 태그), 그리고 현재 범위와 일치하는 deployment의 수인 **engaged automations**가 표시됩니다. 오른쪽 토글로 규칙을 삭제하지 않고 활성/비활성할 수 있습니다.
|
||||
|
||||
## 요구사항
|
||||
|
||||
<Warning>
|
||||
PII Redaction 규칙을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수는 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 렌더링됩니다. 업그레이드하려면 계정 오너 또는 영업팀에 문의하세요.
|
||||
</Warning>
|
||||
|
||||
- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요.
|
||||
- 규칙을 생성·편집·토글·삭제하려면 Agent Control Plane에 대한 [RBAC](/ko/enterprise/features/rbac)의 `manage` 권한이 필요합니다. 보려면 `read` 권한만으로 충분합니다.
|
||||
- 모든 규칙 변경은 감사를 위해 버전 관리됩니다.
|
||||
|
||||
## 사용 가능한 규칙 유형
|
||||
|
||||
| 유형 | 동작 |
|
||||
|------|---------------|
|
||||
| **PII Redaction** | 일치하는 모든 자동화의 실행에 PII redaction을 적용합니다. [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)에 문서화된 동일한 엔티티 카탈로그와 커스텀 recognizer를 사용합니다. |
|
||||
|
||||
향후 더 많은 규칙 유형이 추가될 예정입니다.
|
||||
|
||||
## 규칙 만들기
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/acp-rules-edit-side-panel.png" alt="조건 및 PII 마스크 유형이 있는 규칙 편집 사이드 패널" width="450" />
|
||||
</Frame>
|
||||
|
||||
<Steps>
|
||||
<Step title="편집기 열기">
|
||||
Rules 탭 오른쪽 상단의 **+ Create new**를 클릭하거나, 기존 규칙 카드의 **View Details**를 클릭합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="규칙 이름과 설명 작성">
|
||||
규칙에 명확한 이름(예: *Mask PII (CC)*)과 적용 시점을 설명하는 description을 부여합니다. 둘 다 규칙 카드와 Engaged Automations 모달에 표시됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="유형 선택">
|
||||
현재 **PII Redaction**만 사용할 수 있습니다.
|
||||
</Step>
|
||||
|
||||
<Step title="조건 설정">
|
||||
조건은 규칙이 어떤 자동화에 engage 할지 결정합니다. 둘 다 선택 사항이며 **집합 동일성(set-equality)** 의미론을 사용합니다:
|
||||
|
||||
- **Tools** — 도구 집합이 선택된 도구와 **정확히 일치**하는 자동화만 engage 됩니다. Studio 앱, MCP, OSS 도구, Tool Repository registry 도구 중에서 선택합니다.
|
||||
- **Automations** — 태그 집합이 선택된 태그와 **정확히 일치**하는 자동화만 engage 됩니다.
|
||||
|
||||
피커를 비워두면 "이 차원에서 필터링하지 않음"을 의미합니다. 두 피커를 모두 비워두면 규칙이 조직의 **모든** 자동화에 적용됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="PII Mask Type 테이블 구성">
|
||||
적용할 각 엔티티 유형을 체크하고 **Mask**(엔티티 레이블로 치환, 예: `<CREDIT_CARD>`) 또는 **Redact**(일치하는 텍스트를 완전히 제거) 중에서 선택합니다. 전체 엔티티 카탈로그와 조직 단위 커스텀 recognizer 추가 방법은 [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)을 참고하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="저장">
|
||||
저장하는 즉시 engage 된 모든 자동화의 **향후** 실행에 규칙이 적용됩니다. 재배포는 필요 없습니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Engaged automations
|
||||
|
||||
규칙 카드의 **Engaged N automations**를 클릭하면 현재 규칙이 일치시키고 있는 deployment와 각 deployment의 마지막 실행을 정확히 확인할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
규칙을 활성화하기 전에 범위를 빠르게 점검하는 가장 좋은 방법입니다. 예를 들어, `production` 태그로 범위를 지정한 규칙이 의도치 않게 staging deployment를 일치시키지 않는지 확인할 수 있습니다.
|
||||
|
||||
## 조직 단위 규칙 vs deployment 단위 설정
|
||||
|
||||
PII Redaction은 두 곳에서 설정할 수 있습니다:
|
||||
|
||||
- **deployment 단위** — 각 deployment의 **Settings → PII Protection** ([가이드](/ko/enterprise/features/pii-trace-redactions))
|
||||
- **조직 단위** — 이 페이지의 규칙
|
||||
|
||||
활성화된 조직 단위 규칙의 범위가 어떤 deployment와 일치하면, 규칙의 엔티티 구성이 그 deployment의 실행에 대해 **deployment가 소유한 PII 설정을 덮어씁니다**. 규칙이 연결된 동안에는 규칙이 단일 진실 공급원이 됩니다. 규칙을 비활성화하거나 분리하면(또는 범위를 변경하여 더 이상 일치하지 않게 만들면) deployment는 자체 PII Protection 설정으로 되돌아갑니다.
|
||||
|
||||
여러 deployment에 걸쳐 일관된 정책을 강제하고 싶을 때는 조직 단위 규칙을 선호하고, 일회성 예외에 대해서는 deployment 단위 설정을 사용하세요.
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — 개요" icon="book-open" href="/ko/enterprise/features/agent-control-plane/overview">
|
||||
ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — 모니터링" icon="gauge" href="/ko/enterprise/features/agent-control-plane/monitoring">
|
||||
플릿 전반의 자동화와 LLM 소비를 모니터링합니다.
|
||||
</Card>
|
||||
<Card title="Traces용 PII Redaction" icon="lock" href="/ko/enterprise/features/pii-trace-redactions">
|
||||
엔티티 카탈로그, 커스텀 recognizer, deployment 단위 구성.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/ko/enterprise/features/rbac">
|
||||
누가 규칙을 만들거나 편집할 수 있는지 관리합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
조직의 규칙을 설계하는 데 도움이 필요하시면 지원 팀에 문의하세요.
|
||||
</Card>
|
||||
158
docs/edge/ko/enterprise/features/agent-repositories.mdx
Normal file
158
docs/edge/ko/enterprise/features/agent-repositories.mdx
Normal file
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: '에이전트 저장소'
|
||||
description: '에이전트 저장소를 사용하여 팀과 프로젝트 전반에 걸쳐 에이전트를 공유하고 재사용하는 방법을 알아보세요'
|
||||
icon: 'database'
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
생각: 이제 훌륭한 답변을 드릴 수 있습니다.
|
||||
최종 답변:
|
||||
Agent Repositories는 엔터프라이즈 사용자가 팀과 프로젝트 전반에 걸쳐 agent 정의를 저장, 공유, 재사용할 수 있도록 합니다. 이 기능을 통해 조직은 표준화된 agent의 중앙 라이브러리를 유지할 수 있어 일관성을 높이고 중복 작업을 줄일 수 있습니다.
|
||||
|
||||
## 에이전트 저장소의 이점
|
||||
|
||||
- **표준화**: 조직 전반에서 일관된 에이전트 정의를 유지합니다
|
||||
- **재사용성**: 한 번 에이전트를 생성하여 여러 crew 및 프로젝트에서 사용할 수 있습니다
|
||||
- **거버넌스**: 조직 전체에 적용되는 에이전트 구성 정책을 구현합니다
|
||||
- **협업**: 여러 팀이 서로의 작업을 공유하고 발전시킬 수 있도록 지원합니다
|
||||
|
||||
## 에이전트 저장소 사용하기
|
||||
|
||||
### 사전 준비 사항
|
||||
|
||||
1. CrewAI 계정이 있어야 하며, [무료 플랜](https://app.crewai.com)을 이용해보세요.
|
||||
2. CrewAI CLI를 사용하여 인증되어 있어야 합니다.
|
||||
3. 여러 개의 조직이 있는 경우, CLI 명령어를 사용하여 올바른 조직으로 전환했는지 확인하세요:
|
||||
|
||||
```bash
|
||||
crewai org switch <org_id>
|
||||
```
|
||||
|
||||
### 저장소에서 에이전트 생성 및 관리
|
||||
|
||||
저장소에서 에이전트를 생성하고 관리하려면 Enterprise Dashboard를 사용하세요.
|
||||
|
||||
### 리포지토리에서 에이전트 불러오기
|
||||
|
||||
코드에서 `from_repository` 파라미터를 사용하여 리포지토리에서 에이전트를 불러올 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
# Create an agent by loading it from a repository
|
||||
# The agent is loaded with all its predefined configurations
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent"
|
||||
)
|
||||
|
||||
```
|
||||
|
||||
### 저장소 설정 재정의
|
||||
|
||||
구성에서 특정 설정을 제공하여 저장소의 설정을 재정의할 수 있습니다.
|
||||
|
||||
```python
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent",
|
||||
goal="Research the latest trends in AI development", # Override the repository goal
|
||||
verbose=True # Add a setting not in the repository
|
||||
)
|
||||
```
|
||||
|
||||
### 예제: Repository 에이전트로 Crew 생성하기
|
||||
|
||||
```python
|
||||
from crewai import Crew, Agent, Task
|
||||
|
||||
# Load agents from repositories
|
||||
researcher = Agent(
|
||||
from_repository="market-research-agent"
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
from_repository="content-writer-agent"
|
||||
)
|
||||
|
||||
# Create tasks
|
||||
research_task = Task(
|
||||
description="Research the latest trends in AI",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description="Write a comprehensive report based on the research",
|
||||
agent=writer
|
||||
)
|
||||
|
||||
# Create the crew
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run the crew
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
### 예시: `kickoff()`를 Repository Agent와 함께 사용하기
|
||||
|
||||
`kickoff()` 메서드를 이용해 repository agent를 직접 사용하여 보다 간단하게 상호작용할 수도 있습니다:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
|
||||
# 구조화된 출력 형식 정의
|
||||
class MarketAnalysis(BaseModel):
|
||||
key_trends: List[str]
|
||||
opportunities: List[str]
|
||||
recommendation: str
|
||||
|
||||
# 저장소에서 agent 불러오기
|
||||
analyst = Agent(
|
||||
from_repository="market-analyst-agent",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# 자유 형식 응답 받기
|
||||
result = analyst.kickoff("Analyze the AI market in 2025")
|
||||
print(result.raw) # 원시 응답 접근
|
||||
|
||||
# 구조화된 출력 받기
|
||||
structured_result = analyst.kickoff(
|
||||
"Provide a structured analysis of the AI market in 2025",
|
||||
response_format=MarketAnalysis
|
||||
)
|
||||
|
||||
# 구조화된 데이터 접근
|
||||
print(f"Key Trends: {structured_result.pydantic.key_trends}")
|
||||
print(f"Recommendation: {structured_result.pydantic.recommendation}")
|
||||
```
|
||||
|
||||
## 모범 사례
|
||||
|
||||
1. **명명 규칙**: 리포지토리 에이전트에 대해 명확하고 설명적인 이름을 사용하세요.
|
||||
2. **문서화**: 각 에이전트에 대한 포괄적인 설명을 포함하세요.
|
||||
3. **도구 관리**: 리포지토리 에이전트가 참조하는 도구들이 환경에 제공되는지 확인하세요.
|
||||
4. **접근 제어**: 권한이 있는 팀원만 리포지토리 에이전트를 수정할 수 있도록 권한을 관리하세요.
|
||||
|
||||
## 조직 관리
|
||||
|
||||
조직을 전환하거나 현재 조직을 확인하려면 CrewAI CLI를 사용하세요:
|
||||
|
||||
```bash
|
||||
# 현재 조직 보기
|
||||
crewai org current
|
||||
|
||||
# 다른 조직으로 전환
|
||||
crewai org switch <org_id>
|
||||
|
||||
# 사용 가능한 모든 조직 목록 확인
|
||||
crewai org list
|
||||
```
|
||||
|
||||
<Note>
|
||||
리포지토리에서 agent를 불러올 때는 인증이 완료되어 있어야 하며, 올바른 조직으로 전환되어 있어야 합니다. 오류가 발생하면 위의 CLI 명령어를 사용하여 인증 상태와 조직 설정을 확인하세요.
|
||||
</Note>
|
||||
103
docs/edge/ko/enterprise/features/automations.mdx
Normal file
103
docs/edge/ko/enterprise/features/automations.mdx
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: "자동화"
|
||||
description: "배포된 크루(자동화)를 한 곳에서 관리, 배포 및 모니터링하세요."
|
||||
icon: "rocket"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
자동화는 배포된 크루를 운영하는 허브입니다. GitHub 또는 ZIP으로 배포하고, 환경 변수를 관리하고, 필요 시 재배포하며 각 자동화의 상태를 모니터링하세요.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 배포 방법
|
||||
|
||||
### GitHub로 배포
|
||||
|
||||
버전 관리 및 지속적 배포에 적합합니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="GitHub 연결">
|
||||
<b>Configure GitHub</b>를 클릭하고 접근을 승인합니다.
|
||||
</Step>
|
||||
<Step title="리포지토리 & 브랜치 선택">
|
||||
배포할 <b>리포지토리</b>와 <b>브랜치</b>를 선택합니다.
|
||||
</Step>
|
||||
<Step title="자동 배포 활성화(선택)">
|
||||
<b>Automatically deploy new commits</b>를 켜면 푸시 시마다 자동 배포됩니다.
|
||||
</Step>
|
||||
<Step title="환경 변수 추가">
|
||||
개별로 추가하거나 <b>Bulk View</b>를 사용해 여러 변수를 한 번에 추가합니다.
|
||||
</Step>
|
||||
<Step title="배포">
|
||||
<b>Deploy</b>를 클릭해 라이브 자동화를 생성합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### ZIP으로 배포
|
||||
|
||||
Git 없이 빠르게 배포 — 프로젝트 ZIP 패키지를 업로드하세요.
|
||||
|
||||
<Steps>
|
||||
<Step title="파일 선택">
|
||||
컴퓨터에서 ZIP 파일을 선택합니다.
|
||||
</Step>
|
||||
<Step title="환경 변수 추가">
|
||||
필요한 변수를 제공합니다.
|
||||
</Step>
|
||||
<Step title="배포">
|
||||
<b>Deploy</b>를 클릭해 라이브 자동화를 생성합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 자동화 대시보드
|
||||
|
||||
테이블에는 모든 라이브 자동화가 다음 정보와 함께 표시됩니다:
|
||||
|
||||
- **CREW**: 자동화 이름
|
||||
- **STATUS**: Online / Failed / In Progress
|
||||
- **URL**: kickoff/status 엔드포인트
|
||||
- **TOKEN**: 자동화 토큰
|
||||
- **ACTIONS**: 재배포, 삭제 등
|
||||
|
||||
우측 상단 컨트롤로 필터 및 검색:
|
||||
|
||||
- 이름으로 검색
|
||||
- <b>Status</b>로 필터
|
||||
- <b>Source</b>로 필터 (GitHub / Studio / ZIP)
|
||||
|
||||
배포 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 모범 사례
|
||||
|
||||
- 버전 관리 및 CI/CD를 위해 GitHub 배포를 권장
|
||||
- 코드/구성 변경 후 재배포 사용 또는 푸시마다 자동 배포 설정
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="크루 배포" href="/ko/enterprise/guides/deploy-to-amp" icon="rocket">
|
||||
GitHub 또는 ZIP 파일로 크루 배포
|
||||
</Card>
|
||||
<Card title="자동화 트리거" href="/ko/enterprise/guides/automation-triggers" icon="trigger">
|
||||
웹훅 또는 API로 자동화 트리거
|
||||
</Card>
|
||||
<Card title="Webhook 자동화" href="/ko/enterprise/guides/webhook-automation" icon="webhook">
|
||||
실시간 이벤트/업데이트 스트리밍
|
||||
</Card>
|
||||
</CardGroup>
|
||||
88
docs/edge/ko/enterprise/features/crew-studio.mdx
Normal file
88
docs/edge/ko/enterprise/features/crew-studio.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Crew Studio"
|
||||
description: "AI 보조, 비주얼 에디터, 통합 테스트로 새로운 자동화를 구축하세요."
|
||||
icon: "pencil"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Crew Studio는 자연어와 시각적 워크플로 에디터로 처음부터 자동화를 만드는 인터랙티브한 AI 보조 작업 공간입니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 프롬프트 기반 생성
|
||||
|
||||
- 원하는 자동화를 설명하면, AI가 에이전트/태스크/도구를 생성합니다.
|
||||
- 마이크 아이콘으로 음성 입력을 사용할 수 있습니다.
|
||||
- 공통 사용 사례용 프롬프트 템플릿으로 시작할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 비주얼 에디터
|
||||
|
||||
캔버스는 노드/엣지 형태로 플로우를 표현하며, 세 개의 보조 패널로 코드 없이 쉽게 구성할 수 있습니다 (일명 "vibe coding AI Agents"):
|
||||
|
||||
- **AI Thoughts (좌측)**: 설계 중 스트리밍 추론
|
||||
- **Canvas (중앙)**: 에이전트/태스크 노드와 연결
|
||||
- **Resources (우측)**: 드래그앤드롭 컴포넌트 (에이전트, 태스크, 도구)
|
||||
|
||||
드래그앤드롭으로 캔버스를 구성하거나, 채팅 섹션으로 에이전트를 생성할 수 있으며 두 방식은 상태를 공유합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 실행 & 디버깅
|
||||
|
||||
<b>Execution</b> 뷰로 전환하여 실행을 관찰하세요:
|
||||
|
||||
- 이벤트 타임라인
|
||||
- 상세 로그 (Details, Messages, Raw Data)
|
||||
- 게시 전 로컬 실행
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 게시 & 내보내기
|
||||
|
||||
- <b>Publish</b>로 라이브 자동화 배포
|
||||
- <b>Download</b>로 소스 ZIP 다운로드 (로컬 개발용)
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
게시 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 모범 사례
|
||||
|
||||
- Studio에서 빠르게 반복하고, 안정화 후 게시
|
||||
- 도구 권한은 최소한으로 제한
|
||||
- Traces로 동작/성능 검증
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={4}>
|
||||
<Card title="Crew Studio 활성화" href="/ko/enterprise/guides/enable-crew-studio" icon="palette">
|
||||
Crew Studio를 활성화하세요.
|
||||
</Card>
|
||||
<Card title="크루 빌드" href="/ko/enterprise/guides/build-crew" icon="paintbrush">
|
||||
크루를 빌드하세요.
|
||||
</Card>
|
||||
<Card title="크루 배포" href="/ko/enterprise/guides/deploy-to-amp" icon="rocket">
|
||||
GitHub 또는 ZIP 파일로 크루 배포.
|
||||
</Card>
|
||||
<Card title="React 컴포넌트 내보내기" href="/ko/enterprise/guides/react-component-export" icon="download">
|
||||
React 컴포넌트를 내보내세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
558
docs/edge/ko/enterprise/features/flow-hitl-management.mdx
Normal file
558
docs/edge/ko/enterprise/features/flow-hitl-management.mdx
Normal file
@@ -0,0 +1,558 @@
|
||||
---
|
||||
title: "Flow HITL 관리"
|
||||
description: "이메일 우선 알림, 라우팅 규칙 및 자동 응답 기능을 갖춘 Flow용 엔터프라이즈급 인간 검토"
|
||||
icon: "users-gear"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Flow HITL 관리 기능은 `@human_feedback` 데코레이터가 필요하며, **CrewAI 버전 1.8.0 이상**에서 사용할 수 있습니다. 이 기능은 Crew가 아닌 **Flow**에만 적용됩니다.
|
||||
</Note>
|
||||
|
||||
CrewAI Enterprise는 AI 워크플로우를 협업적인 인간-AI 프로세스로 전환하는 Flow용 포괄적인 Human-in-the-Loop(HITL) 관리 시스템을 제공합니다. 플랫폼은 **이메일 우선 아키텍처**를 사용하여 이메일 주소가 있는 누구나 플랫폼 계정 없이도 검토 요청에 응답할 수 있습니다.
|
||||
|
||||
## 개요
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="이메일 우선 설계" icon="envelope">
|
||||
응답자가 알림 이메일에 직접 회신하여 피드백 제공 가능
|
||||
</Card>
|
||||
<Card title="유연한 라우팅" icon="route">
|
||||
메서드 패턴 또는 Flow 상태에 따라 특정 이메일로 요청 라우팅
|
||||
</Card>
|
||||
<Card title="자동 응답" icon="clock">
|
||||
시간 내에 인간이 응답하지 않을 경우 자동 대체 응답 구성
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### 주요 이점
|
||||
|
||||
- **간단한 멘탈 모델**: 이메일 주소는 보편적이며 플랫폼 사용자나 역할을 관리할 필요 없음
|
||||
- **외부 응답자**: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
|
||||
- **동적 할당**: Flow 상태에서 직접 담당자 이메일 가져오기 (예: `sales_rep_email`)
|
||||
- **간소화된 구성**: 설정할 항목이 적어 더 빠르게 가치 실현
|
||||
- **이메일이 주요 채널**: 대부분의 사용자는 대시보드 로그인보다 이메일로 응답하는 것을 선호
|
||||
|
||||
## Flow에서 인간 검토 포인트 설정
|
||||
|
||||
`@human_feedback` 데코레이터를 사용하여 Flow 내에 인간 검토 체크포인트를 구성합니다. 실행이 검토 포인트에 도달하면 시스템이 일시 중지되고, 담당자에게 이메일로 알리며, 응답을 기다립니다.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start, listen, or_
|
||||
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
|
||||
|
||||
class ContentApprovalFlow(Flow):
|
||||
@start()
|
||||
def generate_content(self):
|
||||
return "Q1 캠페인용 마케팅 카피 생성..."
|
||||
|
||||
@human_feedback(
|
||||
message="브랜드 준수를 위해 이 콘텐츠를 검토해 주세요:",
|
||||
emit=["approved", "rejected", "needs_revision"],
|
||||
)
|
||||
@listen(or_("generate_content", "needs_revision"))
|
||||
def review_content(self):
|
||||
return "검토용 마케팅 카피..."
|
||||
|
||||
@listen("approved")
|
||||
def publish_content(self, result: HumanFeedbackResult):
|
||||
print(f"승인된 콘텐츠 게시 중. 검토자 노트: {result.feedback}")
|
||||
|
||||
@listen("rejected")
|
||||
def archive_content(self, result: HumanFeedbackResult):
|
||||
print(f"콘텐츠 거부됨. 사유: {result.feedback}")
|
||||
```
|
||||
|
||||
완전한 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요.
|
||||
|
||||
### 데코레이터 파라미터
|
||||
|
||||
| 파라미터 | 유형 | 설명 |
|
||||
|---------|------|------|
|
||||
| `message` | `str` | 인간 검토자에게 표시되는 메시지 |
|
||||
| `emit` | `list[str]` | 유효한 응답 옵션 (UI에서 버튼으로 표시) |
|
||||
|
||||
## 플랫폼 구성
|
||||
|
||||
HITL 구성에 접근: **배포** → **설정** → **Human in the Loop 구성**
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-overview.png" alt="HITL 구성 설정" />
|
||||
</Frame>
|
||||
|
||||
### 이메일 알림
|
||||
|
||||
HITL 요청에 대한 이메일 알림을 활성화하거나 비활성화하는 토글입니다.
|
||||
|
||||
| 설정 | 기본값 | 설명 |
|
||||
|-----|-------|------|
|
||||
| 이메일 알림 | 활성화됨 | 피드백 요청 시 이메일 전송 |
|
||||
|
||||
<Note>
|
||||
비활성화되면 응답자는 대시보드 UI를 사용하거나 커스텀 알림 시스템을 위해 webhook을 구성해야 합니다.
|
||||
</Note>
|
||||
|
||||
### SLA 목표
|
||||
|
||||
추적 및 메트릭 목적으로 목표 응답 시간을 설정합니다.
|
||||
|
||||
| 설정 | 설명 |
|
||||
|-----|------|
|
||||
| SLA 목표 (분) | 목표 응답 시간. 대시보드 메트릭 및 SLA 추적에 사용 |
|
||||
|
||||
SLA 추적을 비활성화하려면 비워 두세요.
|
||||
|
||||
## 이메일 알림 및 응답
|
||||
|
||||
HITL 시스템은 응답자가 알림 이메일에 직접 회신할 수 있는 이메일 우선 아키텍처를 사용합니다.
|
||||
|
||||
### 이메일 응답 작동 방식
|
||||
|
||||
<Steps>
|
||||
<Step title="알림 전송">
|
||||
HITL 요청이 생성되면 검토 콘텐츠와 컨텍스트가 포함된 이메일이 할당된 응답자에게 전송됩니다.
|
||||
</Step>
|
||||
<Step title="Reply-To 주소">
|
||||
이메일에는 인증을 위한 서명된 토큰이 포함된 특별한 reply-to 주소가 있습니다.
|
||||
</Step>
|
||||
<Step title="사용자 회신">
|
||||
응답자는 이메일에 피드백으로 회신하면 됩니다—로그인 필요 없음.
|
||||
</Step>
|
||||
<Step title="토큰 검증">
|
||||
플랫폼이 회신을 받고, 서명된 토큰을 확인하고, 발신자 이메일을 매칭합니다.
|
||||
</Step>
|
||||
<Step title="Flow 재개">
|
||||
피드백이 기록되고 인간의 입력으로 Flow가 계속됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 응답 형식
|
||||
|
||||
응답자는 다음과 같이 회신할 수 있습니다:
|
||||
|
||||
- **Emit 옵션**: 회신이 `emit` 옵션과 일치하면 (예: "approved") 직접 사용됨
|
||||
- **자유 형식 텍스트**: 모든 텍스트 응답이 피드백으로 Flow에 전달됨
|
||||
- **일반 텍스트**: 회신 본문의 첫 번째 줄이 피드백으로 사용됨
|
||||
|
||||
### 확인 이메일
|
||||
|
||||
회신을 처리한 후 응답자는 피드백이 성공적으로 제출되었는지 또는 오류가 발생했는지 나타내는 확인 이메일을 받습니다.
|
||||
|
||||
### 이메일 토큰 보안
|
||||
|
||||
- 토큰은 보안을 위해 암호화 서명됨
|
||||
- 토큰은 7일 후 만료됨
|
||||
- 발신자 이메일은 토큰의 인증된 이메일과 일치해야 함
|
||||
- 처리 후 확인/오류 이메일 전송됨
|
||||
|
||||
## 라우팅 규칙
|
||||
|
||||
메서드 패턴에 따라 HITL 요청을 특정 이메일 주소로 라우팅합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL 라우팅 규칙 구성" />
|
||||
</Frame>
|
||||
|
||||
### 규칙 구조
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "재무팀으로 승인",
|
||||
"match": {
|
||||
"method_name": "approve_*"
|
||||
},
|
||||
"assign_to_email": "finance@company.com",
|
||||
"assign_from_input": "manager_email"
|
||||
}
|
||||
```
|
||||
|
||||
### 매칭 패턴
|
||||
|
||||
| 패턴 | 설명 | 매칭 예시 |
|
||||
|-----|------|----------|
|
||||
| `approve_*` | 와일드카드 (모든 문자) | `approve_payment`, `approve_vendor` |
|
||||
| `review_?` | 단일 문자 | `review_a`, `review_1` |
|
||||
| `validate_payment` | 정확히 일치 | `validate_payment`만 |
|
||||
|
||||
### 할당 우선순위
|
||||
|
||||
1. **동적 할당** (`assign_from_input`): 구성된 경우 Flow 상태에서 이메일 가져옴
|
||||
2. **정적 이메일** (`assign_to_email`): 구성된 이메일로 대체
|
||||
3. **배포 생성자**: 규칙이 일치하지 않으면 배포 생성자의 이메일이 사용됨
|
||||
|
||||
### 동적 할당 예제
|
||||
|
||||
Flow 상태에 `{"sales_rep_email": "alice@company.com"}`이 포함된 경우:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "영업 담당자에게 라우팅",
|
||||
"match": {
|
||||
"method_name": "review_*"
|
||||
},
|
||||
"assign_from_input": "sales_rep_email"
|
||||
}
|
||||
```
|
||||
|
||||
요청이 자동으로 `alice@company.com`에 할당됩니다.
|
||||
|
||||
<Tip>
|
||||
**사용 사례**: CRM, 데이터베이스 또는 이전 Flow 단계에서 담당자를 가져와 적합한 사람에게 검토를 동적으로 라우팅하세요.
|
||||
</Tip>
|
||||
|
||||
## 자동 응답
|
||||
|
||||
시간 내에 인간이 응답하지 않으면 HITL 요청에 자동으로 응답합니다. 이를 통해 Flow가 무한정 중단되지 않도록 합니다.
|
||||
|
||||
### 구성
|
||||
|
||||
| 설정 | 설명 |
|
||||
|-----|------|
|
||||
| 활성화됨 | 자동 응답 활성화 토글 |
|
||||
| 타임아웃 (분) | 자동 응답 전 대기 시간 |
|
||||
| 기본 결과 | 응답 값 (`emit` 옵션과 일치해야 함) |
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL 자동 응답 구성" />
|
||||
</Frame>
|
||||
|
||||
### 사용 사례
|
||||
|
||||
- **SLA 준수**: Flow가 무한정 중단되지 않도록 보장
|
||||
- **기본 승인**: 타임아웃 후 저위험 요청 자동 승인
|
||||
- **우아한 저하**: 검토자가 없을 때 안전한 기본값으로 계속
|
||||
|
||||
<Warning>
|
||||
자동 응답을 신중하게 사용하세요. 기본 응답이 허용되는 중요하지 않은 검토에만 활성화하세요.
|
||||
</Warning>
|
||||
|
||||
## 검토 프로세스
|
||||
|
||||
### 대시보드 인터페이스
|
||||
|
||||
HITL 검토 인터페이스는 검토자에게 깔끔하고 집중된 경험을 제공합니다:
|
||||
|
||||
- **마크다운 렌더링**: 구문 강조가 포함된 풍부한 형식의 검토 콘텐츠
|
||||
- **컨텍스트 패널**: Flow 상태, 실행 기록 및 관련 정보 보기
|
||||
- **피드백 입력**: 결정과 함께 상세한 피드백 및 코멘트 제공
|
||||
- **빠른 작업**: 선택적 코멘트가 있는 원클릭 emit 옵션 버튼
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL 대기 중인 요청 목록" />
|
||||
</Frame>
|
||||
|
||||
### 응답 방법
|
||||
|
||||
검토자는 세 가지 채널을 통해 응답할 수 있습니다:
|
||||
|
||||
| 방법 | 설명 |
|
||||
|-----|------|
|
||||
| **이메일 회신** | 알림 이메일에 직접 회신 |
|
||||
| **대시보드** | Enterprise 대시보드 UI 사용 |
|
||||
| **API/Webhook** | API를 통한 프로그래밍 방식 응답 |
|
||||
|
||||
### 기록 및 감사 추적
|
||||
|
||||
모든 HITL 상호작용은 완전한 타임라인으로 추적됩니다:
|
||||
|
||||
- 결정 기록 (승인/거부/수정)
|
||||
- 검토자 신원 및 타임스탬프
|
||||
- 제공된 피드백 및 코멘트
|
||||
- 응답 방법 (이메일/대시보드/API)
|
||||
- 응답 시간 메트릭
|
||||
|
||||
## 분석 및 모니터링
|
||||
|
||||
포괄적인 분석으로 HITL 성능을 추적합니다.
|
||||
|
||||
### 성능 대시보드
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-metrics.png" alt="HITL 메트릭 대시보드" />
|
||||
</Frame>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="응답 시간" icon="stopwatch">
|
||||
검토자 또는 Flow별 평균 및 중앙값 응답 시간 모니터링.
|
||||
</Card>
|
||||
<Card title="볼륨 트렌드" icon="chart-bar">
|
||||
팀 용량 최적화를 위한 검토 볼륨 패턴 분석.
|
||||
</Card>
|
||||
<Card title="결정 분포" icon="chart-pie">
|
||||
다양한 검토 유형에 대한 승인/거부 비율 보기.
|
||||
</Card>
|
||||
<Card title="SLA 추적" icon="chart-line">
|
||||
SLA 목표 내에 완료된 검토 비율 추적.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### 감사 및 규정 준수
|
||||
|
||||
규제 요구 사항을 위한 엔터프라이즈급 감사 기능:
|
||||
|
||||
- 타임스탬프가 있는 완전한 결정 기록
|
||||
- 검토자 신원 확인
|
||||
- 불변 감사 로그
|
||||
- 규정 준수 보고를 위한 내보내기 기능
|
||||
|
||||
## 일반적인 사용 사례
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="보안 검토" icon="shield-halved">
|
||||
**사용 사례**: 인간 검증이 포함된 내부 보안 설문지 자동화
|
||||
|
||||
- AI가 보안 설문지에 대한 응답 생성
|
||||
- 보안팀이 이메일로 정확성 검토 및 검증
|
||||
- 승인된 응답이 최종 제출물로 편집
|
||||
- 규정 준수를 위한 완전한 감사 추적
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="콘텐츠 승인" icon="file-lines">
|
||||
**사용 사례**: 법무/브랜드 검토가 필요한 마케팅 콘텐츠
|
||||
|
||||
- AI가 마케팅 카피 또는 소셜 미디어 콘텐츠 생성
|
||||
- 브랜드팀 이메일로 목소리/톤 검토를 위해 라우팅
|
||||
- 승인 시 자동 게시
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="재무 승인" icon="money-bill">
|
||||
**사용 사례**: 경비 보고서, 계약 조건, 예산 배분
|
||||
|
||||
- AI가 재무 요청을 사전 처리하고 분류
|
||||
- 동적 할당을 사용하여 금액 임계값에 따라 라우팅
|
||||
- 재무 규정 준수를 위한 완전한 감사 추적 유지
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="CRM에서 동적 할당" icon="database">
|
||||
**사용 사례**: CRM에서 계정 담당자에게 검토 라우팅
|
||||
|
||||
- Flow가 CRM에서 계정 담당자 이메일 가져옴
|
||||
- 이메일을 Flow 상태에 저장 (예: `account_owner_email`)
|
||||
- `assign_from_input`을 사용하여 적합한 사람에게 자동 라우팅
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="품질 보증" icon="magnifying-glass">
|
||||
**사용 사례**: 고객 전달 전 AI 출력 검증
|
||||
|
||||
- AI가 고객 대면 콘텐츠 또는 응답 생성
|
||||
- QA팀이 이메일 알림을 통해 검토
|
||||
- 피드백 루프가 시간이 지남에 따라 AI 성능 개선
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Webhook API
|
||||
|
||||
Flow가 인간 피드백을 위해 일시 중지되면, 요청 데이터를 자체 애플리케이션으로 보내도록 webhook을 구성할 수 있습니다. 이를 통해 다음이 가능합니다:
|
||||
|
||||
- 커스텀 승인 UI 구축
|
||||
- 내부 도구와 통합 (Jira, ServiceNow, 커스텀 대시보드)
|
||||
- 타사 시스템으로 승인 라우팅
|
||||
- 모바일 앱 알림
|
||||
- 자동화된 결정 시스템
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook 구성" />
|
||||
</Frame>
|
||||
|
||||
### Webhook 구성
|
||||
|
||||
<Steps>
|
||||
<Step title="설정으로 이동">
|
||||
**배포** → **설정** → **Human in the Loop**으로 이동
|
||||
</Step>
|
||||
<Step title="Webhook 섹션 확장">
|
||||
**Webhooks** 구성을 클릭하여 확장
|
||||
</Step>
|
||||
<Step title="Webhook URL 추가">
|
||||
webhook URL 입력 (프로덕션에서는 HTTPS 필수)
|
||||
</Step>
|
||||
<Step title="구성 저장">
|
||||
**구성 저장**을 클릭하여 활성화
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
여러 webhook을 구성할 수 있습니다. 각 활성 webhook은 모든 HITL 이벤트를 수신합니다.
|
||||
|
||||
### Webhook 이벤트
|
||||
|
||||
엔드포인트는 다음 이벤트에 대해 HTTP POST 요청을 수신합니다:
|
||||
|
||||
| 이벤트 유형 | 트리거 시점 |
|
||||
|------------|------------|
|
||||
| `new_request` | Flow가 일시 중지되고 인간 피드백을 요청할 때 |
|
||||
|
||||
### Webhook 페이로드
|
||||
|
||||
모든 webhook은 다음 구조의 JSON 페이로드를 수신합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "new_request",
|
||||
"request": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"flow_id": "flow_abc123",
|
||||
"method_name": "review_article",
|
||||
"message": "이 기사의 게시를 검토해 주세요.",
|
||||
"emit_options": ["approved", "rejected", "request_changes"],
|
||||
"state": {
|
||||
"article_id": 12345,
|
||||
"author": "john@example.com",
|
||||
"category": "technology"
|
||||
},
|
||||
"metadata": {},
|
||||
"created_at": "2026-01-14T12:00:00Z"
|
||||
},
|
||||
"deployment": {
|
||||
"id": 456,
|
||||
"name": "Content Review Flow",
|
||||
"organization_id": 789
|
||||
},
|
||||
"callback_url": "https://api.crewai.com/...",
|
||||
"assigned_to_email": "reviewer@company.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 요청에 응답하기
|
||||
|
||||
피드백을 제출하려면 webhook 페이로드에 포함된 **`callback_url`로 POST**합니다.
|
||||
|
||||
```http
|
||||
POST {callback_url}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"feedback": "승인됨. 훌륭한 기사입니다!",
|
||||
"source": "my_custom_app"
|
||||
}
|
||||
```
|
||||
|
||||
### 보안
|
||||
|
||||
<Info>
|
||||
모든 webhook 요청은 HMAC-SHA256을 사용하여 암호화 서명되어 진위성을 보장하고 변조를 방지합니다.
|
||||
</Info>
|
||||
|
||||
#### Webhook 보안
|
||||
|
||||
- **HMAC-SHA256 서명**: 모든 webhook에 암호화 서명이 포함됨
|
||||
- **Webhook별 시크릿**: 각 webhook은 고유한 서명 시크릿을 가짐
|
||||
- **저장 시 암호화**: 서명 시크릿은 데이터베이스에서 암호화됨
|
||||
- **타임스탬프 검증**: 리플레이 공격 방지
|
||||
|
||||
#### 서명 헤더
|
||||
|
||||
각 webhook 요청에는 다음 헤더가 포함됩니다:
|
||||
|
||||
| 헤더 | 설명 |
|
||||
|------|------|
|
||||
| `X-Signature` | HMAC-SHA256 서명: `sha256=<hex_digest>` |
|
||||
| `X-Timestamp` | 요청이 서명된 Unix 타임스탬프 |
|
||||
|
||||
#### 검증
|
||||
|
||||
다음과 같이 계산하여 검증합니다:
|
||||
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
expected = hmac.new(
|
||||
signing_secret.encode(),
|
||||
f"{timestamp}.{payload}".encode(),
|
||||
hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
if hmac.compare_digest(expected, signature):
|
||||
# 유효한 서명
|
||||
```
|
||||
|
||||
### 오류 처리
|
||||
|
||||
webhook 엔드포인트는 수신 확인을 위해 2xx 상태 코드를 반환해야 합니다:
|
||||
|
||||
| 응답 | 동작 |
|
||||
|------|------|
|
||||
| 2xx | Webhook 성공적으로 전달됨 |
|
||||
| 4xx/5xx | 실패로 기록됨, 재시도 없음 |
|
||||
| 타임아웃 (30초) | 실패로 기록됨, 재시도 없음 |
|
||||
|
||||
## 보안 및 RBAC
|
||||
|
||||
### 대시보드 접근
|
||||
|
||||
HITL 접근은 배포 수준에서 제어됩니다:
|
||||
|
||||
| 권한 | 기능 |
|
||||
|-----|------|
|
||||
| `manage_human_feedback` | HITL 설정 구성, 모든 요청 보기 |
|
||||
| `respond_to_human_feedback` | 요청에 응답, 할당된 요청 보기 |
|
||||
|
||||
### 이메일 응답 인증
|
||||
|
||||
이메일 회신의 경우:
|
||||
1. reply-to 토큰이 인증된 이메일을 인코딩
|
||||
2. 발신자 이메일이 토큰의 이메일과 일치해야 함
|
||||
3. 토큰이 만료되지 않아야 함 (기본 7일)
|
||||
4. 요청이 여전히 대기 중이어야 함
|
||||
|
||||
### 감사 추적
|
||||
|
||||
모든 HITL 작업이 기록됩니다:
|
||||
- 요청 생성
|
||||
- 할당 변경
|
||||
- 응답 제출 (소스: 대시보드/이메일/API)
|
||||
- Flow 재개 상태
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 이메일이 전송되지 않음
|
||||
|
||||
1. 구성에서 "이메일 알림"이 활성화되어 있는지 확인
|
||||
2. 라우팅 규칙이 메서드 이름과 일치하는지 확인
|
||||
3. 담당자 이메일이 유효한지 확인
|
||||
4. 라우팅 규칙이 일치하지 않는 경우 배포 생성자 대체 확인
|
||||
|
||||
### 이메일 회신이 처리되지 않음
|
||||
|
||||
1. 토큰이 만료되지 않았는지 확인 (기본 7일)
|
||||
2. 발신자 이메일이 할당된 이메일과 일치하는지 확인
|
||||
3. 요청이 여전히 대기 중인지 확인 (아직 응답되지 않음)
|
||||
|
||||
### Flow가 재개되지 않음
|
||||
|
||||
1. 대시보드에서 요청 상태 확인
|
||||
2. 콜백 URL에 접근 가능한지 확인
|
||||
3. 배포가 여전히 실행 중인지 확인
|
||||
|
||||
## 모범 사례
|
||||
|
||||
<Tip>
|
||||
**간단하게 시작**: 배포 생성자에게 이메일 알림으로 시작한 다음, 워크플로우가 성숙해지면 라우팅 규칙을 추가하세요.
|
||||
</Tip>
|
||||
|
||||
1. **동적 할당 사용**: 유연한 라우팅을 위해 Flow 상태에서 담당자 이메일을 가져오세요.
|
||||
|
||||
2. **자동 응답 구성**: 중요하지 않은 검토에 대해 Flow가 중단되지 않도록 대체를 설정하세요.
|
||||
|
||||
3. **응답 시간 모니터링**: 분석을 사용하여 병목 현상을 식별하고 검토 프로세스를 최적화하세요.
|
||||
|
||||
4. **검토 메시지를 명확하게 유지**: `@human_feedback` 데코레이터에 명확하고 실행 가능한 메시지를 작성하세요.
|
||||
|
||||
5. **이메일 흐름 테스트**: 프로덕션에 가기 전에 테스트 요청을 보내 이메일 전달을 확인하세요.
|
||||
|
||||
## 관련 리소스
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Flow에서 인간 피드백" icon="code" href="/ko/learn/human-feedback-in-flows">
|
||||
`@human_feedback` 데코레이터 구현 가이드
|
||||
</Card>
|
||||
<Card title="Flow HITL 워크플로우 가이드" icon="route" href="/ko/enterprise/guides/human-in-the-loop">
|
||||
HITL 워크플로우 설정을 위한 단계별 가이드
|
||||
</Card>
|
||||
<Card title="RBAC 구성" icon="shield-check" href="/ko/enterprise/features/rbac">
|
||||
조직을 위한 역할 기반 접근 제어 구성
|
||||
</Card>
|
||||
<Card title="Webhook 스트리밍" icon="bolt" href="/ko/enterprise/features/webhook-streaming">
|
||||
실시간 이벤트 알림 설정
|
||||
</Card>
|
||||
</CardGroup>
|
||||
251
docs/edge/ko/enterprise/features/hallucination-guardrail.mdx
Normal file
251
docs/edge/ko/enterprise/features/hallucination-guardrail.mdx
Normal file
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: 환각 방어책
|
||||
description: "CrewAI 작업에서 AI 환각을 방지하고 감지합니다"
|
||||
icon: "shield-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Hallucination Guardrail은 AI가 생성한 콘텐츠가 사실에 기반하고 환각이 포함되어 있지 않은지 검증하는 엔터프라이즈 기능입니다. 이 기능은 작업 출력물을 참조 컨텍스트와 비교 분석하여, 잠재적으로 환각이 감지되었을 때 상세한 피드백을 제공합니다.
|
||||
|
||||
## 환각(Hallucinations)이란 무엇인가요?
|
||||
|
||||
AI 환각은 언어 모델이 그럴듯해 보이지만 사실과 다르거나 제공된 맥락에 의해 뒷받침되지 않는 내용을 생성할 때 발생합니다. Hallucination Guardrail은 다음과 같은 방법으로 이러한 문제를 방지합니다:
|
||||
|
||||
- 출력물을 참조 맥락과 비교
|
||||
- 원본 자료에 대한 충실도 평가
|
||||
- 문제 있는 콘텐츠에 대한 상세 피드백 제공
|
||||
- 검증 엄격성을 위한 사용자 정의 임계값 지원
|
||||
|
||||
## 기본 사용법
|
||||
|
||||
### 가드레일 설정하기
|
||||
|
||||
```python
|
||||
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
|
||||
from crewai import LLM
|
||||
|
||||
# Basic usage - will use task's expected_output as context
|
||||
guardrail = HallucinationGuardrail(
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
|
||||
# With explicit reference context
|
||||
context_guardrail = HallucinationGuardrail(
|
||||
context="AI helps with various tasks including analysis and generation.",
|
||||
llm=LLM(model="gpt-4o-mini")
|
||||
)
|
||||
```
|
||||
|
||||
### 작업에 추가하기
|
||||
|
||||
```python
|
||||
from crewai import Task
|
||||
|
||||
# Create your task with the guardrail
|
||||
task = Task(
|
||||
description="Write a summary about AI capabilities",
|
||||
expected_output="A factual summary based on the provided context",
|
||||
agent=my_agent,
|
||||
guardrail=guardrail # Add the guardrail to validate output
|
||||
)
|
||||
```
|
||||
|
||||
## 고급 구성
|
||||
|
||||
### 사용자 지정 임계값 검증
|
||||
|
||||
보다 엄격한 검증을 위해 사용자 지정 신뢰성 임계값(0-10 범위)를 설정할 수 있습니다:
|
||||
|
||||
```python
|
||||
# Strict guardrail requiring high faithfulness score
|
||||
strict_guardrail = HallucinationGuardrail(
|
||||
context="Quantum computing uses qubits that exist in superposition states.",
|
||||
llm=LLM(model="gpt-4o-mini"),
|
||||
threshold=8.0 # Requires score >= 8 to pass validation
|
||||
)
|
||||
```
|
||||
|
||||
### 도구 응답 컨텍스트 포함하기
|
||||
|
||||
작업에서 도구를 사용할 때 더 정확한 검증을 위해 도구 응답을 포함할 수 있습니다:
|
||||
|
||||
```python
|
||||
# Guardrail with tool response context
|
||||
weather_guardrail = HallucinationGuardrail(
|
||||
context="Current weather information for the requested location",
|
||||
llm=LLM(model="gpt-4o-mini"),
|
||||
tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
|
||||
)
|
||||
```
|
||||
|
||||
## 작동 원리
|
||||
|
||||
### 검증 프로세스
|
||||
|
||||
1. **컨텍스트 분석**: 가드레일은 작업 결과를 제공된 참조 컨텍스트와 비교합니다.
|
||||
2. **정확성 점수 부여**: 내부 평가자를 사용하여 정확성 점수(0-10)를 부여합니다.
|
||||
3. **판단 결정**: 콘텐츠가 정확한지 또는 환각이 포함되어 있는지 결정합니다.
|
||||
4. **임계값 확인**: 사용자 지정 임계값이 설정된 경우 해당 점수와 비교하여 검증합니다.
|
||||
5. **피드백 생성**: 검증에 실패할 때 상세한 사유를 제공합니다.
|
||||
|
||||
### 검증 논리
|
||||
|
||||
- **기본 모드**: 판정 기반 검증(FAITHFUL vs HALLUCINATED)을 사용함
|
||||
- **임계값 모드**: 신뢰성 점수가 지정된 임계값에 도달하거나 이를 초과해야 함
|
||||
- **오류 처리**: 평가 오류를 우아하게 처리하고 유익한 피드백을 제공함
|
||||
|
||||
## 가드레일 결과
|
||||
|
||||
가드레일은 검증 상태를 나타내는 구조화된 결과를 반환합니다:
|
||||
|
||||
```python
|
||||
# Example of guardrail result structure
|
||||
{
|
||||
"valid": False,
|
||||
"feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
|
||||
}
|
||||
```
|
||||
|
||||
### 결과 속성
|
||||
|
||||
- **valid**: 출력이 검증을 통과했는지 여부를 나타내는 불리언 값
|
||||
- **feedback**: 검증 실패 시 상세 설명. 다음을 포함:
|
||||
- 신뢰도 점수
|
||||
- 판정 분류
|
||||
- 실패의 구체적인 이유
|
||||
|
||||
## 작업 시스템과의 통합
|
||||
|
||||
### 자동 검증
|
||||
|
||||
가드레일이 태스크에 추가되면, 태스크가 완료로 표시되기 전에 출력값이 자동으로 검증됩니다:
|
||||
|
||||
```python
|
||||
# Task output validation flow
|
||||
task_output = agent.execute_task(task)
|
||||
validation_result = guardrail(task_output)
|
||||
|
||||
if validation_result.valid:
|
||||
# Task completes successfully
|
||||
return task_output
|
||||
else:
|
||||
# Task fails with validation feedback
|
||||
raise ValidationError(validation_result.feedback)
|
||||
```
|
||||
|
||||
### 이벤트 추적
|
||||
|
||||
guardrail은 CrewAI의 이벤트 시스템과 통합되어 가시성을 제공합니다:
|
||||
|
||||
- **검증 시작됨**: guardrail 평가가 시작될 때
|
||||
- **검증 완료됨**: 평가가 결과와 함께 종료될 때
|
||||
- **검증 실패**: 평가 중 기술적 오류가 발생할 때
|
||||
|
||||
## 모범 사례
|
||||
|
||||
### 컨텍스트 가이드라인
|
||||
|
||||
<Steps>
|
||||
<Step title="포괄적인 컨텍스트 제공">
|
||||
AI가 출력할 때 기반이 되어야 할 모든 관련 사실 정보를 포함하세요:
|
||||
|
||||
```python
|
||||
context = """
|
||||
Company XYZ was founded in 2020 and specializes in renewable energy solutions.
|
||||
They have 150 employees and generated $50M revenue in 2023.
|
||||
Their main products include solar panels and wind turbines.
|
||||
"""
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="관련 있는 컨텍스트만 유지하기">
|
||||
혼란을 피하기 위해 작업과 직접적으로 관련된 정보만 포함하세요:
|
||||
|
||||
```python
|
||||
# Good: Focused context
|
||||
context = "The current weather in New York is 18°C with light rain."
|
||||
|
||||
# Avoid: Unrelated information
|
||||
context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="컨텍스트를 정기적으로 업데이트하기">
|
||||
참고하는 컨텍스트가 최신이고 정확한 정보를 반영하는지 확인하세요.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 임계값 선택
|
||||
|
||||
<Steps>
|
||||
<Step title="기본 검증으로 시작하기">
|
||||
맞춤 임계값 없이 시작하여 기준 성능을 파악합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="요구사항에 따라 조정하기">
|
||||
- **중요 콘텐츠**: 최대 정확도를 위해 임계값 8-10 사용
|
||||
- **일반 콘텐츠**: 균형 잡힌 검증을 위해 임계값 6-7 사용
|
||||
- **창의적 콘텐츠**: 임계값 4-5 또는 기본 판정 기반 검증 사용
|
||||
</Step>
|
||||
|
||||
<Step title="모니터링 및 반복">
|
||||
검증 결과를 추적하고, 오탐/미탐을 기반으로 임계값을 조정합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 성능 고려사항
|
||||
|
||||
### 실행 시간에 미치는 영향
|
||||
|
||||
- **검증 오버헤드**: 각 가드레일마다 작업당 약 1~3초가 추가됩니다
|
||||
- **LLM 효율성**: 평가에는 효율적인 모델을 선택하세요 (예: gpt-4o-mini)
|
||||
|
||||
### 비용 최적화
|
||||
|
||||
- **모델 선택**: guardrail 평가에는 더 작고 효율적인 모델을 사용하세요
|
||||
- **컨텍스트 크기**: 참조 컨텍스트는 간결하면서도 포괄적으로 유지하세요
|
||||
- **캐싱**: 반복적인 콘텐츠의 검증 결과를 캐싱하는 것을 고려하세요
|
||||
|
||||
## 문제 해결
|
||||
|
||||
<Accordion title="검증이 항상 실패함">
|
||||
**가능한 원인:**
|
||||
- 컨텍스트가 너무 제한적이거나 작업 결과와 관련이 없음
|
||||
- 임계값이 콘텐츠 유형에 비해 너무 높게 설정됨
|
||||
- 참조 컨텍스트에 오래된 정보가 포함되어 있음
|
||||
|
||||
**해결 방법:**
|
||||
- 작업 요구사항에 맞게 컨텍스트를 검토하고 업데이트하세요
|
||||
- 임계값을 낮추거나 기본 판정 기반 검증을 사용하세요
|
||||
- 컨텍스트가 최신이며 정확한지 확인하세요
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="오탐 (유효한 콘텐츠가 무효로 판정됨)">
|
||||
**가능한 원인:**
|
||||
- 창의적이거나 해석적인 작업에 임계값이 너무 높음
|
||||
- 컨텍스트가 결과의 모든 유효한 측면을 포함하지 않음
|
||||
- 평가 모델이 과도하게 보수적임
|
||||
|
||||
**해결 방법:**
|
||||
- 임계값을 낮추거나 기본 검증을 사용하세요
|
||||
- 폭넓은 허용 가능한 콘텐츠를 포함하도록 컨텍스트를 확장하세요
|
||||
- 다른 평가 모델로 테스트하세요
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="평가 오류">
|
||||
**가능한 원인:**
|
||||
- 네트워크 연결 문제
|
||||
- LLM 모델 사용 불가 또는 속도 제한
|
||||
- 잘못된 형식의 작업 출력 또는 컨텍스트
|
||||
|
||||
**해결 방법:**
|
||||
- 네트워크 연결 및 LLM 서비스 상태를 확인하세요
|
||||
- 일시적 오류에 대해 재시도 로직을 구현하세요
|
||||
- guardrail 평가 전에 작업 출력 형식을 검증하세요
|
||||
</Accordion>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
환각 guardrail 구성 또는 문제 해결에 도움이 필요하시면 지원팀에 문의하세요.
|
||||
</Card>
|
||||
45
docs/edge/ko/enterprise/features/marketplace.mdx
Normal file
45
docs/edge/ko/enterprise/features/marketplace.mdx
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "마켓플레이스"
|
||||
description: "엔터프라이즈 크루를 위한 재사용 가능한 자산을 탐색, 설치 및 관리하세요."
|
||||
icon: "store"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
마켓플레이스는 통합, 내부 도구 및 재사용 가능한 자산을 탐색할 수 있는 큐레이션된 공간을 제공하여 크루 개발을 가속화합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## 탐색
|
||||
|
||||
- 카테고리 및 기능별로 탐색
|
||||
- 이름 또는 키워드로 검색
|
||||
|
||||
## 설치 & 활성화
|
||||
|
||||
- 승인된 자산은 원클릭 설치 지원
|
||||
- 크루별로 활성화/비활성화 가능
|
||||
- 필요한 환경 변수 및 스코프 구성
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
마켓플레이스에서 `Download` 버튼을 클릭해 템플릿을 직접 내려받아 로컬에서 사용하거나 필요에 맞게 수정할 수도 있습니다.
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="도구 & 통합" href="/ko/enterprise/features/tools-and-integrations" icon="wrench">
|
||||
에이전트가 사용할 외부 앱 연결 및 내부 도구 관리.
|
||||
</Card>
|
||||
<Card title="도구 저장소" href="/ko/enterprise/guides/tool-repository" icon="toolbox">
|
||||
크루 기능을 확장할 수 있도록 도구를 게시하고 설치.
|
||||
</Card>
|
||||
<Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="people-group">
|
||||
팀과 프로젝트 전반에서 에이전트 정의 저장, 공유 및 재사용.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
342
docs/edge/ko/enterprise/features/pii-trace-redactions.mdx
Normal file
342
docs/edge/ko/enterprise/features/pii-trace-redactions.mdx
Normal file
@@ -0,0 +1,342 @@
|
||||
---
|
||||
title: 트레이스용 PII 삭제
|
||||
description: "크루 및 플로우 실행 트레이스에서 민감한 데이터를 자동으로 삭제합니다"
|
||||
icon: "lock"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
PII 삭제는 크루 및 플로우 실행 트레이스에서 개인 식별 정보(PII)를 자동으로 감지하고 마스킹하는 CrewAI AMP 기능입니다. 이를 통해 신용카드 번호, 주민등록번호, 이메일 주소, 이름과 같은 민감한 데이터가 CrewAI AMP 트레이스에 노출되지 않도록 보장합니다. 또한 조직별 데이터를 보호하기 위해 커스텀 인식기를 생성할 수 있습니다.
|
||||
|
||||
|
||||
<Info>
|
||||
PII 삭제는 Enterprise 플랜에서 사용 가능합니다.
|
||||
배포 버전은 1.8.0 이상이어야 합니다.
|
||||
</Info>
|
||||
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
|
||||
## PII 삭제가 중요한 이유
|
||||
|
||||
프로덕션 환경에서 AI 에이전트를 실행할 때, 민감한 정보가 종종 크루를 통해 흐릅니다:
|
||||
|
||||
- CRM 통합의 고객 데이터
|
||||
- 결제 처리업체의 금융 정보
|
||||
- 양식 제출의 개인 정보
|
||||
- 내부 직원 데이터
|
||||
|
||||
적절한 삭제 없이는 이 데이터가 트레이스에 나타나, GDPR, HIPAA, PCI-DSS와 같은 규정 준수가 어려워집니다. PII 삭제는 트레이스에 저장되기 전에 민감한 데이터를 자동으로 마스킹하여 이 문제를 해결합니다.
|
||||
|
||||
## 작동 방식
|
||||
|
||||
1. **감지** - 알려진 PII 패턴에 대해 트레이스 이벤트 데이터를 스캔
|
||||
2. **분류** - 민감한 데이터 유형 식별 (신용카드, SSN, 이메일 등)
|
||||
3. **마스킹/삭제** - 구성에 따라 민감한 데이터를 마스킹된 값으로 대체
|
||||
|
||||
```
|
||||
원본: "john.doe@company.com으로 연락하거나 555-123-4567로 전화하세요"
|
||||
삭제됨: "<EMAIL_ADDRESS>로 연락하거나 <PHONE_NUMBER>로 전화하세요"
|
||||
```
|
||||
|
||||
## PII 삭제 활성화
|
||||
|
||||
<Info>
|
||||
이 기능을 사용하려면 Enterprise 플랜이어야 하며 배포 버전이 1.8.0 이상이어야 합니다.
|
||||
</Info>
|
||||
|
||||
<Steps>
|
||||
<Step title="크루 설정으로 이동">
|
||||
CrewAI AMP 대시보드에서 배포된 크루를 선택하고 배포/자동화 중 하나로 이동한 다음 **Settings** → **PII Protection**으로 이동합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="PII 보호 활성화">
|
||||
**PII Redaction for Traces**를 토글하여 활성화합니다. 이렇게 하면 트레이스 데이터의 자동 스캔 및 삭제가 활성화됩니다.
|
||||
|
||||
<Info>
|
||||
각 배포에 대해 PII 삭제를 수동으로 활성화해야 합니다.
|
||||
</Info>
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="엔티티 유형 구성">
|
||||
감지하고 삭제할 PII 유형을 선택합니다. 각 엔티티는 개별적으로 활성화하거나 비활성화할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="저장">
|
||||
구성을 저장합니다. PII 삭제는 이후 모든 크루 실행에서 활성화되며, 재배포가 필요하지 않습니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 지원되는 엔티티 유형
|
||||
|
||||
CrewAI는 카테고리별로 구성된 다음 PII 엔티티 유형을 지원합니다.
|
||||
|
||||
### 글로벌 엔티티
|
||||
|
||||
| 엔티티 | 설명 | 예시 |
|
||||
|--------|------|------|
|
||||
| `CREDIT_CARD` | 신용/직불 카드 번호 | "4111-1111-1111-1111" |
|
||||
| `CRYPTO` | 암호화폐 지갑 주소 | "bc1qxy2kgd..." |
|
||||
| `DATE_TIME` | 날짜 및 시간 | "2024년 1월 15일" |
|
||||
| `EMAIL_ADDRESS` | 이메일 주소 | "john@example.com" |
|
||||
| `IBAN_CODE` | 국제 은행 계좌 번호 | "DE89 3704 0044 0532 0130 00" |
|
||||
| `IP_ADDRESS` | IPv4 및 IPv6 주소 | "192.168.1.1" |
|
||||
| `LOCATION` | 지리적 위치 | "뉴욕시" |
|
||||
| `MEDICAL_LICENSE` | 의료 면허 번호 | "MD12345" |
|
||||
| `NRP` | 국적, 종교 또는 정치 그룹 | - |
|
||||
| `PERSON` | 개인 이름 | "홍길동" |
|
||||
| `PHONE_NUMBER` | 다양한 형식의 전화번호 | "+82 (10) 1234-5678" |
|
||||
| `URL` | 웹 URL | "https://example.com" |
|
||||
|
||||
### 미국 특정 엔티티
|
||||
|
||||
| 엔티티 | 설명 | 예시 |
|
||||
|--------|------|------|
|
||||
| `US_BANK_NUMBER` | 미국 은행 계좌 번호 | "1234567890" |
|
||||
| `US_DRIVER_LICENSE` | 미국 운전면허 번호 | "D1234567" |
|
||||
| `US_ITIN` | 개인 납세자 번호 | "900-70-0000" |
|
||||
| `US_PASSPORT` | 미국 여권 번호 | "123456789" |
|
||||
| `US_SSN` | 사회보장번호 | "123-45-6789" |
|
||||
|
||||
## 삭제 작업
|
||||
|
||||
활성화된 각 엔티티에 대해 데이터가 삭제되는 방식을 구성할 수 있습니다:
|
||||
|
||||
| 작업 | 설명 | 출력 예시 |
|
||||
|------|------|----------|
|
||||
| `mask` | 엔티티 유형 레이블로 대체 | `<CREDIT_CARD>` |
|
||||
| `redact` | 텍스트를 완전히 제거 | *(비어있음)* |
|
||||
|
||||
## 커스텀 인식기
|
||||
|
||||
기본 제공 엔티티 외에도 조직별 PII 패턴을 감지하기 위한 **커스텀 인식기**를 생성할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### 인식기 유형
|
||||
|
||||
커스텀 인식기에는 두 가지 옵션이 있습니다:
|
||||
|
||||
| 유형 | 적합한 용도 | 사용 사례 예시 |
|
||||
|------|------------|---------------|
|
||||
| **패턴 기반 (Regex)** | 예측 가능한 형식의 구조화된 데이터 | 급여 금액, 직원 ID, 프로젝트 코드 |
|
||||
| **거부 목록** | 정확한 문자열 매칭 | 회사명, 내부 코드명, 특정 용어 |
|
||||
|
||||
### 커스텀 인식기 생성
|
||||
|
||||
<Steps>
|
||||
<Step title="커스텀 인식기로 이동">
|
||||
조직 **Settings** → **Organization** → **Add Recognizer**로 이동합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="인식기 구성">
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
다음 필드를 구성합니다:
|
||||
- **Name**: 인식기의 설명적 이름
|
||||
- **Entity Type**: 삭제된 출력에 나타날 엔티티 레이블 (예: `EMPLOYEE_ID`, `SALARY`)
|
||||
- **Type**: Regex 패턴 또는 거부 목록 중 선택
|
||||
- **Pattern/Values**: 매칭할 Regex 패턴 또는 문자열 목록
|
||||
- **Confidence Threshold**: 삭제를 트리거하는 데 필요한 최소 점수 (0.0-1.0). 높은 값 (예: 0.8)은 거짓 양성을 줄이지만 일부 매치를 놓칠 수 있습니다. 낮은 값 (예: 0.5)은 더 많은 매치를 잡지만 과도하게 삭제할 수 있습니다. 기본값은 0.8입니다.
|
||||
- **Context Words** (선택사항): 근처에서 발견될 때 감지 신뢰도를 높이는 단어
|
||||
</Step>
|
||||
|
||||
<Step title="저장">
|
||||
인식기를 저장합니다. 배포에서 활성화할 수 있게 됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 엔티티 유형 이해하기
|
||||
|
||||
**Entity Type**은 매칭된 콘텐츠가 삭제된 트레이스에 어떻게 나타나는지 결정합니다:
|
||||
|
||||
```
|
||||
Entity Type: SALARY
|
||||
Pattern: salary:\s*\$\s*\d+
|
||||
입력: "직원 급여: $50,000"
|
||||
출력: "직원 <SALARY>"
|
||||
```
|
||||
|
||||
### 컨텍스트 단어 사용
|
||||
|
||||
컨텍스트 단어는 매칭된 패턴 근처에 특정 용어가 나타날 때 신뢰도를 높여 정확도를 향상시킵니다:
|
||||
|
||||
```
|
||||
Context Words: "project", "code", "internal"
|
||||
Entity Type: PROJECT_CODE
|
||||
Pattern: PRJ-\d{4}
|
||||
```
|
||||
|
||||
"project" 또는 "code"가 "PRJ-1234" 근처에 나타나면, 인식기는 그것이 진정한 매치라는 확신이 높아져 거짓 양성을 줄입니다.
|
||||
|
||||
|
||||
## 삭제된 트레이스 보기
|
||||
|
||||
PII 삭제가 활성화되면, 트레이스에서 민감한 데이터 대신 삭제된 값이 표시됩니다:
|
||||
|
||||
```
|
||||
Task Output: "고객 <PERSON>이 주문 #12345를 했습니다.
|
||||
연락처 이메일: <EMAIL_ADDRESS>, 전화: <PHONE_NUMBER>.
|
||||
<CREDIT_CARD>로 끝나는 카드로 결제가 처리되었습니다."
|
||||
```
|
||||
|
||||
삭제된 값은 꺾쇠 괄호와 엔티티 유형 레이블 (예: `<EMAIL_ADDRESS>`)로 명확하게 표시되어, 어떤 데이터가 보호되었는지 쉽게 이해할 수 있으면서도 크루 동작을 디버그하고 모니터링할 수 있습니다.
|
||||
|
||||
|
||||
|
||||
## 모범 사례
|
||||
|
||||
### 성능 고려사항
|
||||
|
||||
<Steps>
|
||||
<Step title="필요한 엔티티만 활성화">
|
||||
활성화된 각 엔티티는 처리 오버헤드를 추가합니다. 데이터와 관련된 엔티티만 활성화하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="구체적인 패턴 사용">
|
||||
커스텀 인식기의 경우 거짓 양성을 줄이고 성능을 향상시키기 위해 구체적인 패턴을 사용하세요. Regex 패턴은 급여, 직원 ID, 프로젝트 코드 등 특정 패턴을 식별할 때 가장 적합합니다. 거부 목록 인식기는 회사명, 내부 코드명 등 정확한 문자열을 식별할 때 가장 적합합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="컨텍스트 단어 활용">
|
||||
컨텍스트 단어는 주변 텍스트가 매칭될 때만 감지를 트리거하여 정확도를 향상시킵니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 문제 해결
|
||||
|
||||
<Accordion title="PII가 삭제되지 않음">
|
||||
**가능한 원인:**
|
||||
- 구성에서 엔티티 유형이 활성화되지 않음
|
||||
- 패턴이 데이터 형식과 매치되지 않음
|
||||
- 커스텀 인식기에 구문 오류가 있음
|
||||
|
||||
**해결책:**
|
||||
- Settings → Security에서 엔티티가 활성화되어 있는지 확인
|
||||
- 샘플 데이터로 regex 패턴 테스트
|
||||
- 구성 오류에 대한 로그 확인
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="너무 많은 데이터가 삭제됨">
|
||||
**가능한 원인:**
|
||||
- 너무 광범위한 엔티티 유형이 활성화됨 (예: `DATE_TIME`이 모든 곳의 날짜를 잡음)
|
||||
- 커스텀 인식기 패턴이 너무 일반적임
|
||||
|
||||
**해결책:**
|
||||
- 거짓 양성을 유발하는 엔티티 비활성화
|
||||
- 커스텀 패턴을 더 구체적으로 만들기
|
||||
- 정확도 향상을 위해 컨텍스트 단어 추가
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="성능 문제">
|
||||
**가능한 원인:**
|
||||
- 너무 많은 엔티티가 활성화됨
|
||||
- NLP 기반 엔티티 (`PERSON`, `LOCATION`, `NRP`)는 머신러닝 모델을 사용하므로 계산 비용이 높음
|
||||
|
||||
**해결책:**
|
||||
- 실제로 필요한 엔티티만 활성화
|
||||
- 가능한 경우 패턴 기반 대안 고려
|
||||
- 대시보드에서 트레이스 처리 시간 모니터링
|
||||
</Accordion>
|
||||
|
||||
---
|
||||
|
||||
## 실제 예시: 급여 패턴 매칭
|
||||
|
||||
이 예시는 트레이스에서 급여 정보를 감지하고 마스킹하는 커스텀 인식기를 생성하는 방법을 보여줍니다.
|
||||
|
||||
### 사용 사례
|
||||
|
||||
크루가 다음과 같은 형식의 급여 정보가 포함된 직원 또는 재무 데이터를 처리합니다:
|
||||
- `salary: $50,000`
|
||||
- `salary: $125,000.00`
|
||||
- `salary:$1,500.50`
|
||||
|
||||
민감한 보상 데이터를 보호하기 위해 이러한 값을 자동으로 마스킹하려고 합니다.
|
||||
|
||||
### 구성
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| 필드 | 값 |
|
||||
|------|-----|
|
||||
| **Name** | `SALARY` |
|
||||
| **Entity Type** | `SALARY` |
|
||||
| **Type** | Regex Pattern |
|
||||
| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
|
||||
| **Action** | Mask |
|
||||
| **Confidence Threshold** | `0.8` |
|
||||
| **Context Words** | `salary, compensation, pay, wage, income` |
|
||||
|
||||
### Regex 패턴 분석
|
||||
|
||||
| 패턴 구성요소 | 의미 |
|
||||
|--------------|------|
|
||||
| `salary:` | 리터럴 텍스트 "salary:" 매치 |
|
||||
| `\s*` | 0개 이상의 공백 문자 매치 |
|
||||
| `\$` | 달러 기호 매치 (이스케이프) |
|
||||
| `\s*` | $ 뒤의 0개 이상의 공백 문자 매치 |
|
||||
| `\d{1,3}` | 1-3자리 숫자 매치 (예: "1", "50", "125") |
|
||||
| `(,\d{3})*` | 쉼표로 구분된 천 단위 매치 (예: ",000", ",500,000") |
|
||||
| `(\.\d{2})?` | 선택적으로 센트 매치 (예: ".00", ".50") |
|
||||
|
||||
### 결과 예시
|
||||
|
||||
```
|
||||
원본: "직원 기록에 salary: $125,000.00 연봉이 표시됩니다"
|
||||
삭제됨: "직원 기록에 <SALARY> 연봉이 표시됩니다"
|
||||
|
||||
원본: "기본 salary:$50,000에 보너스 가능성"
|
||||
삭제됨: "기본 <SALARY>에 보너스 가능성"
|
||||
```
|
||||
|
||||
<Tip>
|
||||
"salary", "compensation", "pay", "wage", "income"과 같은 컨텍스트 단어를 추가하면 이러한 용어가 매칭된 패턴 근처에 나타날 때 감지 신뢰도가 높아져 거짓 양성을 줄입니다.
|
||||
</Tip>
|
||||
|
||||
### 배포에서 인식기 활성화
|
||||
|
||||
<Warning>
|
||||
조직 수준에서 커스텀 인식기를 생성해도 배포에 자동으로 활성화되지 않습니다. 적용하려는 모든 배포에 대해 각 인식기를 수동으로 활성화해야 합니다.
|
||||
</Warning>
|
||||
|
||||
커스텀 인식기를 생성한 후, 각 배포에서 활성화합니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="배포로 이동">
|
||||
배포/자동화로 이동하여 **Settings** → **PII Protection**을 엽니다.
|
||||
</Step>
|
||||
|
||||
<Step title="커스텀 인식기 선택">
|
||||
**Mask Recognizers** 아래에서 조직에서 정의한 인식기를 볼 수 있습니다. 활성화하려는 인식기 옆의 체크박스를 선택합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="구성 저장">
|
||||
변경 사항을 저장합니다. 인식기는 이 배포의 모든 후속 실행에서 활성화됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
커스텀 인식기가 필요한 각 배포에서 이 프로세스를 반복합니다. 이를 통해 다양한 환경 (예: 개발 vs. 프로덕션)에서 어떤 인식기가 활성화되는지 세밀하게 제어할 수 있습니다.
|
||||
</Info>
|
||||
260
docs/edge/ko/enterprise/features/rbac.mdx
Normal file
260
docs/edge/ko/enterprise/features/rbac.mdx
Normal file
@@ -0,0 +1,260 @@
|
||||
---
|
||||
title: "역할 기반 접근 제어 (RBAC)"
|
||||
description: "역할, 범위, 세분화된 권한으로 crews, 도구, 데이터 접근을 제어합니다."
|
||||
icon: "shield"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
CrewAI AMP의 RBAC는 두 가지 계층을 통해 안전하고 확장 가능한 접근 관리를 제공합니다:
|
||||
|
||||
1. **기능 권한** — 플랫폼 전반에서 각 역할이 수행할 수 있는 작업을 제어합니다 (관리, 읽기 또는 접근 불가)
|
||||
2. **엔티티 수준 권한** — 개별 자동화, 환경 변수, LLM 연결, Git 저장소에 대한 세분화된 접근 제어
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/users_and_roles.png" alt="CrewAI AMP RBAC 개요" />
|
||||
</Frame>
|
||||
|
||||
## 사용자와 역할
|
||||
|
||||
CrewAI 워크스페이스의 각 구성원에게는 역할이 할당되며, 이를 통해 다양한 기능에 대한 접근 범위가 결정됩니다.
|
||||
|
||||
가능한 작업:
|
||||
|
||||
- 사전 정의된 역할 사용 (Owner, Member)
|
||||
- 특정 권한에 맞춘 커스텀 역할 생성
|
||||
- 설정 패널에서 언제든지 역할 할당
|
||||
|
||||
설정 위치: Settings → Roles
|
||||
|
||||
<Steps>
|
||||
<Step title="Roles 설정 열기">
|
||||
CrewAI AMP에서 <b>Settings → Roles</b>로 이동합니다.
|
||||
</Step>
|
||||
<Step title="역할 유형 선택">
|
||||
사전 정의된 역할(<b>Owner</b>, <b>Member</b>)을 사용하거나{" "}
|
||||
<b>Create role</b>을 클릭하여 커스텀 역할을 만듭니다.
|
||||
</Step>
|
||||
<Step title="멤버에 할당">
|
||||
사용자를 선택하고 역할을 할당합니다. 언제든지 변경할 수 있습니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 사전 정의된 역할
|
||||
|
||||
| 역할 | 설명 |
|
||||
| :--------- | :------------------------------------------------------------------- |
|
||||
| **Owner** | 모든 기능 및 설정에 대한 전체 접근 권한. 제한할 수 없습니다. |
|
||||
| **Member** | 대부분의 기능에 대한 읽기 접근, 환경 변수, LLM 연결, Studio 프로젝트에 대한 관리 접근. 조직 설정이나 기본 설정은 수정할 수 없습니다. |
|
||||
|
||||
### 구성 요약
|
||||
|
||||
| 영역 | 설정 위치 | 옵션 |
|
||||
| :------------ | :--------------------------------- | :-------------------------------- |
|
||||
| 사용자 & 역할 | Settings → Roles | 사전 정의: Owner, Member; 커스텀 역할 |
|
||||
| 자동화 가시성 | Automation → Settings → Visibility | Private; 사용자/역할 화이트리스트 |
|
||||
|
||||
---
|
||||
|
||||
## 기능 권한 매트릭스
|
||||
|
||||
각 역할에는 기능 영역별 권한 수준이 있습니다. 세 가지 수준은 다음과 같습니다:
|
||||
|
||||
- **Manage** — 전체 읽기/쓰기 접근 (생성, 편집, 삭제)
|
||||
- **Read** — 읽기 전용 접근
|
||||
- **No access** — 기능이 숨겨지거나 접근 불가
|
||||
|
||||
| 기능 | Owner | Member (기본값) | 사용 가능한 수준 | 설명 |
|
||||
| :-------------------------- | :------ | :--------------- | :------------------------- | :------------------------------------------------------------- |
|
||||
| `usage_dashboards` | Manage | Read | Manage / Read / No access | 사용 메트릭 및 분석 보기 |
|
||||
| `crews_dashboards` | Manage | Read | Manage / Read / No access | 배포 대시보드 보기, 자동화 세부 정보 접근 |
|
||||
| `invitations` | Manage | Read | Manage / Read / No access | 조직에 새 멤버 초대 |
|
||||
| `training_ui` | Manage | Read | Manage / Read / No access | 훈련/파인튜닝 인터페이스 접근 |
|
||||
| `tools` | Manage | Read | Manage / Read / No access | 도구 생성 및 관리 |
|
||||
| `agents` | Manage | Read | Manage / Read / No access | 에이전트 생성 및 관리 |
|
||||
| `environment_variables` | Manage | Manage | Manage / No access | 환경 변수 생성 및 관리 |
|
||||
| `llm_connections` | Manage | Manage | Manage / No access | LLM 제공자 연결 구성 |
|
||||
| `default_settings` | Manage | No access | Manage / No access | 조직 전체 기본 설정 수정 |
|
||||
| `organization_settings` | Manage | No access | Manage / No access | 결제, 플랜 및 조직 구성 관리 |
|
||||
| `studio_projects` | Manage | Manage | Manage / No access | Studio에서 프로젝트 생성 및 편집 |
|
||||
|
||||
<Tip>
|
||||
커스텀 역할을 만들 때 대부분의 기능은 **Manage**, **Read** 또는 **No access**로 설정할 수 있습니다. 그러나 `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, `studio_projects`는 **Manage** 또는 **No access**만 지원합니다 — 이 기능들에는 읽기 전용 옵션이 없습니다.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## GitHub 또는 Zip에서 배포
|
||||
|
||||
가장 흔한 RBAC 질문 중 하나: _"팀원이 배포하려면 어떤 권한이 필요한가요?"_
|
||||
|
||||
### GitHub에서 배포
|
||||
|
||||
GitHub 저장소에서 자동화를 배포하려면 사용자에게 다음이 필요합니다:
|
||||
|
||||
1. **`crews_dashboards`**: 최소 `Read` — 배포가 생성되는 자동화 대시보드에 접근하는 데 필요
|
||||
2. **Git 저장소 접근** (Git 저장소에 대한 엔티티 수준 RBAC가 활성화된 경우): 사용자의 역할에 엔티티 수준 권한을 통해 특정 Git 저장소에 대한 접근이 부여되어야 함
|
||||
3. **`studio_projects`: `Manage`** — 배포 전에 Studio에서 crew를 빌드하는 경우
|
||||
|
||||
### Zip에서 배포
|
||||
|
||||
Zip 파일 업로드로 자동화를 배포하려면 사용자에게 다음이 필요합니다:
|
||||
|
||||
1. **`crews_dashboards`**: 최소 `Read` — 자동화 대시보드에 접근하는 데 필요
|
||||
2. **Zip 배포 활성화**: 조직이 조직 설정에서 Zip 배포를 비활성화하지 않아야 함
|
||||
|
||||
### 빠른 참조: 배포에 필요한 최소 권한
|
||||
|
||||
| 작업 | 필요한 기능 권한 | 추가 요구사항 |
|
||||
| :------------------- | :----------------------------------- | :----------------------------------------------- |
|
||||
| GitHub에서 배포 | `crews_dashboards: Read` | Git 저장소 엔티티 접근 (Git RBAC 활성화 시) |
|
||||
| Zip에서 배포 | `crews_dashboards: Read` | 조직 수준에서 Zip 배포가 활성화되어야 함 |
|
||||
| Studio에서 빌드 | `studio_projects: Manage` | — |
|
||||
| LLM 키 구성 | `llm_connections: Manage` | — |
|
||||
| 환경 변수 설정 | `environment_variables: Manage` | 엔티티 수준 접근 (엔티티 RBAC 활성화 시) |
|
||||
|
||||
---
|
||||
|
||||
## 자동화 수준 접근 제어 (엔티티 권한)
|
||||
|
||||
조직 전체 역할 외에도, CrewAI는 개별 리소스에 대한 접근을 제한하는 세분화된 엔티티 수준 권한을 지원합니다.
|
||||
|
||||
### 자동화 가시성
|
||||
|
||||
자동화는 사용자 또는 역할별로 접근을 제한하는 가시성 설정을 지원합니다. 다음과 같은 경우에 유용합니다:
|
||||
|
||||
- 민감하거나 실험적인 자동화를 비공개로 유지
|
||||
- 대규모 팀이나 외부 협업자의 가시성 관리
|
||||
- 격리된 컨텍스트에서 자동화 테스트
|
||||
|
||||
배포를 비공개로 구성할 수 있으며, 이 경우 화이트리스트에 포함된 사용자와 역할만 상호작용할 수 있습니다.
|
||||
|
||||
설정 위치: Automation → Settings → Visibility 탭
|
||||
|
||||
<Steps>
|
||||
<Step title="Visibility 탭 열기">
|
||||
<b>Automation → Settings → Visibility</b>로 이동합니다.
|
||||
</Step>
|
||||
<Step title="가시성 설정">
|
||||
접근을 제한하려면 <b>Private</b>를 선택합니다. 조직 Owner는 항상
|
||||
접근 권한을 유지합니다.
|
||||
</Step>
|
||||
<Step title="접근 허용 대상 추가">
|
||||
보기, 실행, 로그/메트릭/설정 접근이 허용된 특정 사용자와 역할을
|
||||
추가합니다.
|
||||
</Step>
|
||||
<Step title="저장 및 확인">
|
||||
변경 사항을 저장한 후, 화이트리스트에 없는 사용자가 자동화를 보거나 실행할 수
|
||||
없는지 확인합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Private 가시성: 접근 결과
|
||||
|
||||
| 동작 | Owner | 화이트리스트 사용자/역할 | 비포함 |
|
||||
| :--------------------- | :---- | :----------------------- | :----- |
|
||||
| 자동화 보기 | ✓ | ✓ | ✗ |
|
||||
| 자동화/API 실행 | ✓ | ✓ | ✗ |
|
||||
| 로그/메트릭/설정 접근 | ✓ | ✓ | ✗ |
|
||||
|
||||
<Tip>
|
||||
조직 Owner는 항상 접근 권한이 있습니다. Private 모드에서는 화이트리스트에 포함된
|
||||
사용자/역할만 보기, 실행, 로그/메트릭/설정에 접근할 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/visibility.png" alt="CrewAI AMP 자동화 가시성 설정" />
|
||||
</Frame>
|
||||
|
||||
### 배포 권한 유형
|
||||
|
||||
특정 자동화에 엔티티 수준 접근을 부여할 때 다음 권한 유형을 할당할 수 있습니다:
|
||||
|
||||
| 권한 | 허용 범위 |
|
||||
| :------------------- | :-------------------------------------------------- |
|
||||
| `run` | 자동화 실행 및 API 사용 |
|
||||
| `traces` | 실행 트레이스 및 로그 보기 |
|
||||
| `manage_settings` | 자동화 편집, 재배포, 롤백 또는 삭제 |
|
||||
| `human_in_the_loop` | HITL(human-in-the-loop) 요청에 응답 |
|
||||
| `full_access` | 위의 모든 권한 |
|
||||
|
||||
### 기타 리소스에 대한 엔티티 수준 RBAC
|
||||
|
||||
엔티티 수준 RBAC가 활성화되면 다음 리소스에 대한 접근도 사용자 또는 역할별로 제어할 수 있습니다:
|
||||
|
||||
| 리소스 | 제어 방식 | 설명 |
|
||||
| :----------------- | :---------------------------------- | :------------------------------------------------------------ |
|
||||
| 환경 변수 | 엔티티 RBAC 기능 플래그 | 특정 환경 변수를 보거나 관리할 수 있는 역할/사용자 제한 |
|
||||
| LLM 연결 | 엔티티 RBAC 기능 플래그 | 특정 LLM 제공자 구성에 대한 접근 제한 |
|
||||
| Git 저장소 | Git 저장소 RBAC 조직 설정 | 특정 연결된 저장소에 접근할 수 있는 역할/사용자 제한 |
|
||||
|
||||
---
|
||||
|
||||
## 일반적인 역할 패턴
|
||||
|
||||
CrewAI는 Owner와 Member 역할을 기본 제공하지만, 대부분의 팀은 커스텀 역할을 만들어 활용합니다. 일반적인 패턴은 다음과 같습니다:
|
||||
|
||||
### Developer 역할
|
||||
|
||||
자동화를 빌드하고 배포하지만 조직 설정을 관리하지 않는 팀원을 위한 역할입니다.
|
||||
|
||||
| 기능 | 권한 |
|
||||
| :-------------------------- | :---------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Read |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Manage |
|
||||
| `agents` | Manage |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | Manage |
|
||||
|
||||
### Viewer / Stakeholder 역할
|
||||
|
||||
자동화를 모니터링하고 결과를 확인해야 하는 비기술 이해관계자를 위한 역할입니다.
|
||||
|
||||
| 기능 | 권한 |
|
||||
| :-------------------------- | :---------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Read |
|
||||
| `invitations` | No access |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | No access |
|
||||
| `llm_connections` | No access |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
### Ops / Platform Admin 역할
|
||||
|
||||
인프라 설정을 관리하지만 에이전트를 빌드하지 않을 수 있는 플랫폼 운영자를 위한 역할입니다.
|
||||
|
||||
| 기능 | 권한 |
|
||||
| :-------------------------- | :---------- |
|
||||
| `usage_dashboards` | Manage |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Manage |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | Manage |
|
||||
| `organization_settings` | Read |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
---
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
RBAC 관련 질문은 지원팀에 문의해 주세요.
|
||||
</Card>
|
||||
@@ -0,0 +1,321 @@
|
||||
---
|
||||
title: AWS Workload Identity (OIDC Federation)
|
||||
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity를 통해 AWS Secrets Manager를 구성합니다
|
||||
sidebarTitle: Workload Identity 사용
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **Workload Identity Federation**을 사용하여 AWS Secrets Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, STS를 통해 이를 AWS 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 AWS 액세스 키를 어디에도 저장하지 않습니다.
|
||||
|
||||
<Note>
|
||||
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하고 로테이션 전파에 신경 쓰지 않는다면, 더 간단한 [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) 가이드를 참조하세요.
|
||||
</Note>
|
||||
|
||||
### 런타임 동작 방식
|
||||
|
||||
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
|
||||
2. 워커가 JWT를 제시하여 아래에서 설정한 IAM 역할에 대해 `sts:AssumeRoleWithWebIdentity`를 호출합니다.
|
||||
3. AWS STS가 CrewAI Platform의 공개 OIDC 발급자에 대해 JWT를 검증한 다음(따라서 플랫폼 설치가 AWS에서 접근 가능해야 함), 단기 AWS 자격 증명을 반환합니다.
|
||||
4. 워커가 해당 자격 증명을 사용하여 `secretsmanager:GetSecretValue`를 호출합니다.
|
||||
5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
|
||||
|
||||
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
|
||||
- IAM OIDC 공급자, IAM 역할, IAM 정책을 생성할 권한이 있는 AWS 계정.
|
||||
- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`).
|
||||
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
- **CrewAI 조직 UUID.** CrewAI Platform의 조직 설정 페이지에서 찾을 수 있습니다 — 3단계의 신뢰 정책이 IAM 역할을 이 특정 조직에 바인딩합니다.
|
||||
- **CrewAI Platform 설치가 AWS에서 HTTPS를 통해 접근 가능해야 합니다.** AWS STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지(또는 AWS가 VPC 피어링/동등한 방법을 통해 네트워크에 도달할 수 있는지) 확인하세요.
|
||||
</Note>
|
||||
|
||||
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
|
||||
|
||||
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 해당 문서의 `issuer` 필드는 AWS가 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다.
|
||||
|
||||
브라우저에서 URL을 엽니다(`<your-platform-host>`를 실제 호스트 이름으로 교체, 예: `app.crewai.com`):
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
다음을 포함하는 JSON이 보일 것입니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
|
||||
|
||||
<Tip>
|
||||
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
## 2단계 — CrewAI Platform을 IAM OIDC ID 공급자로 등록
|
||||
|
||||
[IAM → Identity providers 콘솔](https://console.aws.amazon.com/iam/home#/identity_providers)을 열고 **Add provider**를 클릭합니다.
|
||||
|
||||
- **Provider type:** OpenID Connect.
|
||||
- **Provider URL:** 1단계의 `issuer` 값(예: `https://app.crewai.com`).
|
||||
- **Audience:** `sts.amazonaws.com`
|
||||
|
||||
**Add provider**를 클릭합니다.
|
||||
|
||||
또는 CLI를 통해:
|
||||
|
||||
```bash
|
||||
aws iam create-open-id-connect-provider \
|
||||
--url "https://<your-platform-host>" \
|
||||
--client-id-list "sts.amazonaws.com" \
|
||||
--thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
|
||||
```
|
||||
|
||||
출력에서 **OpenIDConnectProviderArn**(또는 콘솔에서 공급자의 ARN)을 복사합니다. 3단계에서 사용합니다.
|
||||
|
||||
<Note>
|
||||
AWS는 실제로 STS WebIdentity 호출의 thumbprint를 검증하지 않습니다 — 검증 시점에 항상 JWKS를 다시 가져옵니다 — 그러나 API에서 해당 필드가 존재해야 합니다.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */}
|
||||
{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */}
|
||||
|
||||
## 3단계 — IAM 역할 생성
|
||||
|
||||
`trust-policy.json`으로 저장하고, `<YOUR_ACCOUNT_ID>`, `<your-platform-host>`(발급자 호스트로 `https://` 또는 `http://` **없음**, 예: `app.crewai.com`), `<YOUR_CREWAI_ORG_UUID>`(사전 준비 사항에서)를 교체합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
|
||||
},
|
||||
"Action": "sts:AssumeRoleWithWebIdentity",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"<your-platform-host>:aud": "sts.amazonaws.com",
|
||||
"<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
역할을 생성합니다:
|
||||
|
||||
```bash
|
||||
aws iam create-role \
|
||||
--role-name crewai-secrets-reader \
|
||||
--assume-role-policy-document file://trust-policy.json
|
||||
```
|
||||
|
||||
출력에서 **Role Arn**을 복사합니다 — 이것이 `aws_role_arn`입니다. 6단계에서 CrewAI Platform에 붙여 넣습니다.
|
||||
|
||||
<Tip>
|
||||
두 조건은 신뢰를 정확하게 범위 지정합니다: `aud`는 AWS STS audience를 가진 토큰으로만 가정을 제한하고, `sub`는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다. CrewAI Platform은 항상 AWS workload identity 토큰에 두 클레임을 모두 설정합니다.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */}
|
||||
|
||||
## 4단계 — Secrets Manager + KMS 액세스용 IAM 정책 생성 및 연결
|
||||
|
||||
`secrets-policy.json`으로 저장하고 자리 표시자를 계정 ID, 리전, 시크릿 이름 접두사, 그리고 해당 시크릿을 암호화하는 KMS 키 ARN으로 교체합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerListForUI",
|
||||
"Effect": "Allow",
|
||||
"Action": "secretsmanager:ListSecrets",
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:GetSecretValue"
|
||||
],
|
||||
"Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`SecretsManagerListForUI`는 환경 변수 폼의 **Secret Name 자동 완성**과 자격 증명의 **Test Connection** 버튼을 지원합니다. `secretsmanager:ListSecrets`는 `Resource: "*"`만 허용합니다 — IAM 계층에서 계정 범위로 제한됩니다.
|
||||
|
||||
CLI(인라인 정책, 가장 간단함) 또는 콘솔 UI를 사용하여 역할에 정책을 연결합니다. 많은 역할에서 동일한 권한을 재사용하는 환경의 경우 재사용 가능한 명명된 정책을 위해 **Managed policy** 탭을 사용하세요.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="인라인 정책 (CLI)">
|
||||
```bash
|
||||
aws iam put-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-name SecretsManagerRead \
|
||||
--policy-document file://secrets-policy.json
|
||||
```
|
||||
|
||||
이는 정책을 **인라인**으로 역할에 연결합니다. 인라인 정책은 역할에 연결되어 있으며 다른 역할에서 재사용할 수 없습니다.
|
||||
</Tab>
|
||||
|
||||
<Tab title="관리형 정책 (CLI, 재사용 가능)">
|
||||
```bash
|
||||
POLICY_ARN=$(aws iam create-policy \
|
||||
--policy-name CrewAISecretsReader \
|
||||
--policy-document file://secrets-policy.json \
|
||||
--query 'Policy.Arn' --output text)
|
||||
|
||||
aws iam attach-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-arn "$POLICY_ARN"
|
||||
```
|
||||
|
||||
관리형 정책은 여러 역할에 연결할 수 있는 독립형 IAM 리소스입니다.
|
||||
</Tab>
|
||||
|
||||
<Tab title="콘솔 (UI)">
|
||||
1. [IAM → Roles 콘솔](https://console.aws.amazon.com/iam/home#/roles)을 열고 **crewai-secrets-reader**를 선택합니다.
|
||||
2. **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다.
|
||||
3. **JSON** 편집기로 전환하고 `secrets-policy.json`의 내용을 붙여 넣습니다.
|
||||
4. **Next**를 클릭하고 정책 이름(예: `SecretsManagerRead`)을 지정한 다음 **Create policy**를 클릭합니다.
|
||||
|
||||
대신 재사용 가능한 관리형 정책을 만들려면 **IAM → Policies → Create policy**를 사용한 다음, 역할의 **Permissions** 탭에서 역할에 연결합니다.
|
||||
|
||||
{/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 5단계 — AWS에 최소 하나의 시크릿 생성
|
||||
|
||||
테스트할 시크릿이 아직 없다면 지금 하나 만드세요:
|
||||
|
||||
```bash
|
||||
aws secretsmanager create-secret \
|
||||
--region <REGION> \
|
||||
--name crewai-test-keyword \
|
||||
--secret-string "hello from aws"
|
||||
```
|
||||
|
||||
또는 [AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**을 통해 만듭니다.
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */}
|
||||
|
||||
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */}
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `aws-prod`).
|
||||
- **Cloud Provider:** `AWS`.
|
||||
- **AWS Role ARN:** 3단계의 **Role Arn**.
|
||||
- **AWS Region:** 시크릿이 위치한 리전(예: `us-east-1`).
|
||||
- (선택) AWS 기반 시크릿 자격 증명을 생성할 때 이 WI 구성을 기본으로 선택하려면 **Set as default for AWS**를 체크합니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */}
|
||||
|
||||
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
|
||||
|
||||
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `aws-prod-wi`).
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Authentication Method:** `Workload Identity`(정적 키 / AssumeRole 대신).
|
||||
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다(예: `aws-prod`).
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다.
|
||||
|
||||
Workload Identity 아래에서는 폼이 **AWS Region**만 요청합니다 — 정적 자격 증명 필드(Access Key ID, Secret Access Key, Role ARN, External ID)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. 역할 ARN은 연결된 WI 구성에서 가져옵니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */}
|
||||
|
||||
## 8단계 — 연결 테스트
|
||||
|
||||
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, `sts:AssumeRoleWithWebIdentity`를 통해 AWS STS와 교환한 다음, 결과로 받은 자격 증명이 가정된 역할에 대해 `sts:GetCallerIdentity`를 호출할 수 있는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
|
||||
|
||||
성공적인 Test Connection은 신뢰 정책, OIDC 공급자 등록, audience 조건이 모두 올바르게 연결되었음을 증명합니다. 시크릿별 IAM이 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿 ARN에 대한 `secretsmanager:GetSecretValue`는 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
|
||||
|
||||
## 9단계 — 환경 변수에서 시크릿 참조
|
||||
|
||||
이제 다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
|
||||
WI 기반과 정적 키 기반 환경 변수의 유일한 차이는 시크릿이 **언제** 읽히는지입니다:
|
||||
|
||||
- **WI 기반:** 모든 자동화 kickoff에서 시크릿 값을 새로 읽습니다.
|
||||
- **정적 키 기반:** 배포 시점에 시크릿 값을 읽고 배포 이미지에 박힙니다.
|
||||
|
||||
## 10단계 — 로테이션 확인
|
||||
|
||||
배포가 실행 중인 상태에서 AWS의 시크릿을 로테이션합니다:
|
||||
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id crewai-test-keyword \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
|
||||
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
|
||||
|
||||
로그에서 확인하려면(워커에 액세스할 수 있는 경우) 다음을 찾으세요:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (aws): N secret(s) resolved
|
||||
```
|
||||
|
||||
이 줄은 모든 kickoff에 나타나며 AWS에 대한 새로운 `GetSecretValue` 호출을 의미합니다.
|
||||
|
||||
## 문제 해결
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| Test Connection이 핸드셰이크 오류로 실패함 | `sts:AssumeRoleWithWebIdentity` 호출이 거부되었습니다. 신뢰 정책의 federated principal ARN이 `oidc-provider/<your-platform-host>`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 참조하는지, audience 조건이 정확히 `sts.amazonaws.com`인지, `sub` 조건이 CrewAI 조직 UUID와 일치하는지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 AWS에서 접근 가능한지 확인하세요. |
|
||||
| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS가 CrewAI Platform 호스트에 도달하여 JWKS를 가져올 수 없습니다. 호스트가 AWS에서 인터넷에 접근 가능한지, OIDC 디스커버리 URL이 200을 반환하는지, JWKS 엔드포인트가 접근 가능한지 확인하세요. |
|
||||
| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | 신뢰 정책 불일치. 3단계를 다시 확인하세요: federated principal ARN은 `oidc-provider/<your-platform-host>`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 포함해야 하고, audience 조건은 정확히 `sts.amazonaws.com`이어야 하며, `sub` 조건은 `organization:<YOUR_CREWAI_ORG_UUID>`와 같아야 합니다. |
|
||||
| Secret Name 자동 완성에 `AccessDenied: secretsmanager:ListSecrets` 표시 | 역할에 `Resource: "*"`를 가진 `secretsmanager:ListSecrets`가 없습니다. 4단계의 `SecretsManagerListForUI` 문을 추가하세요. |
|
||||
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 리소스 범위 IAM이 없습니다. 해당 시크릿의 ARN과 KMS 키에 대한 역할의 `secretsmanager:GetSecretValue` 및 `kms:Decrypt` 권한을 감사하세요. |
|
||||
| `RegionDisabledException` / 시크릿을 찾을 수 없음 | Workload Identity Config의 리전이 시크릿이 위치한 곳과 일치하지 않습니다. 6단계를 다시 확인하세요. |
|
||||
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
|
||||
|
||||
### 참고 링크
|
||||
|
||||
- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
|
||||
- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html)
|
||||
- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
|
||||
- 다중 클라우드의 경우 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요.
|
||||
295
docs/edge/ko/enterprise/features/secrets-manager/aws.mdx
Normal file
295
docs/edge/ko/enterprise/features/secrets-manager/aws.mdx
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: AWS Secrets Manager (정적 자격 증명)
|
||||
description: 정적 액세스 키 또는 AssumeRole을 사용하여 AWS Secrets Manager를 CrewAI Platform의 시크릿 공급자로 구성합니다
|
||||
sidebarTitle: 정적 자격 증명 사용
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **정적 자격 증명**(액세스 키, 선택적으로 AssumeRole 포함)을 사용하여 AWS Secrets Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 AWS 계정에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
|
||||
|
||||
<Note>
|
||||
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원하면(재배포 없음), [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
이 가이드는 AWS 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- IAM 사용자, 고객 관리형 정책, 그리고 (선택적으로) IAM 역할을 생성할 수 있는 권한이 있는 AWS 계정.
|
||||
- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`).
|
||||
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 인증 방법 선택
|
||||
|
||||
CrewAI Platform은 AWS Secrets Manager에 인증하는 두 가지 방법을 지원합니다. 시작하기 전에 하나를 선택하세요 — 아래 단계는 선택한 방법에 따라 다릅니다.
|
||||
|
||||
| 방법 | 사용 시기 | 트레이드오프 |
|
||||
|---|---|---|
|
||||
| **정적 액세스 키** | 시작 단계, 단일 계정 배포 | 가장 간단한 설정; 액세스 키를 수동으로 로테이션해야 함 |
|
||||
| **AssumeRole** | 교차 계정, 프로덕션 강화 | 단기 자격 증명; External ID 지원; 추가 IAM 역할 필요 |
|
||||
|
||||
이 가이드의 나머지 부분은 단계 3-5에서 탭을 사용하므로 선택한 경로에 맞는 단계를 따를 수 있습니다.
|
||||
|
||||
## 1단계 — IAM 사용자 생성
|
||||
|
||||
[IAM 콘솔](https://console.aws.amazon.com/iam/)을 열고 **Users**로 이동한 다음 **Create user**를 클릭합니다.
|
||||
|
||||
- 권장 이름: `crewai-secrets-reader`.
|
||||
- **Provide user access to the AWS Management Console**은 선택하지 마세요 — 이 주체는 사람이 아닌 CrewAI Platform이 프로그래밍 방식으로 사용합니다.
|
||||
- **Next**를 클릭합니다.
|
||||
|
||||
**Set permissions** 페이지에서 기본 선택을 유지합니다. 정책은 3단계에서 연결합니다.
|
||||
|
||||
**Next**를 클릭하고 검토한 다음 **Create user**를 클릭합니다.
|
||||
|
||||
자세한 내용은 AWS 문서를 참조하세요: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */}
|
||||
|
||||
## 2단계 — IAM 정책 생성
|
||||
|
||||
CrewAI Platform은 AWS Secrets Manager에 대한 읽기 전용 액세스와 KMS를 통해 시크릿을 복호화할 수 있는 권한이 필요합니다. 다음 JSON으로 고객 관리형 정책을 생성하세요.
|
||||
|
||||
IAM 콘솔에서 **Policies**로 이동한 다음 **Create policy**를 클릭합니다.
|
||||
|
||||
**JSON** 탭을 선택하고 내용을 다음으로 바꿉니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:ListSecrets",
|
||||
"secretsmanager:GetSecretValue",
|
||||
"secretsmanager:DescribeSecret"
|
||||
],
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:DescribeKey",
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Next**를 클릭한 다음 **Review and create** 페이지에서:
|
||||
|
||||
- **Policy name:** `CrewAISecretsManagerRead`
|
||||
- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform`
|
||||
|
||||
**Create policy**를 클릭합니다.
|
||||
|
||||
<Tip>
|
||||
위 정책은 간소화를 위해 `Resource`에 `*`를 부여합니다. 프로덕션에서는 `Resource`를 CrewAI Platform이 액세스해야 하는 특정 시크릿의 ARN으로 좁히고, `kms:Decrypt`를 해당 시크릿을 암호화하는 특정 KMS 키 ARN으로 좁히세요. [AWS의 최소 권한 지침](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)을 참조하세요.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */}
|
||||
{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */}
|
||||
|
||||
## 3단계 — 정책 연결
|
||||
|
||||
<Tabs>
|
||||
<Tab title="정적 액세스 키">
|
||||
1. IAM 콘솔에서 **Users**로 이동하여 1단계에서 만든 사용자를 클릭합니다.
|
||||
2. **Permissions** 탭에서 **Add permissions** → **Attach policies directly**를 클릭합니다.
|
||||
3. `CrewAISecretsManagerRead`를 검색하고 선택한 다음 **Next**를 클릭합니다.
|
||||
4. **Add permissions**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
AssumeRole의 경우 정책은 (사용자가 아닌) 별도의 IAM **역할**에 연결됩니다. 1단계의 사용자는 해당 역할에 대해 `sts:AssumeRole`을 호출할 권한만 필요합니다.
|
||||
|
||||
**역할 생성:**
|
||||
|
||||
1. IAM 콘솔에서 **Roles**로 이동하여 **Create role**을 클릭합니다.
|
||||
2. **Trusted entity type:** AWS account. **This account**를 선택합니다(또는 교차 계정 설정의 경우 **Another AWS account**를 선택하고 1단계 IAM 사용자를 호스팅하는 AWS 계정 ID를 입력합니다).
|
||||
3. (권장) **Require external ID**를 체크하고 직접 생성한 값을 입력합니다 — 이는 5단계에서 CrewAI Platform에 붙여 넣을 공유 시크릿입니다.
|
||||
4. **Next**를 클릭합니다.
|
||||
5. `CrewAISecretsManagerRead` 정책을 연결합니다.
|
||||
6. **Next**를 클릭하고 역할 이름을 `CrewAISecretsManagerRole`로 지정한 다음 **Create role**을 클릭합니다.
|
||||
|
||||
**IAM 사용자가 역할을 맡을 수 있도록 허용:**
|
||||
|
||||
1. 방금 만든 역할을 열고 **ARN**을 복사합니다.
|
||||
2. IAM 콘솔에서 **Users**로 이동하여 1단계 사용자를 클릭한 다음 **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다.
|
||||
3. **JSON** 탭에서 다음을 붙여 넣습니다(`ROLE_ARN_FROM_ABOVE`를 교체):
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": "sts:AssumeRole",
|
||||
"Resource": "ROLE_ARN_FROM_ABOVE"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
4. 정책 이름을 `CrewAIAssumeSecretsRole`로 지정하고 **Create policy**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */}
|
||||
{/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 4단계 — 자격 증명 가져오기
|
||||
|
||||
<Tabs>
|
||||
<Tab title="정적 액세스 키">
|
||||
1. IAM 콘솔에서 1단계 사용자를 엽니다.
|
||||
2. **Security credentials** 탭을 클릭합니다.
|
||||
3. **Access keys** 아래에서 **Create access key**를 클릭합니다.
|
||||
4. 사용 사례로 **Application running outside AWS**(또는 **Other**)를 선택합니다. **Next**를 클릭합니다.
|
||||
5. (선택) 설명 태그를 추가합니다. **Create access key**를 클릭합니다.
|
||||
6. **Show**를 클릭하여 시크릿 액세스 키를 표시한 다음 **Access key ID**와 **Secret access key**를 모두 복사하거나 **Download .csv file**을 클릭합니다.
|
||||
|
||||
<Warning>
|
||||
시크릿 액세스 키는 한 번만 표시됩니다. 복사하지 않고 이 페이지를 닫으면 키를 삭제하고 새 키를 만들어야 합니다.
|
||||
</Warning>
|
||||
|
||||
자세한 내용은 AWS 문서를 참조하세요: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
|
||||
|
||||
{/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */}
|
||||
{/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
AssumeRole을 사용하더라도 CrewAI Platform은 여전히 IAM 사용자에 대한 액세스 키가 필요합니다 — `sts:AssumeRole` 호출을 수행하기 위한 호출 신원으로 해당 키를 사용합니다.
|
||||
|
||||
1. 위의 **정적 액세스 키** 탭에서 설명한 대로 사용자에 대한 액세스 키를 생성합니다.
|
||||
2. 3단계에서 만든 역할을 열고 다음을 복사합니다:
|
||||
- **Role ARN** (역할 요약에서).
|
||||
- 구성한 **External ID** (있는 경우) — 3단계에서 직접 설정했으므로 가지고 있는지 확인하세요.
|
||||
|
||||
{/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 5단계 — CrewAI Platform에 자격 증명 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */}
|
||||
|
||||
<Tabs>
|
||||
<Tab title="정적 액세스 키">
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `aws-prod`).
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** 시크릿이 위치한 AWS 리전(예: `us-east-1`). 읽으려는 시크릿의 리전과 일치해야 합니다.
|
||||
- **Access Key ID:** 4단계의 값.
|
||||
- **Secret Access Key:** 4단계의 값.
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 AWS 시크릿을 참조하는 환경 변수에서 사용됩니다.
|
||||
|
||||
**Role ARN**과 **External ID**는 비워둡니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `aws-prod-assumerole`).
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** 시크릿이 위치한 AWS 리전.
|
||||
- **Access Key ID:** 4단계의 IAM 사용자 액세스 키(STS 호출에 사용).
|
||||
- **Secret Access Key:** 4단계의 IAM 사용자 시크릿 액세스 키.
|
||||
- **Role ARN:** 4단계에서 복사한 Role ARN.
|
||||
- **External ID:** 역할의 신뢰 정책에 설정한 External ID(없으면 생략).
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
**두 모드의 런타임 동작:**
|
||||
|
||||
- **정적 액세스 키**만 사용하는 경우, CrewAI Platform은 제공된 키를 사용하여 AWS Secrets Manager를 직접 호출합니다.
|
||||
- **Role ARN**이 설정된 경우, CrewAI Platform은 먼저 제공된 액세스 키(구성된 경우 External ID 포함)로 `sts:AssumeRole`을 호출한 다음, STS가 반환한 단기 자격 증명을 사용하여 시크릿을 읽습니다.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */}
|
||||
|
||||
## 6단계 — AWS에 최소 하나의 시크릿 생성
|
||||
|
||||
AWS Secrets Manager에 시크릿이 아직 없다면, 7단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
|
||||
|
||||
[AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/)에서 **Store a new secret**을 클릭합니다.
|
||||
|
||||
- **Secret type:** **Other type of secret**을 선택합니다.
|
||||
- **Key/value pairs** — 다음 중 하나:
|
||||
- 하나 이상의 키/값 쌍 입력(구조화된 시크릿에 권장), 또는
|
||||
- 단일 문자열 값을 위해 **Plaintext** 탭 사용.
|
||||
- **Encryption key:** 특정 KMS 키 요구 사항이 없으면 `aws/secretsmanager`(AWS 관리형 키)를 사용합니다.
|
||||
|
||||
**Next**를 클릭한 다음 입력합니다:
|
||||
|
||||
- **Secret name:** 고유한 이름(예: `crewai/openai-api-key`).
|
||||
- **Description (optional):** 시크릿 용도에 대한 간단한 메모.
|
||||
|
||||
로테이션 및 검토 단계를 통해 **Next**를 클릭한 다음 **Store**를 클릭합니다.
|
||||
|
||||
<Note>
|
||||
**JSON 키 참조 구문.** 여러 키/값 쌍(JSON 객체)이 있는 시크릿을 저장하는 경우, CrewAI Platform은 환경 변수 참조에서 `secret-name#json_key` 구문을 사용하여 특정 필드를 추출할 수 있습니다. 예를 들어, `{"username": "...", "password": "..."}`가 있는 `database-credentials`라는 시크릿은 `database-credentials#password`로 참조할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
자세한 내용은 AWS 문서를 참조하세요: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */}
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */}
|
||||
|
||||
## 7단계 — 연결 테스트
|
||||
|
||||
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
|
||||
|
||||
성공 토스트는 CrewAI Platform이 AWS에 인증하고 계정의 시크릿을 읽을 수 있음을 확인합니다.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */}
|
||||
|
||||
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| `secretsmanager:ListSecrets`에서 `AccessDenied` | 정책이 연결되지 않았거나 잘못된 사용자입니다. 3단계를 다시 확인하세요. |
|
||||
| `kms:Decrypt`에서 `AccessDenied` | `KMSDecrypt` 문이 누락되었거나, 시크릿이 `Resource: "*"`로 다루지 않는 고객 관리형 KMS 키를 사용합니다. |
|
||||
| `InvalidClientTokenId` / `SignatureDoesNotMatch` | 잘못된 액세스 키 ID 또는 시크릿 액세스 키입니다. 4단계와 5단계를 다시 확인하세요. |
|
||||
| `RegionDisabledException` / 시크릿을 찾을 수 없음 | 자격 증명의 **Region**이 시크릿이 실제로 위치한 곳과 일치하지 않습니다. |
|
||||
| `sts:AssumeRole`에서 `AccessDenied` (AssumeRole만 해당) | IAM 사용자에 인라인 `sts:AssumeRole` 정책이 없거나, 역할의 신뢰 정책이 이 주체를 허용하지 않거나, External ID가 일치하지 않습니다. |
|
||||
| IAM 사용자 생성 직후 테스트는 통과하지만 다음 번에는 실패함 | IAM 자격 증명이 전역적으로 전파되는 데 1-2분 정도 걸릴 수 있습니다. 다시 시도하세요. |
|
||||
|
||||
## 다음 단계
|
||||
|
||||
이제 AWS가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
|
||||
|
||||
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
|
||||
- CrewAI Platform 환경 변수에서 AWS 시크릿을 참조합니다.
|
||||
|
||||
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다.
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
title: Azure Workload Identity Federation
|
||||
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Microsoft Entra Workload Identity Federation을 통해 Azure Key Vault를 구성합니다
|
||||
sidebarTitle: Workload Identity 사용
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **Microsoft Entra Workload Identity Federation**을 사용하여 Azure Key Vault를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Microsoft identity platform을 통해 이를 Entra 액세스 토큰과 교환하여 시크릿을 읽습니다 — 클라이언트 시크릿을 어디에도 저장하지 않습니다.
|
||||
|
||||
<Note>
|
||||
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [Azure Key Vault — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) 가이드를 참조하세요.
|
||||
</Note>
|
||||
|
||||
### 런타임 동작 방식
|
||||
|
||||
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
|
||||
2. 워커가 `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token`에서 JWT를 `client_assertion`(`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`)으로 Microsoft Entra에 제시하며, JWT의 발급자 + 주체와 일치하는 **Federated Identity Credential**을 가진 App Registration을 참조합니다.
|
||||
3. Entra가 플랫폼의 OIDC 디스커버리 문서와 JWKS에 대해 JWT를 검증한 다음, `https://vault.azure.net/.default`로 범위가 지정된 단기 액세스 토큰을 반환합니다.
|
||||
4. 워커가 Azure Key Vault를 호출하여 시크릿을 읽습니다.
|
||||
5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
|
||||
|
||||
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
|
||||
- 관리할 수 있는 Azure 구독과 Microsoft Entra 테넌트.
|
||||
- App Registration을 생성하고 Federated Identity Credential을 추가할 테넌트 권한.
|
||||
- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님).
|
||||
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
- **CrewAI Platform 설치가 Microsoft Entra에서 HTTPS를 통해 접근 가능해야 합니다.** Entra가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요.
|
||||
</Note>
|
||||
|
||||
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
|
||||
|
||||
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Microsoft Entra가 신뢰할 수 있는 federation 발급자로 등록할 URL입니다.
|
||||
|
||||
브라우저에서 URL을 엽니다:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
다음을 포함하는 JSON이 보일 것입니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
|
||||
|
||||
<Tip>
|
||||
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
## 2단계 — App Registration 생성
|
||||
|
||||
[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- **Redirect URI**는 비워둡니다.
|
||||
|
||||
**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 6단계에서 사용합니다.
|
||||
|
||||
{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */}
|
||||
|
||||
## 3단계 — Federated Identity Credential 추가
|
||||
|
||||
Federated Identity Credential은 Microsoft Entra에 다음을 알려줍니다: *이 발급자가 발급한 JWT를 신뢰하라, 이 주체로, 이 App Registration에 대한 client assertion으로 제시될 때.*
|
||||
|
||||
App Registration에서 **Certificates & secrets** → **Federated credentials** → **Add credential**로 이동합니다.
|
||||
|
||||
- **Federated credential scenario:** `Other issuer`.
|
||||
- **Issuer:** 1단계의 CrewAI Platform 발급자 URL(예: `https://<your-platform-host>`).
|
||||
- **Subject identifier:** `organization:<YOUR_CREWAI_ORG_UUID>` — 정확히 JWT의 `sub` 클레임 값. CrewAI Platform의 조직 설정에서 조직 UUID를 찾으세요. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다.
|
||||
- **Name:** 설명적인 레이블(예: `crewai-org-prod`).
|
||||
- **Audience:** `api://AzureADTokenExchange`. 이는 Microsoft Entra가 federated 자격 증명에 요구하는 고정 audience이며 CrewAI Platform이 JWT의 `aud` 클레임에 설정하는 값입니다.
|
||||
|
||||
**Add**를 클릭합니다.
|
||||
|
||||
<Tip>
|
||||
**조직별 격리.** 주체 식별자(`organization:<UUID>`)는 federated 자격 증명을 특정 CrewAI 조직의 토큰으로 제한합니다. 여러 CrewAI 조직이 하나의 App Registration을 공유해야 하는 경우, 조직당 하나의 Federated Identity Credential을 추가하세요(각각 조직의 UUID 사용).
|
||||
</Tip>
|
||||
|
||||
자세한 내용은 Microsoft 문서를 참조하세요: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust).
|
||||
|
||||
{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:<uuid>", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */}
|
||||
|
||||
## 4단계 — App Registration에 Key Vault 액세스 부여
|
||||
|
||||
대상 볼트에서 App Registration에 **Key Vault Secrets User**를 부여합니다 — 정적 자격 증명 경로에서 사용할 것과 동일한 역할입니다. 볼트 전체(더 간단함) 또는 시크릿별(최소 권한)을 사용하세요.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="볼트 전체 (더 간단함)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
볼트 전체 범위는 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**이 의존하는 `secrets/list` 권한을 부여합니다. 자동 완성이 작동하길 원한다면 이 탭을 선택하세요.
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="시크릿별 (최소 권한)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
시크릿별 바인딩은 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**을 비활성화합니다(자동 완성은 볼트 범위에서만 가능한 `secrets/list`가 필요합니다). 대신 전체 시크릿 이름을 입력하세요.
|
||||
|
||||
{/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="포털 (UI)">
|
||||
**볼트 전체** 할당:
|
||||
|
||||
1. Azure 포털에서 Key Vault를 엽니다.
|
||||
2. **Access control (IAM)** → **Add** → **Add role assignment**를 클릭합니다.
|
||||
3. 역할 **Key Vault Secrets User**를 선택하고 → **Next**를 클릭합니다.
|
||||
4. **Select members**를 클릭하고 App Registration `crewai-secrets-reader`를 검색한 다음 **Select**를 클릭합니다.
|
||||
5. **Review + assign**을 클릭합니다.
|
||||
|
||||
**시크릿별** 할당의 경우 동일한 흐름을 사용하지만 **Objects** → **Secrets** → 시크릿 선택 → 자체 **Access control (IAM)** 패널에서 시작합니다. 시크릿별 바인딩은 자동 완성을 비활성화합니다(위의 시크릿별 탭 참조).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 5단계 — Key Vault에 최소 하나의 시크릿 생성
|
||||
|
||||
테스트할 시크릿이 아직 없다면 Azure CLI를 통해 하나 만듭니다:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
또는 Azure 포털을 통해:
|
||||
|
||||
1. Key Vault를 열고 **Objects** → **Secrets**로 이동합니다.
|
||||
2. **Generate/Import**를 클릭합니다.
|
||||
3. **Upload options:** `Manual`. **Name:** 시크릿 이름(예: `openai-api-key`). **Secret value:** 값을 붙여 넣습니다.
|
||||
4. **Create**를 클릭합니다.
|
||||
|
||||
<Note>
|
||||
**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다.
|
||||
</Note>
|
||||
|
||||
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `azure-prod`).
|
||||
- **Cloud Provider:** `Azure`.
|
||||
- **Tenant ID:** 2단계의 Microsoft Entra **Directory (tenant) ID**.
|
||||
- **Client ID:** 2단계의 App Registration **Application (client) ID**.
|
||||
- (선택) Azure 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Set as default for Azure**를 체크합니다.
|
||||
|
||||
**Audience**는 `api://AzureADTokenExchange`로 고정되어 있습니다 — Microsoft Entra는 federated 자격 증명에 대해 이 정확한 audience를 요구하므로 폼에 Audience 필드가 표시되지 않습니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */}
|
||||
|
||||
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
|
||||
|
||||
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `azure-prod-wi`).
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다.
|
||||
- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`).
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다.
|
||||
|
||||
Workload Identity 아래에서는 폼이 **Key Vault URL**만 요청합니다 — 정적 자격 증명 필드(Tenant ID, Client ID, Client Secret)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. tenant + client는 연결된 WI 구성에서 가져옵니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
<Tip>
|
||||
**하나의 App Registration, 여러 볼트.** Key Vault URL은 WI 구성이 아닌 자격 증명에 있습니다. 따라서 하나의 App Registration(과 하나의 WI 구성)이 여러 Key Vault를 서비스할 수 있습니다 — 동일한 WI 구성에 연결된 볼트당 하나의 Secret Provider Credential을 만드세요.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */}
|
||||
|
||||
## 8단계 — 연결 테스트
|
||||
|
||||
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, federated `client_assertion`으로 Microsoft Entra에 제시한 다음, Entra가 볼트 범위 액세스 토큰을 반환하는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
|
||||
|
||||
성공적인 Test Connection은 Federated Identity Credential의 발급자, 주체, audience가 모두 일치하고 App Registration이 접근 가능함을 증명합니다. 시크릿별 Key Vault RBAC가 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿에 대한 `getSecret`은 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
|
||||
|
||||
## 9단계 — 환경 변수에서 시크릿 참조
|
||||
|
||||
다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
|
||||
## 10단계 — 로테이션 확인
|
||||
|
||||
배포가 실행 중인 상태에서 Key Vault의 시크릿을 로테이션합니다:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "rotated value"
|
||||
```
|
||||
|
||||
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
|
||||
|
||||
워커 로그에서 확인하려면 다음을 찾으세요:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (azure): N secret(s) resolved
|
||||
```
|
||||
|
||||
이 줄은 모든 kickoff에 나타나며 Azure Key Vault에 대한 새로운 `getSecret` 호출을 의미합니다.
|
||||
|
||||
엔드 투 엔드 fingerprint 기반 검증은 [로테이션 엔드 투 엔드 검증](/ko/enterprise/features/secrets-manager/verify-rotation)을 참조하세요.
|
||||
|
||||
## 문제 해결
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| Test Connection이 핸드셰이크 오류로 실패함 | federated `client_assertion`이 Microsoft Entra에 의해 거부되었습니다. Federated Identity Credential의 **Issuer**가 플랫폼의 `issuer` 값과 정확히 일치하는지, **Subject**가 `organization:<your-org-uuid>`(JWT의 `sub` 클레임과 일치)인지, **Audience**가 `api://AzureADTokenExchange`인지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 Entra에서 접근 가능한지 확인하세요. |
|
||||
| `AADSTS70021: No matching federated identity record found for presented assertion` | Federated Identity Credential의 **Issuer** + **Subject** + **Audience**가 모두 JWT와 정확히 일치하지 않습니다. 3단계를 다시 확인하세요: 주체는 `organization:<your-org-uuid>`(JWT의 `sub` 클레임과 일치)여야 하고, audience는 `api://AzureADTokenExchange`여야 합니다. |
|
||||
| `AADSTS700024: Client assertion is not within its valid time range` | CrewAI Platform 호스트의 시계가 실제 시간과 크게 다릅니다. 호스트의 NTP를 확인하세요. |
|
||||
| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra가 JWT의 서명을 확인할 수 없습니다. `https://<your-platform-host>/oauth2/jwks`가 공용 인터넷에서 접근 가능하고 유효한 JWKS를 제공하는지 확인하세요. |
|
||||
| Secret Name 자동 완성에 `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` 표시 | App Registration의 **Key Vault Secrets User** 역할이 단일 시크릿으로 범위 지정되어 있습니다. `list` 데이터 플레인 액션이 허용되도록 볼트 범위에서 역할을 부여하세요. 4단계를 참조하세요. |
|
||||
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 시크릿별 Key Vault RBAC가 없습니다. 해당 특정 시크릿에 대한 **Key Vault Secrets User**를 감사하거나(또는 역할 할당을 볼트 범위로 확장). |
|
||||
| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 4단계의 역할을 다시 부여하세요. |
|
||||
| `azure_vault_url is required for Azure secret resolution` (워커 로그) | Secret Provider Credential에 **Key Vault URL**이 없습니다. 7단계를 다시 확인하세요. |
|
||||
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
|
||||
|
||||
### 참고 링크
|
||||
|
||||
- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
|
||||
- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
|
||||
- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
|
||||
- 다중 클라우드의 경우 AWS 동등 설정은 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)에, GCP 동등 설정은 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에 있습니다.
|
||||
|
||||
## 스크린샷 참조
|
||||
|
||||
위의 자리 표시자는 다음에 매핑됩니다:
|
||||
|
||||
- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼.
|
||||
- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, **Other issuer**, 플랫폼 발급자 URL, 주체 `organization:<uuid>`, audience `api://AzureADTokenExchange`.
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**와 App Registration이 선택됨.
|
||||
- `04-per-secret-rbac.png` — 동일한 폼이지만 단일 시크릿의 IAM 범위에서(대체 최소 권한 경로).
|
||||
- `05-amp-add-wi-config-azure.png` — Cloud Provider = Azure, Tenant ID, Client ID가 채워진 CrewAI Platform "Add Workload Identity Config" 폼.
|
||||
- `06-amp-wi-list-with-azure.png` — 생성 후 Workload Identity 목록 페이지, AWS, GCP 및 새 Azure 구성 행 표시.
|
||||
- `07-amp-add-credential-azure-wi.png` — Provider = Azure Key Vault, Auth = Workload Identity, WI 구성 선택, Key Vault URL이 채워진 "Add Secret Provider Credential" 폼.
|
||||
196
docs/edge/ko/enterprise/features/secrets-manager/azure.mdx
Normal file
196
docs/edge/ko/enterprise/features/secrets-manager/azure.mdx
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: Azure Key Vault
|
||||
description: Azure Key Vault를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다
|
||||
sidebarTitle: 정적 자격 증명 사용
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **클라이언트 시크릿이 있는 Microsoft Entra App Registration**을 사용하여 Azure Key Vault를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Azure Key Vault에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
|
||||
|
||||
<Note>
|
||||
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
이 가이드는 Azure 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- Microsoft Entra에서 App Registration을 생성하고 Key Vault 리소스에 역할 할당을 부여할 권한이 있는 Azure 구독.
|
||||
- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님). 볼트가 여전히 액세스 정책을 사용하는 경우, 볼트의 **Access configuration** 블레이드에서 RBAC로 전환하세요.
|
||||
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 1단계 — App Registration 생성
|
||||
|
||||
App Registration은 CrewAI Platform이 인증할 Microsoft Entra 측 ID입니다.
|
||||
|
||||
[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- **Redirect URI**는 비워둡니다.
|
||||
|
||||
**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 4단계에서 둘 다 CrewAI Platform에 붙여 넣습니다.
|
||||
|
||||
자세한 내용은 Microsoft 문서를 참조하세요: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
|
||||
|
||||
{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */}
|
||||
|
||||
## 2단계 — 클라이언트 시크릿 생성
|
||||
|
||||
App Registration에서 **Certificates & secrets** → **Client secrets** → **New client secret**으로 이동합니다.
|
||||
|
||||
- **Description:** `crewai-platform`
|
||||
- **Expires:** 로테이션 정책과 일치하는 기간을 선택합니다(Microsoft은 이를 24개월로 제한).
|
||||
|
||||
**Add**를 클릭합니다. **Value** 열을 즉시 복사하세요 — 페이지를 떠난 후에는 다시 표시할 수 없습니다.
|
||||
|
||||
<Warning>
|
||||
클라이언트 시크릿은 장기 정적 자격 증명입니다. 값을 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 만료 전에 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 사용하세요.
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */}
|
||||
|
||||
## 3단계 — App Registration에 Key Vault 액세스 부여
|
||||
|
||||
CrewAI Platform은 Key Vault의 시크릿에 대한 읽기 액세스가 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **볼트 전체** 또는 최소 권한을 위한 **시크릿별**.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="볼트 전체 (더 간단함)">
|
||||
[Key Vault 콘솔](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults)에서 대상 볼트를 열고 **Access control (IAM)** → **Add** → **Add role assignment**로 이동합니다.
|
||||
|
||||
- **Role:** **Key Vault Secrets User**
|
||||
- **Assign access to:** User, group, or service principal
|
||||
- **Members:** App Registration(`crewai-secrets-reader`)을 검색하고 선택합니다.
|
||||
|
||||
**Review + assign**을 클릭합니다.
|
||||
|
||||
또는 Azure CLI를 통해:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="시크릿별 (최소 권한)">
|
||||
개별 시크릿 수준에서 역할을 부여합니다. CrewAI Platform이 액세스해야 하는 각 시크릿에 대해 반복합니다:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
**Key Vault Secrets User** 역할은 시크릿 값 읽기를 허용하지만 볼트의 모든 시크릿을 나열하는 것은 허용하지 않습니다. CrewAI Platform의 시크릿 이름 자동 완성도 `list`를 호출합니다 — 해당 권한은 볼트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 대신 전체 시크릿 이름을 입력하세요.
|
||||
</Tip>
|
||||
|
||||
## 4단계 — CrewAI Platform에 자격 증명 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `azure-prod`).
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`).
|
||||
- **Tenant ID:** 1단계의 Microsoft Entra **Directory (tenant) ID**.
|
||||
- **Client ID:** 1단계의 App Registration **Application (client) ID**.
|
||||
- **Client Secret:** 2단계에서 복사한 **Value**.
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 Azure 시크릿을 참조하는 환경 변수에서 사용됩니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */}
|
||||
|
||||
## 5단계 — Azure Key Vault에 최소 하나의 시크릿 생성
|
||||
|
||||
Key Vault에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
|
||||
|
||||
Key Vault 콘솔에서 **Objects** → **Secrets** → **Generate/Import**로 이동합니다.
|
||||
|
||||
- **Upload options:** `Manual`
|
||||
- **Name:** 예: `openai-api-key`
|
||||
- **Secret value:** 시크릿 값을 붙여 넣습니다
|
||||
- 나머지는 기본값으로 둡니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
또는 Azure CLI를 통해:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
<Note>
|
||||
**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**JSON 키 참조 구문.** Key Vault는 시크릿 값을 불투명한 문자열로 취급합니다. 시크릿 값이 JSON 객체인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
자세한 내용은 Microsoft 문서를 참조하세요: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
|
||||
|
||||
{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */}
|
||||
|
||||
## 6단계 — 연결 테스트
|
||||
|
||||
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
|
||||
|
||||
성공 토스트는 CrewAI Platform이 Microsoft Entra에 인증하고 볼트의 시크릿을 읽을 수 있음을 확인합니다.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */}
|
||||
|
||||
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| `AADSTS7000215: Invalid client secret provided` | 붙여 넣은 **Client Secret**이 잘못되었거나 만료되었습니다. 시크릿을 다시 생성하고(2단계) 자격 증명을 업데이트하세요. |
|
||||
| `AADSTS700016: Application not found in the directory` | **Tenant ID** 또는 **Client ID**가 App Registration과 일치하지 않습니다. 4단계를 다시 확인하세요. |
|
||||
| `Forbidden — caller does not have permission` | App Registration에 볼트(또는 시크릿별) **Key Vault Secrets User** 역할이 없습니다. 3단계를 다시 확인하세요. |
|
||||
| `Vault not found` / DNS 오류 | **Key Vault URL**이 잘못되었거나, 볼트에 공용 액세스를 차단하는 프라이빗 엔드포인트가 있습니다. 호스트가 `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`에 응답하는지 확인하세요. |
|
||||
| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 3단계의 역할을 다시 부여하세요. |
|
||||
|
||||
## 다음 단계
|
||||
|
||||
이제 Azure Key Vault가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
|
||||
|
||||
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
|
||||
- CrewAI Platform 환경 변수에서 Azure 시크릿을 참조합니다.
|
||||
|
||||
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)으로 전환하세요 — 동일한 볼트, 로테이션할 클라이언트 시크릿 없음, kickoff마다 시크릿을 가져옵니다.
|
||||
|
||||
## 스크린샷 참조
|
||||
|
||||
위의 자리 표시자는 다음에 매핑됩니다:
|
||||
|
||||
- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼.
|
||||
- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, 새로 생성된 시크릿 행이 표시됨(마스킹되기 전 Value 열 강조).
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**가 선택되고 App Registration이 멤버로 선택됨.
|
||||
- `04-per-secret-rbac.png` — 동일한 패널이지만 단일 시크릿 리소스로 범위 지정됨(대체 최소 권한 경로).
|
||||
- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" 폼: Provider = Azure Key Vault, 다섯 필드 모두 채워짐.
|
||||
- `06-create-secret.png` — `openai-api-key`와 붙여 넣은 값이 있는 Azure Key Vault "Create a secret" 패널.
|
||||
- `07-test-connection-success.png` — 자격 증명에서 **Test Connection**을 클릭한 후의 CrewAI Platform 성공 토스트 / 행 상태.
|
||||
@@ -0,0 +1,273 @@
|
||||
---
|
||||
title: GCP Workload Identity Federation
|
||||
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity Federation을 통해 Google Cloud Secret Manager를 구성합니다
|
||||
sidebarTitle: Workload Identity 사용
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **Workload Identity Federation**을 사용하여 Google Cloud Secret Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Security Token Service를 통해 이를 Google Cloud 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 서비스 계정 키를 어디에도 저장하지 않습니다.
|
||||
|
||||
<Note>
|
||||
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) 가이드를 참조하세요.
|
||||
</Note>
|
||||
|
||||
### 런타임 동작 방식
|
||||
|
||||
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
|
||||
2. 워커가 아래에서 설정한 Workload Identity Pool Provider를 참조하여 [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest)를 통해 JWT를 federated Google 자격 증명과 교환합니다.
|
||||
3. 워커가 federated 자격 증명을 직접 사용하여 시크릿을 읽기 위해 `secretmanager.googleapis.com:accessSecretVersion`을 호출합니다(federated 주체가 `roles/secretmanager.secretAccessor`를 보유함 — 4단계 참조).
|
||||
4. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
|
||||
|
||||
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
|
||||
- **Secret Manager API**, **Security Token Service API**, **IAM Credentials API**가 활성화된 Google Cloud 프로젝트. 콘솔에서 또는 다음을 통해 활성화하세요:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
- Workload Identity Pool, IAM 역할, 서비스 계정, (필요한 경우) 시크릿을 생성할 프로젝트 권한.
|
||||
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
- **CrewAI Platform 설치가 Google Cloud에서 HTTPS를 통해 접근 가능해야 합니다.** GCP STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요.
|
||||
</Note>
|
||||
|
||||
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
|
||||
|
||||
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Google이 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다.
|
||||
|
||||
브라우저에서 URL을 엽니다:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
다음을 포함하는 JSON이 보일 것입니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
|
||||
|
||||
<Tip>
|
||||
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
## 2단계 — Workload Identity Pool 생성
|
||||
|
||||
Workload Identity Pool은 신뢰할 수 있는 외부 ID를 위한 Google Cloud 측 컨테이너입니다. 이 풀 내부에 CrewAI Platform을 공급자로 등록합니다.
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools create crewai-pool \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--display-name="CrewAI Platform"
|
||||
```
|
||||
|
||||
또는 [Workload Identity Pools 콘솔](https://console.cloud.google.com/iam-admin/workload-identity-pools)에서 **Create Pool**을 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */}
|
||||
|
||||
## 3단계 — CrewAI Platform을 풀에 OIDC 공급자로 추가
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers create-oidc crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--display-name="CrewAI Platform OIDC" \
|
||||
--issuer-uri="https://<your-platform-host>" \
|
||||
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
|
||||
--attribute-condition="assertion.organization_id != ''"
|
||||
```
|
||||
|
||||
`--attribute-mapping`은 JWT 클레임을 Google 속성으로 매핑하는 방법을 Google에 알려줍니다:
|
||||
- `google.subject`는 주체 식별자입니다 — JWT의 `sub` 클레임에 매핑하며, CrewAI Platform은 이를 `organization:<uuid>`로 설정합니다.
|
||||
- `attribute.organization`은 사용자 정의 속성입니다 — JWT의 `organization_id` 클레임에 매핑하여 나중에 IAM 바인딩에서 참조할 수 있습니다.
|
||||
|
||||
`--attribute-condition`은 `organization_id` 클레임이 없는 토큰을 거부하는 심층 방어 검사입니다.
|
||||
|
||||
**Provider 리소스 이름**을 가져옵니다(audience 및 IAM 바인딩에 필요):
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers describe crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--format="value(name)"
|
||||
```
|
||||
|
||||
출력은 다음과 같습니다:
|
||||
|
||||
```
|
||||
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider
|
||||
```
|
||||
|
||||
이것이 6단계에서 CrewAI Platform의 **Workload Identity Provider** 값입니다. CrewAI Platform은 토큰을 발급할 때 OIDC audience를 `//iam.googleapis.com/<this-resource-name>`으로 자동으로 계산합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */}
|
||||
|
||||
## 4단계 — Federated 주체에 Secret Manager 액세스 부여
|
||||
|
||||
프로젝트 범위에서 두 Secret Manager 역할을 모두 federated 주체에 바인딩합니다 — 한 역할은 환경 변수 폼의 Secret Name 자동 완성을 활성화하고, 다른 역할은 자동화 kickoff 시점에 시크릿 값을 읽을 수 있게 합니다. 기능이 처음부터 끝까지 작동하려면 두 역할 모두 필요합니다.
|
||||
|
||||
```bash
|
||||
PRINCIPAL_SET="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/attribute.organization/<YOUR_CREWAI_ORG_UUID>"
|
||||
|
||||
# Secret Name 자동 완성에 필요 (secretmanager.secrets.list 호출)
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.viewer"
|
||||
|
||||
# kickoff 시점에 시크릿 값을 읽는 데 필요
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
`<PROJECT_NUMBER>`를 숫자 프로젝트 번호(`gcloud projects describe <YOUR_PROJECT_ID> --format='value(projectNumber)'`)로, `<YOUR_CREWAI_ORG_UUID>`를 시크릿을 읽을 수 있도록 허용할 CrewAI Platform 조직의 UUID로 교체합니다. 조직 UUID는 플랫폼 UI의 조직 설정 페이지나 API를 통해 찾을 수 있습니다. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다.
|
||||
|
||||
또는 Google Cloud 콘솔을 통해:
|
||||
|
||||
1. 프로젝트의 **IAM & Admin** → **IAM**을 엽니다.
|
||||
2. **GRANT ACCESS**를 클릭합니다.
|
||||
3. **New principals:** 전체 `principalSet://...attribute.organization/<YOUR_CREWAI_ORG_UUID>` 문자열을 붙여 넣습니다.
|
||||
4. 역할 **Secret Manager Viewer** (`roles/secretmanager.viewer`)를 할당합니다.
|
||||
5. **SAVE**를 클릭합니다.
|
||||
6. **GRANT ACCESS**를 다시 클릭하고 **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) 역할로 반복합니다.
|
||||
|
||||
<Tip>
|
||||
**조직별 격리.** `principalSet://...attribute.organization/<UUID>` 패턴은 특정 조직의 토큰에 대한 액세스를 제한합니다. 하나의 Google Cloud 프로젝트를 여러 CrewAI 조직이 공유하는 경우, 각 조직에 대해 올바른 UUID로 두 바인딩을 모두 반복하거나 — 격리가 필요하지 않으면 덜 제한적인 attribute condition을 사용하세요.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**시크릿별로 `secretAccessor` 범위 지정 (선택 사항).** `roles/secretmanager.secretAccessor`를 프로젝트 전체로 부여하고 싶지 않으면, 위의 두 번째 바인딩을 생략하고 대신 시크릿별로 바인딩합니다:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding <SECRET_NAME> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
어느 쪽이든 `roles/secretmanager.viewer`는 프로젝트 범위로 유지하세요 — `secretmanager.secrets.list`(자동 완성이 의존)는 시크릿별로 부여할 수 없습니다.
|
||||
</Tip>
|
||||
|
||||
## 5단계 — GCP에 최소 하나의 시크릿 생성
|
||||
|
||||
테스트할 시크릿이 아직 없다면 `gcloud` CLI를 통해 하나 만듭니다:
|
||||
|
||||
```bash
|
||||
echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
또는 [Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)을 통해:
|
||||
|
||||
1. GCP 프로젝트에서 **Secret Manager**를 엽니다.
|
||||
2. **+ CREATE SECRET**을 클릭합니다.
|
||||
3. **Name:** `crewai-test-keyword`. **Secret value:** 값을 붙여 넣습니다.
|
||||
4. **CREATE SECRET**을 클릭합니다.
|
||||
|
||||
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `gcp-prod`).
|
||||
- **Cloud Provider:** `GCP`.
|
||||
- **Workload Identity Provider:** 3단계의 provider 리소스 이름(예: `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`).
|
||||
- (선택) GCP 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Default Configuration**을 토글합니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */}
|
||||
|
||||
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
|
||||
|
||||
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `gcp-prod-wi`).
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다.
|
||||
- **Project ID:** GCP 프로젝트 ID(시크릿을 소유한 동일한 프로젝트).
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다.
|
||||
|
||||
Workload Identity 아래에서는 폼이 **Project ID**만 요청합니다 — **Service Account JSON** 필드는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. federated ID는 연결된 WI 구성에서 가져옵니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */}
|
||||
|
||||
## 8단계 — 연결 테스트
|
||||
|
||||
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, Security Token Service를 통해 federated Google 액세스 토큰과 교환합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
|
||||
|
||||
성공적인 Test Connection은 Workload Identity Pool, OIDC 공급자, attribute mapping, attribute condition이 모두 올바르게 연결되었음을 증명합니다. Secret Manager IAM이 올바르다는 것을 증명하지는 **않습니다** — `secretmanager.secrets.list`와 `secretmanager.versions.access`는 Secret Name 자동 완성이 로드되거나 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
|
||||
|
||||
## 9단계 — 환경 변수에서 시크릿 참조
|
||||
|
||||
다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
|
||||
## 10단계 — 로테이션 확인
|
||||
|
||||
배포가 실행 중인 상태에서 새 버전을 추가하여 GCP의 시크릿을 로테이션합니다(Secret Manager는 기본적으로 항상 최신 활성화 버전을 읽음):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
|
||||
|
||||
워커 로그에서 확인하려면 다음을 찾으세요:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (gcp): N secret(s) resolved
|
||||
```
|
||||
|
||||
이 줄은 모든 kickoff에 나타나며 GCP에 대한 새로운 `accessSecretVersion` 호출을 의미합니다.
|
||||
|
||||
## 문제 해결
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| Test Connection이 핸드셰이크 오류로 실패함 | STS 토큰 교환이 거부되었습니다. Workload Identity Pool이 존재하는지, OIDC provider의 발급자가 플랫폼의 `issuer` 값과 일치하는지, attribute condition이 JWT의 클레임을 수락하는지 확인하세요. 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 GCP에서 접근 가능한지 확인하세요. |
|
||||
| `Could not refresh access token: invalid_target` | audience 클레임이 Workload Identity Provider의 예상 audience와 일치하지 않습니다. CrewAI Platform이 audience를 자동으로 설정합니다. 사용자 정의한 경우 `//iam.googleapis.com/<provider-resource-name>`과 일치하는지 확인하세요. |
|
||||
| `Failed to fetch JWKS from issuer` | GCP STS가 CrewAI Platform 호스트에 도달할 수 없습니다. 호스트가 인터넷에서 접근 가능하고 `/.well-known/openid-configuration`이 200을 반환하는지 확인하세요. |
|
||||
| `Attribute condition rejected token` | OIDC provider의 attribute condition(3단계)이 `organization_id`를 요구합니다. CrewAI Platform은 항상 이 클레임을 설정하므로 보통 잘못 구성된 풀/공급자를 의미합니다. provider의 attribute condition을 다시 확인하세요. |
|
||||
| Secret Name 자동 완성에 `PERMISSION_DENIED: secretmanager.secrets.list` 표시 | federated 주체에 프로젝트 범위의 `roles/secretmanager.viewer`가 없습니다. `secretmanager.secrets.list` 권한은 프로젝트 범위에서만 가능하며 시크릿별로 부여할 수 없습니다. 4단계를 참조하세요. |
|
||||
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 `secretmanager.versions.access`가 없습니다. `roles/secretmanager.secretAccessor`(프로젝트 범위 또는 4단계에서 그렇게 범위 지정한 경우 시크릿별)를 감사하세요. |
|
||||
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
|
||||
|
||||
### 참고 링크
|
||||
|
||||
- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation)
|
||||
- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
|
||||
- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control)
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
|
||||
- 다중 클라우드의 경우 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요.
|
||||
189
docs/edge/ko/enterprise/features/secrets-manager/gcp.mdx
Normal file
189
docs/edge/ko/enterprise/features/secrets-manager/gcp.mdx
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
title: Google Cloud Secret Manager
|
||||
description: Google Cloud Secret Manager를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다
|
||||
sidebarTitle: 정적 자격 증명 사용
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **서비스 계정 자격 증명**을 사용하여 Google Cloud Secret Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Google Cloud 프로젝트에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
|
||||
|
||||
<Note>
|
||||
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
이 가이드는 GCP 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<Note>
|
||||
시작하기 전에 다음을 준비하세요:
|
||||
|
||||
- **Secret Manager API**가 활성화된 Google Cloud 프로젝트. [APIs & Services 콘솔](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com)에서 또는 `gcloud`를 통해 활성화하세요:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
- 서비스 계정 생성, IAM 역할 부여, (필요한 경우) 시크릿 생성에 대한 프로젝트 권한.
|
||||
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
</Note>
|
||||
|
||||
## 1단계 — 서비스 계정 생성
|
||||
|
||||
서비스 계정은 CrewAI Platform이 인증할 GCP 측 ID입니다.
|
||||
|
||||
[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 **Create Service Account**를 클릭합니다.
|
||||
|
||||
- **Service account name:** `crewai-secrets-reader`
|
||||
- **Service account ID:** 이름에서 자동으로 채워짐(예: `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`)
|
||||
- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform"
|
||||
|
||||
**Create and Continue**를 클릭합니다. 이 화면에서 선택적 권한 부여는 건너뜁니다 — 역할은 2단계에서 연결합니다. **Done**을 클릭합니다.
|
||||
|
||||
자세한 내용은 GCP 문서를 참조하세요: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */}
|
||||
|
||||
## 2단계 — Secret Manager 액세스 부여
|
||||
|
||||
CrewAI Platform은 프로젝트의 시크릿을 나열하고 읽을 수 있는 권한이 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **프로젝트 전체** 또는 최소 권한을 위한 **시크릿별**.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="프로젝트 전체 (더 간단함)">
|
||||
[IAM 콘솔](https://console.cloud.google.com/iam-admin/iam)에서 **Grant Access**를 클릭하고:
|
||||
|
||||
- **New principals:** 1단계 서비스 계정의 이메일.
|
||||
- **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
|
||||
|
||||
**Save**를 클릭합니다.
|
||||
|
||||
또는 `gcloud`를 통해:
|
||||
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="시크릿별 (최소 권한)">
|
||||
CrewAI Platform이 액세스해야 하는 특정 시크릿에만 역할을 부여합니다. 각 시크릿에 대해 반복합니다:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
또는 콘솔에서: [Secret Manager](https://console.cloud.google.com/security/secret-manager)에서 각 시크릿을 열고, 오른쪽 패널의 **Permissions**를 클릭한 다음 서비스 계정에 **Secret Manager Secret Accessor**를 부여합니다.
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
`roles/secretmanager.secretAccessor` 역할은 시크릿 값에 대한 읽기 전용 액세스를 부여합니다. CrewAI Platform은 또한 환경 변수 폼의 자동 완성 경험을 위해 `secretmanager.secrets.list`를 호출합니다 — 해당 권한은 프로젝트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 전체 시크릿 이름을 입력해야 합니다.
|
||||
</Tip>
|
||||
|
||||
## 3단계 — 서비스 계정 키 생성
|
||||
|
||||
[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 1단계의 서비스 계정을 엽니다.
|
||||
|
||||
- **Keys** 탭을 클릭합니다.
|
||||
- **Add Key** → **Create new key**를 클릭합니다.
|
||||
- **Key type:** JSON.
|
||||
- **Create**를 클릭합니다. 브라우저가 JSON 파일을 다운로드합니다 — 안전하게 보관하세요. 다시 다운로드할 수 없습니다.
|
||||
|
||||
또는 `gcloud`를 통해:
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
|
||||
--iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
|
||||
```
|
||||
|
||||
<Warning>
|
||||
서비스 계정 키는 장기 정적 자격 증명입니다. 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 정기적으로 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 사용하세요.
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */}
|
||||
|
||||
## 4단계 — CrewAI Platform에 자격 증명 추가
|
||||
|
||||
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Name:** 설명적인 이름(예: `gcp-prod`).
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Project ID:** GCP 프로젝트 ID(예: `my-crewai-prod`).
|
||||
- **Service Account JSON:** 3단계에서 다운로드한 JSON 파일의 전체 내용을 붙여 넣습니다.
|
||||
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 GCP 시크릿을 참조하는 환경 변수에서 사용됩니다.
|
||||
|
||||
**Create**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */}
|
||||
|
||||
## 5단계 — GCP에 최소 하나의 시크릿 생성
|
||||
|
||||
GCP Secret Manager에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
|
||||
|
||||
[Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)에서 **Create secret**을 클릭합니다.
|
||||
|
||||
- **Name:** 고유한 이름(예: `openai-api-key`).
|
||||
- **Secret value:** 원시 값을 붙여 넣거나 파일을 업로드합니다.
|
||||
- 특정 요구 사항이 없으면 로테이션, 복제 및 기타 설정을 기본값으로 둡니다.
|
||||
|
||||
**Create secret**을 클릭합니다.
|
||||
|
||||
또는 `gcloud`를 통해:
|
||||
|
||||
```bash
|
||||
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
|
||||
--data-file=- \
|
||||
--project=YOUR_PROJECT_ID \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
<Note>
|
||||
**JSON 키 참조 구문.** GCP Secret Manager는 시크릿 값을 불투명한 blob으로 취급합니다. 시크릿 값이 JSON 문자열인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
</Note>
|
||||
|
||||
자세한 내용은 GCP 문서를 참조하세요: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */}
|
||||
|
||||
## 6단계 — 연결 테스트
|
||||
|
||||
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
|
||||
|
||||
성공 토스트는 CrewAI Platform이 GCP에 인증하고 프로젝트의 시크릿을 읽을 수 있음을 확인합니다.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */}
|
||||
|
||||
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| 시크릿 나열 시 `PERMISSION_DENIED` | 서비스 계정에 `roles/secretmanager.secretAccessor`가 없거나, 시크릿별로 범위를 지정했습니다(`list`가 부여되지 않음). 2단계를 다시 확인하세요. |
|
||||
| `secretmanager.secrets.access`에서 `PERMISSION_DENIED` | 위와 동일하지만 특정 시크릿에 대한 것입니다. 해당 시크릿에 서비스 계정이 accessor 역할을 갖고 있는지 확인하세요. |
|
||||
| `unauthorized_client` / `invalid_grant` | 붙여 넣은 서비스 계정 JSON이 유효하지 않거나, 만료되었거나, 삭제된 서비스 계정용입니다. 키를 다시 만들고(3단계) 다시 붙여 넣으세요. |
|
||||
| `Project ID does not match` | CrewAI Platform의 Project ID 필드가 서비스 계정/시크릿을 소유한 프로젝트와 일치하지 않습니다. 4단계를 다시 확인하세요. |
|
||||
| `API not enabled` | 프로젝트에 Secret Manager API가 활성화되어 있지 않습니다. 사전 준비 사항을 참조하세요. |
|
||||
|
||||
## 다음 단계
|
||||
|
||||
이제 GCP가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
|
||||
|
||||
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
|
||||
- CrewAI Platform 환경 변수에서 GCP 시크릿을 참조합니다.
|
||||
|
||||
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Secrets Manager 개요
|
||||
description: 외부 시크릿 저장소를 CrewAI Platform에 연결하고 환경 변수에서 관리되는 시크릿을 참조합니다
|
||||
sidebarTitle: 개요
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Secrets Manager 기능은 조직에서 외부 시크릿 저장소(AWS Secrets Manager, Google Cloud Secret Manager 또는 Azure Key Vault)를 연결하고, 자동화(Automation) 및 Crew의 환경 변수에서 해당 시크릿을 직접 참조할 수 있게 해줍니다. 플랫폼에 평문 값을 붙여 넣는 대신, 각 공급자별로 자격 증명 한 세트만 저장하고 시크릿을 이름으로 참조합니다.
|
||||
|
||||
이를 통해 얻는 이점은 다음과 같습니다:
|
||||
|
||||
- **중앙 집중식 저장** — CrewAI Platform 설정을 편집하는 대신 공급자에서 시크릿을 관리합니다. CrewAI Platform은 시크릿 값의 평문 사본을 보관하지 않습니다.
|
||||
- **노출 감소** — 민감한 값이 CrewAI Platform 설정에 평문으로 존재하지 않습니다.
|
||||
- **클라우드 네이티브 감사 가능성** — 공급자의 감사 로그에 모든 시크릿 읽기 작업이 기록됩니다.
|
||||
|
||||
<Note>
|
||||
Secrets Manager(정적 자격 증명 및 Workload Identity 경로 모두)는 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 필요합니다.
|
||||
</Note>
|
||||
|
||||
## 두 가지 경로: 정적 자격 증명 vs Workload Identity
|
||||
|
||||
CrewAI Platform을 클라우드의 시크릿 저장소에 연결하는 방법은 두 가지가 있습니다. **로테이션 동작 방식에서 큰 차이가 있으므로**, 시크릿이 얼마나 자주 로테이션되는지와 보안 정책의 엄격함에 따라 선택하세요.
|
||||
|
||||
| 항목 | 정적 자격 증명 | Workload Identity (OIDC Federation) |
|
||||
|---|---|---|
|
||||
| **인증** | 장기 액세스 키 / 서비스 계정 JSON을 CrewAI Platform에 저장 | 워커 프로세스마다 발급되는 단기 토큰; 어디에도 정적 자격 증명을 저장하지 않음 |
|
||||
| **로테이션 전파** | 배포 시점에 해석되어 **배포 컨테이너 이미지에 박힘** — 로테이션된 값을 반영하려면 재배포 필요 | **자동화 실행 시점**에 해석됨 — 로테이션된 값이 재배포 없이 다음 kickoff에 전파됨 |
|
||||
| **설정 노력** | 더 적음 — 키 붙여 넣기 / 서비스 계정 JSON 업로드 | 더 많음 — CrewAI Platform을 클라우드에 OIDC 공급자로 등록하고 신뢰 정책 구성 |
|
||||
| **적합한 용도** | 시작 단계, 드물게 로테이션되는 시크릿, 단일 계정 배포 | 프로덕션, 자주 로테이션되는 시크릿, 장기 자격 증명을 금지하는 규정 준수 환경 |
|
||||
|
||||
<Note>
|
||||
**두 경로 모두 환경 변수에서 시크릿을 참조하는 동일한 UI 흐름을 사용합니다**([Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage) 참조). 차이점은 전적으로 플랫폼이 클라우드에 어떻게 인증하고 언제 시크릿 값을 읽는지에 있습니다.
|
||||
</Note>
|
||||
|
||||
### 설정 가이드 선택
|
||||
|
||||
| 공급자 | 정적 자격 증명 | Workload Identity |
|
||||
|---|---|---|
|
||||
| AWS Secrets Manager | [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/ko/enterprise/features/secrets-manager/aws-workload-identity) |
|
||||
| Google Cloud Secret Manager | [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) |
|
||||
| Azure Key Vault | [Azure — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity) |
|
||||
|
||||
<Note>
|
||||
Secrets Manager 및 Workload Identity UI는 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다.
|
||||
</Note>
|
||||
|
||||
## 동작 방식
|
||||
|
||||
Secrets Manager 설정은 클라우드 공급자와 CrewAI Platform 양쪽 모두에서 작업하는 3단계 흐름입니다:
|
||||
|
||||
1. **관리자가 공급자 자격 증명을 구성합니다.** 이는 클라우드 측 작업이며 — 선택한 경로(정적 자격 증명 또는 Workload Identity)에 따라 작업이 다릅니다. 공급자별 가이드에서 처음부터 끝까지 다룹니다.
|
||||
2. **관리자(또는 권한이 부여된 멤버)가 환경 변수에서 시크릿을 참조합니다.** Environment Variables 페이지에서 공급자 자격 증명을 선택하고 시크릿 이름을 선택합니다. [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
|
||||
3. **자동화가 런타임에 해석된 값을 받습니다.** Crew 또는 자동화가 실행될 때, CrewAI Platform이 공급자에서 시크릿을 가져와 환경 변수 값으로 주입합니다. Workload Identity의 경우 이 가져오기는 매 kickoff마다 수행됩니다(로테이션 인식). 정적 자격 증명의 경우 이 가져오기는 배포 시점에 수행되고 값이 배포 이미지에 박힙니다.
|
||||
|
||||
## 가시성 및 범위
|
||||
|
||||
<Note>
|
||||
WI 기반 환경 변수는 평문 환경 변수와 동일한 할당 모델을 따릅니다: 자동화는 명시적으로 할당된 WI 기반 변수만 해석합니다. 해당 자동화의 Environment Variables 페이지에서 WI 기반 변수를 자동화에 할당하세요; 조직 수준 또는 Studio 프로젝트에 정의된 변수는 할당하기 전까지 kickoff에서 해석되지 않습니다.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
시크릿 가져오기 단계는 매 kickoff마다 실행되지만, 배포에 WI 기반 환경 변수가 할당되어 있을 때만 실제로 작업을 수행합니다. 할당된 변수 각각에 대해, 런타임은 매 crew, flow, training, test, 또는 checkpoint-restore kickoff마다 클라우드 공급자에서 값을 해석하여 프로세스 환경에 기록합니다. 할당된 변수가 없으면 이 단계는 no-op입니다. 그렇지 않은 경우, 비용은 할당된 변수 수에 비례합니다: kickoff당 약간의 추가 지연 시간과 변수당 하나의 클라우드 측 audit log 항목.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
Workload Identity *구성* 수준에서는 오늘날에도 여전히 조직 전체에 적용됩니다. 조직 내 모든 자동화는 조직이 등록한 모든 Workload Identity 구성을 기반으로 부트스트랩되며, 오늘날에는 특정 Workload Identity 구성을 특정 자동화에 바인딩할 수 없습니다. 자동화별 Workload Identity 범위 지정은 로드맵에 있습니다. 그때까지는 조직 내 모든 자동화가 사용해도 되는 Workload Identity 구성만 등록하세요.
|
||||
</Warning>
|
||||
|
||||
## 권한
|
||||
|
||||
Secrets Manager 접근을 제어하는 두 가지 CrewAI Platform 기능:
|
||||
|
||||
- `secret_providers` — 공급자 자격 증명을 보거나 관리할 수 있는 사람을 제어합니다.
|
||||
- `environment_variables` — 시크릿을 참조하는 환경 변수를 포함하여 환경 변수를 생성하고 편집할 수 있는 사람을 제어합니다.
|
||||
|
||||
세 번째 기능은 Workload Identity 설정을 제어합니다:
|
||||
|
||||
- `workload_identity_configs` — Workload Identity 구성을 보거나 관리할 수 있는 사람을 제어합니다. Workload Identity 경로를 사용하는 경우에만 필요합니다.
|
||||
|
||||
소유자(Owner)는 항상 전체 접근 권한을 가집니다. 멤버는 기본적으로 `secret_providers` 또는 `workload_identity_configs`에 대한 접근 권한을 **받지 않으며**, 사용자 정의 역할을 통해 권한을 명시적으로 부여받아야 합니다. 전체 매트릭스와 단계별 지침은 [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
|
||||
|
||||
## 다음 단계
|
||||
|
||||
원하는 경로를 선택하세요:
|
||||
|
||||
- **정적 자격 증명** (더 간단함, 로테이션 시 재배포 필요):
|
||||
- [AWS Secrets Manager 구성](/ko/enterprise/features/secrets-manager/aws)
|
||||
- [Google Cloud Secret Manager 구성](/ko/enterprise/features/secrets-manager/gcp)
|
||||
- [Azure Key Vault 구성](/ko/enterprise/features/secrets-manager/azure)
|
||||
- **Workload Identity** (로테이션 인식, 재배포 불필요):
|
||||
- [AWS Workload Identity 구성](/ko/enterprise/features/secrets-manager/aws-workload-identity)
|
||||
- [GCP Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
- [Azure Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/azure-workload-identity)
|
||||
- 그리고: [환경 변수에서 시크릿을 사용하고 권한 관리하기](/ko/enterprise/features/secrets-manager/usage)
|
||||
137
docs/edge/ko/enterprise/features/secrets-manager/usage.mdx
Normal file
137
docs/edge/ko/enterprise/features/secrets-manager/usage.mdx
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Secrets Manager 사용하기
|
||||
description: CrewAI Platform에서 권한을 관리하고 환경 변수에서 관리되는 시크릿을 참조합니다
|
||||
sidebarTitle: 사용 및 권한
|
||||
icon: "list-check"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 공급자 중립적입니다. 사용자(또는 다른 관리자)가 이미 최소 하나의 Secret Provider Credential을 구성했다고 가정합니다. 원하는 경로에 따라 설정 가이드를 선택하세요:
|
||||
|
||||
- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
|
||||
이 가이드를 사용하여 다음을 수행하세요:
|
||||
|
||||
- 조직 멤버에게 적절한 권한을 부여합니다.
|
||||
- 자동화의 환경 변수에서 시크릿을 참조합니다.
|
||||
- 런타임에서 모든 것이 올바르게 해석되는지 확인합니다.
|
||||
|
||||
## 권한 (RBAC)
|
||||
|
||||
Secrets Manager를 사용할 때 관련된 세 가지 CrewAI Platform 기능:
|
||||
|
||||
- `secret_providers` — **Secret Provider Credentials** 페이지에 대한 접근을 제어합니다.
|
||||
- `workload_identity_configs` — **Workload Identity** 페이지에 대한 접근을 제어합니다(WI 경로를 사용하는 경우에만 관련됨).
|
||||
- `environment_variables` — 환경 변수를 생성하거나 편집할 수 있는 사람을 제어합니다.
|
||||
|
||||
각 기능에는 두 가지 작업 수준이 있습니다: `read`와 `manage`. `manage`를 부여하면 자동으로 `read`를 포함합니다.
|
||||
|
||||
### 부여할 권한
|
||||
|
||||
| 목표 | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|
||||
|---|---|---|---|
|
||||
| 환경 변수에서 기존 정적 자격 증명 사용 (공급자 편집 불가) | `read` | — | `manage` |
|
||||
| 정적 자격 증명 생성, 편집 또는 삭제 | `manage` | — | `manage` |
|
||||
| 환경 변수에서 기존 Workload Identity 기반 자격 증명 사용 | `read` | — | `manage` |
|
||||
| Workload Identity 구성(및 이를 참조하는 자격 증명) 생성, 편집 또는 삭제 | `manage` | `manage` | `manage` |
|
||||
|
||||
<Note>
|
||||
**소유자(Owner)**는 모든 기능에 대해 자동으로 전체 접근 권한을 가집니다. 기본 **멤버(Member)** 역할은 의도적으로 `secret_providers` 및 `workload_identity_configs`를 제외합니다 — 관리자는 사용자 정의 역할을 통해 멤버에게 명시적으로 옵트인해야 합니다.
|
||||
</Note>
|
||||
|
||||
### 할당 방법
|
||||
|
||||
1. CrewAI Platform에서 **Settings** → **Roles**로 이동합니다. 이 페이지에서 새 역할을 생성하고, 각 역할의 권한을 편집하며, 조직의 기존 멤버에게 역할을 할당할 수 있습니다.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */}
|
||||
{/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}
|
||||
|
||||
2. **Create Role**을 클릭하여 새 역할을 만들거나, 기존 역할을 열어 권한을 편집합니다.
|
||||
|
||||
3. 역할의 권한 편집기에서 위 표에 따라 관련 기능을 토글합니다:
|
||||
|
||||
- `secret_providers`: 이 역할이 기존 자격 증명만 사용하면 되는 경우 **read**를 선택하고, 자격 증명을 생성, 편집, 삭제할 수도 있어야 하면 **manage**를 선택합니다.
|
||||
- `environment_variables`: 역할이 시크릿을 참조하는 환경 변수를 생성할 수 있도록 **manage**를 선택합니다.
|
||||
|
||||
{/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */}
|
||||
{/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}
|
||||
|
||||
4. 역할을 저장합니다.
|
||||
|
||||
5. 동일한 Roles 페이지(또는 조직 Members 목록)에서 해당 멤버에게 역할을 할당합니다.
|
||||
|
||||
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
|
||||
|
||||
## 환경 변수에서 시크릿 참조하기
|
||||
|
||||
공급자 자격 증명이 존재하고 역할에 적절한 권한이 있으면, 모든 환경 변수에서 관리되는 시크릿을 참조할 수 있습니다.
|
||||
|
||||
CrewAI Platform에서 **Environment Variables**로 이동하여 **Add Environment Variables**를 클릭합니다.
|
||||
|
||||
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
|
||||
|
||||
폼을 작성합니다:
|
||||
|
||||
- **Key** — 환경 변수의 이름입니다. 문자나 밑줄로 시작해야 하며, 문자, 숫자, 밑줄만 포함해야 합니다. 관례적으로 대문자로 작성합니다(예: `OPENAI_API_KEY`).
|
||||
|
||||
- **Value Source** — 값의 출처를 선택합니다:
|
||||
- **Direct Value** — 직접 입력하는 평문 값입니다. 공급자를 사용하고 싶지 않을 때 사용합니다.
|
||||
- **Use AWS default** (또는 공급자에 해당하는 항목) — 해당 공급자 유형에서 기본값으로 표시된 자격 증명을 사용합니다.
|
||||
- **특정 명명된 자격 증명** — 이름으로 자격 증명을 선택합니다. 동일한 공급자에 대해 여러 자격 증명(예: `aws-prod`와 `aws-staging`)이 있고 하나를 명시적으로 선택하려는 경우에 사용합니다.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */}
|
||||
|
||||
- **Secret Name** — 공급자의 시크릿 이름입니다. 자격 증명이 선택되면 이 필드에서 자동 완성을 제공합니다: 입력을 시작하면 CrewAI Platform이 일치하는 시크릿 이름을 공급자에 쿼리합니다.
|
||||
|
||||
구조화된(JSON) 시크릿에서 단일 필드를 추출하려면 `secret-name#json_key` 구문을 사용합니다. 예를 들어, `{"username": "...", "password": "..."}` 값을 가진 시크릿 `database-credentials`가 있다면, `database-credentials#password`로 참조하여 비밀번호만 주입할 수 있습니다.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */}
|
||||
|
||||
<Note>
|
||||
**Azure Key Vault 참고:** Azure 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 `Secret Name` 필드의 밑줄을 자동으로 하이픈으로 변환합니다(예: `db_password`는 `db-password`로 전송됨).
|
||||
</Note>
|
||||
|
||||
**Create**를 클릭하여 변수를 저장합니다.
|
||||
|
||||
{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */}
|
||||
|
||||
<Tip>
|
||||
기존 환경 변수를 편집할 때 **Value** 필드를 비워두면 현재 값이 유지됩니다. 이는 의도된 동작이며 — 값을 다시 입력하지 않고도 다른 필드(시크릿 이름이나 자격 증명 등)를 변경할 수 있게 해줍니다.
|
||||
</Tip>
|
||||
|
||||
## 작동 여부 검증
|
||||
|
||||
엔드 투 엔드 검증 방법:
|
||||
|
||||
1. 다른 환경 변수와 동일한 방식으로 자동화, Crew 또는 배포에서 환경 변수를 참조합니다.
|
||||
2. 자동화를 배포합니다.
|
||||
3. 실행을 트리거하고 성공적으로 완료되는지 확인합니다.
|
||||
|
||||
### 로테이션 동작은 자격 증명 경로에 따라 다릅니다
|
||||
|
||||
| 자격 증명 경로 | 시크릿이 읽히는 시점 | 로테이션 시 필요한 작업 |
|
||||
|---|---|---|
|
||||
| **정적 자격 증명** (AWS 액세스 키, GCP 서비스 계정 JSON) | **배포 시점** — 값이 배포 이미지에 박힘 | 시크릿 로테이션 후 자동화 재배포 |
|
||||
| **Workload Identity** (OIDC federation, AWS 또는 GCP) | **모든 자동화 kickoff 시점** — 값을 클라우드에서 새로 가져옴 | 없음 — 로테이션 후 다음 kickoff에서 새 값이 보임 |
|
||||
|
||||
<Note>
|
||||
**로테이션 인식 시크릿이 필요한 경우**(로테이션 시 재배포 없이), Workload Identity 경로를 사용하세요: [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity). 트레이드오프는 초기 설정 노력이 더 많지만(CrewAI Platform을 클라우드에 OIDC 공급자로 등록), 장기적으로는 운영이 더 단순해진다는 점입니다.
|
||||
</Note>
|
||||
|
||||
배포 또는 실행이 시크릿 관련 오류로 실패하면 가장 일반적인 원인을 확인하세요:
|
||||
|
||||
| 증상 | 가능한 원인 |
|
||||
|---|---|
|
||||
| `no credential found` | 환경 변수가 공급자를 참조하지만 특정 자격 증명이 선택되지 않았고, 해당 공급자 유형에 대한 기본 자격 증명이 설정되어 있지 않습니다. 변수에서 자격 증명을 명시적으로 선택하거나, **Secret Provider Credentials** 페이지에서 자격 증명을 기본값으로 표시하세요. |
|
||||
| `secret not found` | **Secret Name**의 오타, 또는 자격 증명이 가리키는 공급자 계정/리전에 시크릿이 존재하지 않습니다. 둘 다 다시 확인하세요. |
|
||||
| 로테이션 후에도 자동화가 이전 값으로 실행됨 (정적 자격 증명 경로) | 이전 값이 배포 컨테이너 이미지에 박혀 있습니다. 로테이션된 값을 가져오려면 자동화를 재배포하세요. 이를 완전히 피하려면 자격 증명을 Workload Identity 경로로 전환하세요. |
|
||||
| 로테이션 후에도 자동화가 이전 값으로 실행됨 (Workload Identity 경로) | 환경 변수가 WI 기반 자격 증명을 참조하는지 확인하세요(정적 키가 아님). WI를 사용하면 로테이션 후 다음 kickoff에서 새 값이 보여야 합니다. 그렇지 않으면 시크릿이 실제로 클라우드에서 업데이트되었는지 확인하세요(예: `aws secretsmanager get-secret-value`). |
|
||||
| `JSON key not found` | `secret-name#json_key`를 사용할 때 기본 시크릿은 해당 키를 포함하는 유효한 JSON 객체여야 합니다. 공급자에서 직접 시크릿을 읽어 확인하세요. |
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview)
|
||||
- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: 로테이션 확인
|
||||
description: 클라우드 공급자에서 로테이션된 시크릿이 재배포 없이 실행 중인 배포에 전파됨을 증명하는 자체 포함된 예제 Crew입니다.
|
||||
sidebarTitle: 로테이션 확인
|
||||
icon: "arrows-rotate"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
이 가이드는 **클라우드 공급자에서 로테이션된 시크릿이 바로 다음 자동화 kickoff에서 적용됨**을 검증하는 방법을 보여줍니다 — 재배포 없음, 워커 재시작 없음. Workload Identity 기반 자격 증명([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity))을 구성한 경우에만 관련됩니다. 정적 자격 증명 배포는 로테이션 후 재배포가 필요합니다. 여기에서는 확인할 것이 없습니다.
|
||||
|
||||
아래 레시피는 하나의 도구, 하나의 에이전트, 하나의 작업으로 구성된 작은 자체 포함된 Crew를 사용합니다. Crew 프롬프트는 시크릿 값을 절대 참조하지 않으며 — 대신 도구가 `os.environ`에서 이를 읽고 본 것의 SHA-256 fingerprint를 보고합니다. 클라우드 공급자에서 시크릿을 로테이션하고, 다시 kickoff하면 fingerprint가 변경됩니다.
|
||||
|
||||
<Note>
|
||||
원시 값이 아닌 fingerprint를 사용하는 이유? 원시 시크릿을 LLM 출력과 트레이스 로그에 넣는 것은 유출 벡터입니다. fingerprint는 실제 값을 관찰 가능한 곳에 쓰지 않고도 "값이 변경되었다"는 것을 확인하기에 충분합니다.
|
||||
</Note>
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
이 검증을 실행하기 전에:
|
||||
|
||||
- WI 기반 Secret Provider Credential이 구성되어 있어야 합니다([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity)).
|
||||
- `Secret = true`, 키 `API_KEY`(또는 원하는 이름 — 아래 도구를 일치시키도록 조정)로 클라우드 공급자의 시크릿을 참조하는 배포의 환경 변수.
|
||||
- 클라우드 공급자에서 시크릿 값을 업데이트할 방법(CLI 액세스 또는 클라우드 콘솔).
|
||||
- HTTP를 통해 배포를 kickoff할 방법(curl, Postman, 또는 CrewAI Platform의 **Run** 탭).
|
||||
|
||||
## 1단계 — 검증 Crew 스캐폴딩
|
||||
|
||||
이 예제는 `crew.py`를 통해 Python 도구를 연결하므로 클래식 crew 프로젝트를 만듭니다:
|
||||
|
||||
```bash
|
||||
crewai create crew rotation_verifier --classic --skip_provider
|
||||
cd rotation_verifier
|
||||
```
|
||||
|
||||
## 2단계 — Credential Echo 도구 추가
|
||||
|
||||
`src/rotation_verifier/tools/custom_tool.py`를 시크릿 기반 환경 변수를 읽고 fingerprint를 반환하는 도구로 교체합니다:
|
||||
|
||||
```python src/rotation_verifier/tools/credential_echo_tool.py
|
||||
"""Tool that verifies a runtime-injected secret without leaking the value.
|
||||
|
||||
Reads the secret-backed env var (populated by the workload-identity
|
||||
secrets manager at kickoff time) and returns a stable fingerprint. Never
|
||||
echo raw credential values into LLM output or logs in production code —
|
||||
the fingerprint alone is sufficient to confirm rotation worked.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import os
|
||||
|
||||
from crewai.tools import BaseTool
|
||||
|
||||
|
||||
# Match the deployment environment variable's `key` field.
|
||||
ENV_VAR_NAME = "API_KEY"
|
||||
|
||||
|
||||
class CredentialEchoTool(BaseTool):
|
||||
name: str = "credential_echo"
|
||||
description: str = (
|
||||
"Read the API credential from the worker's environment and return a "
|
||||
"fingerprint summary. Use this exactly once when asked to verify the "
|
||||
"current credential. Takes no arguments."
|
||||
)
|
||||
|
||||
def _run(self) -> str:
|
||||
value = os.environ.get(ENV_VAR_NAME)
|
||||
if not value:
|
||||
return (
|
||||
f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-"
|
||||
"identity secret fetch did not run, or the deployment is "
|
||||
"missing the secret-backed env var."
|
||||
)
|
||||
fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12]
|
||||
return f"Authenticated. credential.fingerprint=sha256:{fingerprint}"
|
||||
```
|
||||
|
||||
## 3단계 — 기본 에이전트 및 작업 구성 교체
|
||||
|
||||
Crew에는 하나의 에이전트와 하나의 작업이 있습니다 — 둘 다 시크릿 값을 **절대** 언급하지 않는 설명을 가지므로, 작업 키가 로테이션 전반에 걸쳐 안정적으로 유지됩니다.
|
||||
|
||||
```yaml src/rotation_verifier/config/agents.yaml
|
||||
credential_checker:
|
||||
role: >
|
||||
Credential Verifier
|
||||
goal: >
|
||||
Confirm that the workload-identity-backed secret reached this worker
|
||||
process and report a fingerprint of the current value.
|
||||
backstory: >
|
||||
You are a no-nonsense reliability engineer responsible for verifying
|
||||
that secrets fetched at runtime via workload identity are present
|
||||
and fresh. You always use the credential_echo tool exactly once and
|
||||
report the result verbatim — you never make up values.
|
||||
```
|
||||
|
||||
```yaml src/rotation_verifier/config/tasks.yaml
|
||||
verify_credential_task:
|
||||
description: >
|
||||
Use the credential_echo tool to read the runtime-injected credential
|
||||
and produce a one-line confirmation. The current year is {current_year}
|
||||
(use it only in the timestamp; do not transform the credential output).
|
||||
expected_output: >
|
||||
A single line in the form:
|
||||
"[{current_year}] <credential_echo tool's exact output>"
|
||||
agent: credential_checker
|
||||
```
|
||||
|
||||
## 4단계 — Crew 클래스 연결
|
||||
|
||||
```python src/rotation_verifier/crew.py
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
|
||||
from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool
|
||||
|
||||
|
||||
@CrewBase
|
||||
class RotationVerifierCrew():
|
||||
"""Single-task crew that verifies a workload-identity-backed secret
|
||||
was successfully fetched at runtime.
|
||||
|
||||
Rotate the underlying secret in the cloud provider, kickoff again, and
|
||||
the credential fingerprint in the agent's report changes — without any
|
||||
re-deploy, worker restart, or input change. The crew prompt itself
|
||||
never references the secret value.
|
||||
"""
|
||||
|
||||
agents: list[BaseAgent]
|
||||
tasks: list[Task]
|
||||
|
||||
@agent
|
||||
def credential_checker(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config["credential_checker"],
|
||||
tools=[CredentialEchoTool()],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
@task
|
||||
def verify_credential_task(self) -> Task:
|
||||
return Task(config=self.tasks_config["verify_credential_task"])
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
## 5단계 — 배포 및 시크릿 환경 변수 구성
|
||||
|
||||
다른 Crew와 마찬가지로 이 Crew를 CrewAI Platform에 배포합니다. 그런 다음 배포의 **Environment Variables** 페이지에서:
|
||||
|
||||
- **Key:** `API_KEY` (도구의 `ENV_VAR_NAME`과 일치해야 함)
|
||||
- **Value Source:** [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에서 설정한 WI 기반 자격 증명
|
||||
- **Secret Name:** 클라우드 공급자의 Secret Manager에 있는 시크릿 이름
|
||||
|
||||
{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */}
|
||||
|
||||
## 6단계 — 첫 번째 Kickoff 실행
|
||||
|
||||
`<DEPLOYMENT_AUTH_TOKEN>`과 `<DEPLOYMENT_HOST>`를 배포의 **Run** 탭에 있는 값으로 교체합니다.
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
kickoff가 완료되면(몇 초), 에이전트의 출력을 확인합니다. 다음과 같이 표시됩니다:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:004421b993c9
|
||||
```
|
||||
|
||||
fingerprint를 기록합니다. 그 해시는 클라우드 공급자에 현재 있는 어떤 시크릿 값과 고유하게 연결되어 있습니다.
|
||||
|
||||
## 7단계 — 클라우드 공급자에서 시크릿 로테이션
|
||||
|
||||
<Tabs>
|
||||
<Tab title="AWS">
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id <SECRET_NAME> \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="GCP">
|
||||
새 버전을 추가합니다(Secret Manager는 항상 `latest`를 읽음):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Azure">
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name <SECRET_NAME> \
|
||||
--value "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 8단계 — 두 번째 Kickoff 실행 및 비교
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
이제 에이전트의 출력은 **다른 fingerprint**를 보여줍니다:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72
|
||||
```
|
||||
|
||||
이는 재배포, 워커 재시작 또는 기타 운영자 작업 없이 실행 중인 배포에서 로테이션이 적용되었음을 증명합니다.
|
||||
|
||||
## 이것이 검증하는 것 — 그리고 검증하지 않는 것
|
||||
|
||||
**검증하는 것:**
|
||||
- CrewAI Platform에서 WI OIDC 토큰 발급이 작동합니다.
|
||||
- 클라우드 측 신뢰(AWS의 IAM OIDC 공급자, GCP의 Workload Identity Pool, Azure의 Federated Identity Credential)가 토큰을 수락합니다.
|
||||
- 클라우드 측 ID(IAM Role / GCP 서비스 계정 / Entra App Registration)가 시크릿을 읽을 수 있는 액세스 권한을 가집니다.
|
||||
- 시크릿 값이 kickoff 시점에 워커 프로세스의 `os.environ`에 도달합니다.
|
||||
- 후속 로테이션이 다음 kickoff에 전파됩니다.
|
||||
|
||||
**검증하지 않는 것:**
|
||||
- 실제 프로덕션 Crew가 로테이션을 우아하게 처리하는지 — 예를 들어, 시작 시 환경 변수를 한 번만 읽는 장기 실행 작업은 작업이 끝날 때까지 이전 값을 계속 사용합니다. 적절히 계획하세요: 모듈 임포트 시가 아닌 사용 시점에 시크릿을 읽으세요.
|
||||
|
||||
## 왜 프롬프트에서 직접 시크릿을 참조하지 않나요?
|
||||
|
||||
더 간단해 보이는 데모는 시크릿 값을 작업 설명에 직접 넣고(예: "`{api_key}`에 대해 조사") 프롬프트를 검사하는 것입니다. **그렇게 하지 마세요.** 두 가지 이유:
|
||||
|
||||
1. **LLM 호출 트레이스와 공급자 측 로그에 시크릿이 유출됩니다.** 트레이스 액세스가 있는 모든 사람이 읽을 수 있습니다.
|
||||
2. **모든 kickoff에서 작업 설명이 변경됩니다.** CrewAI Platform은 설명의 MD5 해시로 작업을 식별합니다. 로테이션되는 값은 kickoff마다 해시가 변경되어 배포 시간 → 런타임 작업 매핑이 깨집니다. 증상: 작업 레코드가 무한정 `pending_run`으로 표시되거나 다중 작업 Crew의 일부 작업만 등록됩니다.
|
||||
|
||||
이 가이드의 도구 기반 패턴은 두 문제를 모두 회피합니다: 프롬프트는 정적이고, 도구가 런타임에 환경 변수를 읽으며, 값의 fingerprint만 LLM에 도달합니다.
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview)
|
||||
- 검증되면 검증 Crew를 삭제합니다. 실제 Crew는 동일한 패턴을 따라야 합니다: 시크릿은 도구 내부의 `os.environ`을 통해 액세스되며, 절대 프롬프트에 치환되지 않습니다.
|
||||
248
docs/edge/ko/enterprise/features/tools-and-integrations.mdx
Normal file
248
docs/edge/ko/enterprise/features/tools-and-integrations.mdx
Normal file
@@ -0,0 +1,248 @@
|
||||
---
|
||||
title: "도구 & 통합"
|
||||
description: "외부 앱을 연결하고 에이전트가 사용할 내부 도구를 관리하세요."
|
||||
icon: "wrench"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
도구 & 통합은 서드파티 애플리케이션을 연결하고 에이전트가 런타임에 사용할 내부 도구를 관리하는 중앙 허브입니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
## 살펴보기
|
||||
|
||||
<Tabs>
|
||||
<Tab title="통합" icon="plug">
|
||||
|
||||
## 에이전트 앱 (통합)
|
||||
|
||||
Gmail, Google Drive, HubSpot, Slack 등 OAuth 기반 서비스에 연결하여 에이전트 액션을 활성화하세요.
|
||||
|
||||
{" "}
|
||||
<Steps>
|
||||
<Step title="연결">
|
||||
원하는 앱에서 <b>Connect</b>를 클릭하고 OAuth를 완료합니다.
|
||||
</Step>
|
||||
<Step title="구성">
|
||||
필요에 따라 스코프, 트리거, 사용 가능한 액션을 조정합니다.
|
||||
</Step>
|
||||
<Step title="에이전트에서 사용">
|
||||
연결된 서비스는 에이전트 도구로 사용 가능합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
### 계정 연결하기
|
||||
|
||||
1. <Link href="https://app.crewai.com/crewai_plus/connectors">
|
||||
Integrations
|
||||
</Link>
|
||||
로 이동
|
||||
2. 원하는 서비스에서 <b>Connect</b> 클릭
|
||||
3. OAuth 플로우 완료 및 스코프 승인
|
||||
4. <Link href="https://app.crewai.com/crewai_plus/settings/integrations">
|
||||
통합 설정
|
||||
</Link>
|
||||
에서 Enterprise Token 복사
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### 통합 도구 설치
|
||||
|
||||
로컬에서 통합을 사용하려면 최신 `crewai-tools` 패키지를 설치하세요.
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 환경 변수 설정
|
||||
|
||||
{" "}
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
### 사용 예시
|
||||
|
||||
{" "}
|
||||
<Tip>
|
||||
새로운 간소화된 접근 방식을 사용하여 엔터프라이즈 앱을 통합하세요. Agent
|
||||
구성에서 앱과 해당 액션을 직접 지정하기만 하면 됩니다.
|
||||
</Tip>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Gmail 기능을 가진 에이전트 생성
|
||||
email_agent = Agent(
|
||||
role="이메일 매니저",
|
||||
goal="이메일 커뮤니케이션 관리",
|
||||
backstory="이메일 관리에 특화된 AI 어시스턴트",
|
||||
apps=['gmail', 'gmail/send_email'] # 정식 이름 'gmail' 사용
|
||||
)
|
||||
|
||||
email_task = Task(
|
||||
description="프로젝트 업데이트에 대한 후속 이메일 작성 및 전송",
|
||||
agent=email_agent,
|
||||
expected_output="이메일 전송 성공 확인"
|
||||
)
|
||||
|
||||
crew = Crew(agents=[email_agent], tasks=[email_task])
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 도구 필터링
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 특정 Gmail 액션만 사용하는 에이전트 생성
|
||||
gmail_agent = Agent(
|
||||
role="Gmail 매니저",
|
||||
goal="Gmail 커뮤니케이션 및 알림 관리",
|
||||
backstory="Gmail 커뮤니케이션 조율 AI 어시스턴트",
|
||||
apps=['gmail/fetch_emails'] # 정식 이름과 특정 액션 사용
|
||||
)
|
||||
|
||||
notification_task = Task(
|
||||
description="john@example.com에서 온 이메일 찾기",
|
||||
agent=gmail_agent,
|
||||
expected_output="john@example.com의 이메일을 찾았다는 확인"
|
||||
)
|
||||
|
||||
crew = Crew(agents=[gmail_agent], tasks=[notification_task])
|
||||
```
|
||||
|
||||
배포된 크루에서는 각 통합의 서비스 설정 페이지에서 사용 가능한 액션을 지정할 수 있습니다.
|
||||
|
||||
{" "}
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### 범위 지정 배포 (다중 사용자 조직)
|
||||
|
||||
각 통합을 특정 사용자로 범위 지정할 수 있습니다 (예: 특정 사용자의 Gmail 계정 사용).
|
||||
|
||||
{" "}
|
||||
<Tip>팀/사용자별 데이터 접근을 분리해야 할 때 유용합니다.</Tip>
|
||||
|
||||
`user_bearer_token`을 사용해 요청 사용자로 인증을 범위 지정합니다. 사용자가 로그인하지 않은 경우 연결된 통합을 사용하지 않으며, 그렇지 않으면 배포에 설정된 기본 토큰을 사용합니다.
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
{" "}
|
||||
<div id="catalog"></div>
|
||||
### 카탈로그
|
||||
|
||||
#### 커뮤니케이션 & 협업
|
||||
|
||||
- Gmail — 이메일 및 초안 관리
|
||||
- Slack — 워크스페이스 알림 및 경보
|
||||
- Microsoft — Office 365 및 Teams 통합
|
||||
|
||||
#### 프로젝트 관리
|
||||
|
||||
- Jira — 이슈 추적 및 프로젝트 관리
|
||||
- ClickUp — 작업 및 생산성 관리
|
||||
- Asana — 팀 작업 조율
|
||||
- Notion — 페이지 및 데이터베이스 관리
|
||||
- Linear — 버그/프로젝트 추적
|
||||
- GitHub — 리포지토리 및 이슈 관리
|
||||
|
||||
#### CRM
|
||||
|
||||
- Salesforce — 계정 및 기회 관리
|
||||
- HubSpot — 파이프라인/연락처 관리
|
||||
- Zendesk — 고객 지원 티켓 관리
|
||||
|
||||
#### 비즈니스 & 금융
|
||||
|
||||
- Stripe — 결제 처리 및 고객 관리
|
||||
- Shopify — 전자상거래 및 상품 관리
|
||||
|
||||
#### 생산성 & 스토리지
|
||||
|
||||
- Google Sheets — 스프레드시트 동기화
|
||||
- Google Calendar — 일정/이벤트 관리
|
||||
- Box — 파일 스토리지
|
||||
|
||||
…더 많은 통합이 추가될 예정입니다!
|
||||
|
||||
</Tab>
|
||||
<Tab title="내부 도구" icon="toolbox">
|
||||
|
||||
## 내부 도구
|
||||
|
||||
로컬에서 도구를 만들고, CrewAI AMP 도구 저장소에 게시한 후, 에이전트에서 사용하세요.
|
||||
|
||||
{" "}
|
||||
<Tip>
|
||||
아래 명령을 실행하기 전에 CrewAI AMP 계정에 로그인하세요: ```bash crewai login```
|
||||
</Tip>
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
{" "}
|
||||
<Steps>
|
||||
<Step title="생성">
|
||||
로컬에서 새 도구 생성 ```bash crewai tool create your-tool ```
|
||||
</Step>
|
||||
<Step title="게시">도구 저장소에 게시 ```bash crewai tool publish ```</Step>
|
||||
<Step title="설치">
|
||||
도구 저장소에서 설치 ```bash crewai tool install your-tool ```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
관리:
|
||||
|
||||
- 이름 및 설명
|
||||
- 가시성 (비공개 / 공개)
|
||||
- 필요한 환경 변수
|
||||
- 버전 이력 및 다운로드
|
||||
- 팀/역할 접근 권한
|
||||
|
||||
{" "}
|
||||
<Frame></Frame>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 관련 문서
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="도구 저장소"
|
||||
href="/ko/enterprise/guides/tool-repository"
|
||||
icon="toolbox"
|
||||
>
|
||||
크루 기능을 확장할 수 있도록 도구를 게시하고 설치하세요.
|
||||
</Card>
|
||||
<Card
|
||||
title="Webhook 자동화"
|
||||
href="/ko/enterprise/guides/webhook-automation"
|
||||
icon="bolt"
|
||||
>
|
||||
워크플로를 자동화하고 외부 플랫폼/서비스와 통합하세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
142
docs/edge/ko/enterprise/features/traces.mdx
Normal file
142
docs/edge/ko/enterprise/features/traces.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: 트레이스
|
||||
description: "Traces를 사용하여 내 크루 모니터링하기"
|
||||
icon: "timeline"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Trace는 crew 실행에 대한 포괄적인 가시성을 제공하여 성능 모니터링, 문제 디버깅, AI agent workflow 최적화에 도움을 줍니다.
|
||||
|
||||
## Traces란 무엇인가요?
|
||||
|
||||
CrewAI AOP의 Traces는 crew의 작동 과정을 처음 입력에서 최종 출력까지 모든 측면에서 포착하는 상세 실행 기록입니다. Traces에는 다음 내용이 기록됩니다:
|
||||
|
||||
- Agent의 생각 및 추론
|
||||
- 작업 실행 세부 정보
|
||||
- 도구 사용 및 출력
|
||||
- 토큰 소모 메트릭
|
||||
- 실행 시간
|
||||
- 비용 추정치
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
## 트레이스(Traces) 접근하기
|
||||
|
||||
<Steps>
|
||||
<Step title="트레이스 탭으로 이동">
|
||||
CrewAI AMP 대시보드에 들어가면, **트레이스**를 클릭하여 모든 실행 기록을 볼 수 있습니다.
|
||||
</Step>
|
||||
|
||||
<Step title="실행 선택하기">
|
||||
모든 crew 실행 목록이 날짜별로 정렬되어 표시됩니다. 상세 트레이스를 보려면 원하는 실행을 클릭하세요.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 트레이스 인터페이스 이해하기
|
||||
|
||||
트레이스 인터페이스는 여러 섹션으로 나뉘어 있으며, 각 섹션은 crew의 실행에 대한 다양한 인사이트를 제공합니다.
|
||||
|
||||
### 1. 실행 요약
|
||||
|
||||
상단 섹션에서는 실행에 대한 고수준 메트릭을 표시합니다:
|
||||
|
||||
- **총 토큰**: 모든 작업에서 소모된 토큰 수
|
||||
- **프롬프트 토큰**: LLM에 프롬프트로 사용된 토큰
|
||||
- **컴플리션 토큰**: LLM 응답에서 생성된 토큰
|
||||
- **요청 수**: 수행된 API 호출 수
|
||||
- **실행 시간**: crew 런의 전체 소요 시간
|
||||
- **예상 비용**: 토큰 사용량을 기반으로 한 대략적인 비용
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 2. Tasks & Agents
|
||||
|
||||
이 섹션에서는 crew 실행에 포함된 모든 task와 agent를 보여줍니다:
|
||||
|
||||
- task 이름 및 agent 할당
|
||||
- 각 task에 사용된 agent 및 LLM
|
||||
- 상태 (완료/실패)
|
||||
- task의 개별 실행 시간
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 3. 최종 결과
|
||||
|
||||
모든 작업이 완료된 후 crew가 생성한 최종 결과를 표시합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 4. 실행 타임라인
|
||||
|
||||
각 작업이 시작되고 종료된 시점을 시각적으로 표현하여 병목 현상이나 병렬 실행 패턴을 파악하는 데 도움이 됩니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 5. 상세 작업 보기
|
||||
|
||||
타임라인이나 작업 목록에서 특정 작업을 클릭하면 다음을 볼 수 있습니다:
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
- **작업 키**: 작업의 고유 식별자
|
||||
- **작업 ID**: 시스템 내의 기술적 식별자
|
||||
- **상태**: 현재 상태 (완료/진행 중/실패)
|
||||
- **에이전트**: 해당 작업을 수행한 에이전트
|
||||
- **LLM**: 이 작업에 사용된 언어 모델
|
||||
- **시작/종료 시간**: 작업이 시작되고 완료된 시간
|
||||
- **실행 시간**: 이 특정 작업의 소요 시간
|
||||
- **작업 설명**: 에이전트에게 지시된 작업 내용
|
||||
- **예상 출력**: 요청된 출력 형식
|
||||
- **입력**: 이전 작업에서 이 작업에 제공된 입력값
|
||||
- **출력**: 에이전트가 실제로 생성한 결과
|
||||
|
||||
## 디버깅을 위한 트레이스 사용
|
||||
|
||||
트레이스는 crew 문제 해결에 매우 유용합니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="실패 지점 식별">
|
||||
crew 실행이 예상한 결과를 내지 못할 때, 트레이스를 확인하여 어디에서 문제가 발생했는지 찾으세요. 다음을 확인하세요:
|
||||
|
||||
- 실패한 작업
|
||||
- 에이전트의 예상 밖 결정
|
||||
- 도구 사용 오류
|
||||
- 잘못 해석된 지침
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="성능 최적화">
|
||||
실행 메트릭을 사용하여 성능 병목 현상을 파악하세요:
|
||||
|
||||
- 예상보다 오래 걸린 작업
|
||||
- 과도한 토큰 사용
|
||||
- 중복된 도구 작업
|
||||
- 불필요한 API 호출
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="비용 효율성 향상">
|
||||
토큰 사용량 및 비용 추정치를 분석해 crew의 효율성을 최적화하세요:
|
||||
|
||||
- 더 간단한 작업에는 더 작은 모델을 사용 고려
|
||||
- 프롬프트를 더 간결하게 다듬기
|
||||
- 자주 액세스하는 정보 캐싱
|
||||
- 중복 작업을 최소화하도록 작업 구조화하기
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
트레이스 분석이나 기타 CrewAI 엔터프라이즈 기능에 대한 지원이 필요하시면 저희
|
||||
지원팀에 문의하세요.
|
||||
</Card>
|
||||
82
docs/edge/ko/enterprise/features/webhook-streaming.mdx
Normal file
82
docs/edge/ko/enterprise/features/webhook-streaming.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: 웹훅 스트리밍
|
||||
description: "웹훅 스트리밍을 사용하여 이벤트를 웹훅으로 스트리밍하기"
|
||||
icon: "webhook"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Enterprise Event Streaming을 사용하면 CrewAI AOP에 배포된 crew 및 flow에 대한 실시간 웹훅 업데이트(예: 모델 호출, 도구 사용, flow 단계)를 받을 수 있습니다.
|
||||
|
||||
## 사용법
|
||||
|
||||
Kickoff API를 사용할 때, 요청에 `webhooks` 객체를 포함시키세요. 예를 들면 아래와 같습니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": {"foo": "bar"},
|
||||
"webhooks": {
|
||||
"events": ["crew_kickoff_started", "llm_call_started"],
|
||||
"url": "https://your.endpoint/webhook",
|
||||
"realtime": false,
|
||||
"authentication": {
|
||||
"strategy": "bearer",
|
||||
"token": "my-secret-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`realtime`이 `true`로 설정되면, 각 이벤트가 개별적으로 그리고 즉시 전달되지만 crew/flow 성능에 영향을 미칠 수 있습니다.
|
||||
|
||||
## Webhook 형식
|
||||
|
||||
각 webhook은 이벤트 목록을 전송합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"id": "event-id",
|
||||
"execution_id": "crew-run-id",
|
||||
"timestamp": "2025-02-16T10:58:44.965Z",
|
||||
"type": "llm_call_started",
|
||||
"data": {
|
||||
"model": "gpt-4",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are an assistant."},
|
||||
{"role": "user", "content": "Summarize this article."}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`data` 객체의 구조는 이벤트 타입에 따라 다릅니다. 자세한 내용은 GitHub의 [이벤트 목록](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)을 참조하세요.
|
||||
|
||||
요청이 HTTP를 통해 전송되므로, 이벤트의 순서가 보장되지 않습니다. 순서가 필요하다면 `timestamp` 필드를 사용하세요.
|
||||
|
||||
## 지원되는 이벤트
|
||||
|
||||
CrewAI는 Enterprise Event Streaming에서 시스템 이벤트와 사용자 지정 이벤트 둘 다를 지원합니다. 이러한 이벤트는 crew 및 flow 실행 중에 구성한 웹훅 엔드포인트로 전송됩니다.
|
||||
|
||||
- `crew_kickoff_started`
|
||||
- `crew_step_started`
|
||||
- `crew_step_completed`
|
||||
- `crew_execution_completed`
|
||||
- `llm_call_started`
|
||||
- `llm_call_completed`
|
||||
- `tool_usage_started`
|
||||
- `tool_usage_completed`
|
||||
- `crew_test_failed`
|
||||
- *...그리고 기타 여러 가지*
|
||||
|
||||
이벤트 이름은 내부 이벤트 버스와 일치합니다. 전체 목록은 [GitHub 소스](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)에서 확인할 수 있습니다.
|
||||
|
||||
사용자 지정 이벤트도 직접 발생시킬 수 있으며, 시스템 이벤트와 함께 웹훅 스트림을 통해 전달됩니다.
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
웹훅 통합 또는 문제 해결에 대한 지원이 필요하다면 저희 지원팀에 문의해 주세요.
|
||||
</Card>
|
||||
272
docs/edge/ko/enterprise/guides/automation-triggers.mdx
Normal file
272
docs/edge/ko/enterprise/guides/automation-triggers.mdx
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
title: "트리거 개요"
|
||||
description: "CrewAI AMP 트리거의 동작 방식과 관리 방법, 그리고 통합별 플레이북을 한눈에 확인하세요"
|
||||
icon: "bolt"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AMP 트리거는 팀이 이미 사용하고 있는 도구의 실시간 이벤트와 자동화를 연결합니다. 폴링이나 수동 실행 대신, 트리거는 새로운 이메일, 캘린더 업데이트, CRM 상태 변화 등을 감지하여 지정한 크루 또는 플로우를 즉시 실행합니다.
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/TpQ45lAZh48"
|
||||
title="CrewAI 트리거 개요"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
### 통합 플레이북
|
||||
|
||||
아래 가이드는 각 통합을 활성화하고 테스트하는 방법을 자세히 설명합니다.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Gmail 트리거" icon="envelope">
|
||||
<a href="/ko/enterprise/guides/gmail-trigger">새로운 이메일이나 스레드 업데이트에 맞춰 크루를 실행하세요.</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Google Calendar 트리거" icon="calendar-days">
|
||||
<a href="/ko/enterprise/guides/google-calendar-trigger">
|
||||
캘린더 이벤트 생성, 수정, 취소에 대응하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Google Drive 트리거" icon="folder-open">
|
||||
<a href="/ko/enterprise/guides/google-drive-trigger">
|
||||
Drive 파일 업로드, 수정, 삭제를 감시하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Outlook 트리거" icon="envelope-open">
|
||||
<a href="/ko/enterprise/guides/outlook-trigger">
|
||||
Outlook의 새로운 메일이나 삭제된 이벤트에 대응하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="OneDrive 트리거" icon="cloud">
|
||||
<a href="/ko/enterprise/guides/onedrive-trigger">
|
||||
OneDrive 파일 활동 및 공유 변경 사항을 감사하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Microsoft Teams 트리거" icon="comments">
|
||||
<a href="/ko/enterprise/guides/microsoft-teams-trigger">
|
||||
새로운 Teams 채팅이 생성될 때 워크플로우를 시작하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="HubSpot 트리거" icon="hubspot">
|
||||
<a href="/ko/enterprise/guides/hubspot-trigger">
|
||||
HubSpot 워크플로우와 라이프사이클 이벤트에서 자동화를 실행하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Salesforce 트리거" icon="salesforce">
|
||||
<a href="/ko/enterprise/guides/salesforce-trigger">
|
||||
Salesforce 프로세스를 CrewAI 크루와 연결해 CRM 자동화를 구현하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
{" "}
|
||||
<Card title="Slack 트리거" icon="slack">
|
||||
<a href="/ko/enterprise/guides/slack-trigger">
|
||||
Slack 슬래시 명령으로 크루를 바로 실행하세요.
|
||||
</a>
|
||||
</Card>
|
||||
|
||||
<Card title="Zapier 트리거" icon="bolt">
|
||||
<a href="/ko/enterprise/guides/zapier-trigger">CrewAI를 수천 개의 Zapier 지원 앱과 연동하세요.</a>
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 트리거 기능
|
||||
|
||||
- **실시간 대응** – 조건이 충족되면 자동으로 워크플로우 실행
|
||||
- **외부 시스템 연동** – Gmail, Outlook, OneDrive, JIRA, Slack, Stripe 등과 연결
|
||||
- **자동화 확장성** – 수동 개입 없이 대량 이벤트 처리
|
||||
- **컨텍스트 유지** – 트리거 데이터를 크루와 플로우에서 바로 활용
|
||||
|
||||
## 트리거 관리
|
||||
|
||||
### 사용 가능한 트리거 보기
|
||||
|
||||
1. CrewAI 대시보드에서 자동화를 선택합니다.
|
||||
2. **Triggers** 탭을 클릭하여 사용 가능한 통합을 확인합니다.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-available-triggers.png"
|
||||
alt="사용 가능한 트리거 목록"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
### 트리거 활성화/비활성화
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/trigger-selected.png" alt="트리거 토글" />
|
||||
</Frame>
|
||||
|
||||
- **파랑 (활성)** – 이벤트 발생 시 자동 실행
|
||||
- **회색 (비활성)** – 이벤트 무시
|
||||
|
||||
토글 버튼을 클릭하면 즉시 적용됩니다.
|
||||
|
||||
### 트리거 실행 모니터링
|
||||
|
||||
트리거 실행 내역과 상태를 대시보드에서 확인하세요.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/list-executions.png" alt="트리거 실행 내역" />
|
||||
</Frame>
|
||||
|
||||
## 트리거 기반 자동화 구성
|
||||
|
||||
### 설정 체크리스트
|
||||
|
||||
- **Tools & Integrations**에서 해당 서비스를 연결하고 OAuth 또는 API 설정을 완료했나요?
|
||||
- 자동화에서 트리거 토글을 활성화했나요?
|
||||
- 필요한 환경 변수(토큰, 테넌트 ID, 시크릿 등)를 설정했나요?
|
||||
- 첫 번째 작업에서 트리거 payload를 파싱하도록 구성했나요?
|
||||
- `allow_crewai_trigger_context` 옵션으로 컨텍스트 자동 주입 여부를 결정했나요?
|
||||
- 웹훅 로그, CrewAI 실행 기록, 외부 알림 등 모니터링을 준비했나요?
|
||||
|
||||
### CLI로 로컬에서 트리거 테스트
|
||||
|
||||
CrewAI CLI는 프로덕션에 배포하기 전에 트리거 기반 자동화를 개발하고 테스트할 수 있는 강력한 명령을 제공합니다.
|
||||
|
||||
#### 사용 가능한 트리거 목록 보기
|
||||
|
||||
연결된 통합에 사용 가능한 모든 트리거를 확인하세요:
|
||||
|
||||
```bash
|
||||
crewai triggers list
|
||||
```
|
||||
|
||||
이 명령은 연결된 통합을 기반으로 사용 가능한 모든 트리거를 표시합니다:
|
||||
|
||||
- 통합 이름 및 연결 상태
|
||||
- 사용 가능한 트리거 유형
|
||||
- 트리거 이름 및 설명
|
||||
|
||||
#### 트리거 실행 시뮬레이션
|
||||
|
||||
배포 전에 실제 트리거 payload로 크루를 테스트하세요:
|
||||
|
||||
```bash
|
||||
crewai triggers run <트리거_이름>
|
||||
```
|
||||
|
||||
예시:
|
||||
|
||||
```bash
|
||||
crewai triggers run microsoft_onedrive/file_changed
|
||||
```
|
||||
|
||||
이 명령은:
|
||||
|
||||
- 로컬에서 크루를 실행합니다
|
||||
- 완전하고 실제적인 트리거 payload를 전달합니다
|
||||
- 프로덕션에서 크루가 호출되는 방식을 정확히 시뮬레이션합니다
|
||||
|
||||
<Warning>
|
||||
**중요한 개발 노트:**
|
||||
- 개발 중 트리거 실행을 시뮬레이션하려면 `crewai triggers run <trigger>`를 사용하세요
|
||||
- `crewai run`을 사용하면 트리거 호출을 시뮬레이션하지 않으며 트리거 payload를 전달하지 않습니다
|
||||
- 배포 후에는 실제 트리거 payload로 크루가 실행됩니다
|
||||
- 크루가 트리거 payload에 없는 매개변수를 기대하면 실행이 실패할 수 있습니다
|
||||
</Warning>
|
||||
|
||||
### 트리거와 Crew 연동
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class MyAutomatedCrew:
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher'],
|
||||
)
|
||||
|
||||
@task
|
||||
def parse_trigger_payload(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['parse_trigger_payload'],
|
||||
agent=self.researcher(),
|
||||
)
|
||||
|
||||
@task
|
||||
def analyze_trigger_content(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['analyze_trigger_data'],
|
||||
agent=self.researcher(),
|
||||
)
|
||||
```
|
||||
|
||||
### 플로우와의 통합
|
||||
|
||||
#### Payload 접근
|
||||
|
||||
```python
|
||||
from crewai.flow import Flow, start, listen
|
||||
|
||||
class MyAutomatedFlow(Flow):
|
||||
@start()
|
||||
def handle_trigger(self, crewai_trigger_payload: dict = None):
|
||||
if crewai_trigger_payload:
|
||||
trigger_id = crewai_trigger_payload.get('id')
|
||||
event_data = crewai_trigger_payload.get('payload', {})
|
||||
self.state.trigger_id = trigger_id
|
||||
self.state.trigger_type = event_data
|
||||
return event_data
|
||||
return None
|
||||
|
||||
@listen(handle_trigger)
|
||||
def process_data(self, trigger_data):
|
||||
# ... 트리거 처리
|
||||
```
|
||||
|
||||
#### 플로우에서 Crew 실행
|
||||
|
||||
```python
|
||||
@start()
|
||||
def delegate_to_crew(self, crewai_trigger_payload: dict = None):
|
||||
crew = MySpecializedCrew()
|
||||
result = crew.crew().kickoff(
|
||||
inputs={
|
||||
'custom_parameter': "custom_value",
|
||||
'crewai_trigger_payload': crewai_trigger_payload
|
||||
},
|
||||
)
|
||||
return result
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
**트리거가 실행되지 않나요?**
|
||||
|
||||
- 배포의 Triggers 탭에서 트리거가 활성화되어 있는지 확인하세요
|
||||
- Tools & Integrations에서 통합 연결 상태를 확인하세요
|
||||
- 필요한 모든 환경 변수가 올바르게 구성되어 있는지 확인하세요
|
||||
|
||||
**실행 중 오류가 발생하나요?**
|
||||
|
||||
- 실행 로그에서 오류 세부 정보를 확인하세요
|
||||
- `crewai triggers run <트리거_이름>`을 사용하여 로컬에서 테스트하고 정확한 payload 구조를 확인하세요
|
||||
- 크루가 `crewai_trigger_payload` 매개변수를 처리할 수 있는지 확인하세요
|
||||
- 크루가 트리거 payload에 포함되지 않은 매개변수를 기대하지 않는지 확인하세요
|
||||
|
||||
**개발 문제:**
|
||||
|
||||
- 배포하기 전에 항상 `crewai triggers run <trigger>`로 테스트하여 전체 payload를 확인하세요
|
||||
- `crewai run`은 트리거 호출을 시뮬레이션하지 않으므로 `crewai triggers run`을 대신 사용하세요
|
||||
- `crewai triggers list`를 사용하여 연결된 통합에 사용 가능한 트리거를 확인하세요
|
||||
- 배포 후 크루는 실제 트리거 payload를 받으므로 먼저 로컬에서 철저히 테스트하세요
|
||||
|
||||
트리거를 활용하면 CrewAI 자동화를 이벤트 기반 시스템으로 전환하여 기존 비즈니스 프로세스와 도구에 자연스럽게 녹여낼 수 있습니다.
|
||||
54
docs/edge/ko/enterprise/guides/azure-openai-setup.mdx
Normal file
54
docs/edge/ko/enterprise/guides/azure-openai-setup.mdx
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Azure OpenAI 설정"
|
||||
description: "엔터프라이즈 LLM 연결을 위해 Crew Studio와 함께 Azure OpenAI를 구성합니다"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이 가이드는 Azure OpenAI와 Crew Studio를 연동하여 원활한 엔터프라이즈 AI 운영을 수행하는 방법을 안내합니다.
|
||||
|
||||
## 설정 프로세스
|
||||
|
||||
<Steps>
|
||||
<Step title="Azure OpenAI Studio 접속">
|
||||
1. Azure에서 `Azure AI Services > 배포 선택 > Azure OpenAI Studio 열기`로 이동합니다.
|
||||
2. 왼쪽 메뉴에서 `Deployments`를 클릭합니다. 배포가 없다면 원하는 모델로 새 배포를 생성하세요.
|
||||
3. 생성이 완료되면 해당 배포를 선택하고, 페이지 오른쪽에서 `Target URI`와 `Key`를 찾습니다. 이 정보가 필요하니 페이지를 열어둔 상태로 두세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/azure-openai-studio.png" alt="Azure OpenAI Studio" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="CrewAI AMP 연결 구성">
|
||||
4. 다른 탭에서 `CrewAI AMP > LLM Connections`를 엽니다. LLM Connection에 이름을 지정하고, 공급자로 Azure를 선택한 다음, Azure에서 선택한 것과 동일한 모델을 선택하세요.
|
||||
5. 같은 페이지에서 3단계에서 가져온 환경 변수를 추가하세요:
|
||||
- 하나는 `AZURE_DEPLOYMENT_TARGET_URL` (Target URI 사용)로 명명합니다. URL은 다음과 같이 표시됩니다: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview
|
||||
- 다른 하나는 `AZURE_API_KEY` (Key 사용)로 명명합니다.
|
||||
6. `Add Connection`을 클릭하여 LLM Connection을 저장합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="기본 구성 설정">
|
||||
7. `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`에서 새 LLM Connection과 모델을 기본값으로 설정합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="네트워크 액세스 구성">
|
||||
8. 네트워크 액세스 설정을 확인하세요:
|
||||
- Azure에서 `Azure OpenAI > 배포 선택`으로 이동합니다.
|
||||
- `Resource Management > Networking`으로 이동합니다.
|
||||
- `Allow access from all networks`가 활성화되어 있는지 확인하세요. 이 설정이 제한되어 있으면 CrewAI가 Azure OpenAI 엔드포인트에 접근하지 못할 수 있습니다.
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 확인
|
||||
|
||||
모두 준비되었습니다! 이제 Crew Studio는 Azure OpenAI 연결을 사용합니다. 모든 기능이 제대로 작동하는지 확인하려면 간단한 crew 또는 task를 만들어 연결을 테스트해 보세요.
|
||||
|
||||
## 문제 해결
|
||||
|
||||
문제가 발생한 경우:
|
||||
|
||||
- Target URI 형식이 예상 패턴과 일치하는지 확인하세요
|
||||
- API 키가 올바르고 적절한 권한을 가지고 있는지 확인하세요
|
||||
- 네트워크 액세스가 CrewAI 연결을 허용하도록 구성되어 있는지 확인하세요
|
||||
- 배포 모델이 CrewAI에서 구성한 것과 일치하는지 확인하세요
|
||||
44
docs/edge/ko/enterprise/guides/build-crew.mdx
Normal file
44
docs/edge/ko/enterprise/guides/build-crew.mdx
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "Crew 빌드"
|
||||
description: "Crew는 함께 작업을 완수하기 위해 협력하는 에이전트 그룹입니다."
|
||||
icon: "people-arrows"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
[CrewAI AMP](https://app.crewai.com)는 프로덕션 환경에서 AI 에이전트를 **생성**, **배포** 및 **관리**하는 과정을 간소화합니다.
|
||||
|
||||
## 시작하기
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/-kSOTtYzgEw"
|
||||
title="Building crews with the CrewAI CLI"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
### 설치 및 설정
|
||||
|
||||
<Card title="표준 설치 따라하기" icon="wrench" href="/ko/installation">
|
||||
CrewAI CLI를 설정하고 첫 번째 프로젝트를 생성하기 위해 표준 설치 가이드를
|
||||
따라주세요.
|
||||
</Card>
|
||||
|
||||
### 크루 구성하기
|
||||
|
||||
<Card title="빠른 시작 튜토리얼" icon="rocket" href="/ko/quickstart">
|
||||
YAML 구성을 사용하여 첫 번째 에이전트 크루를 만드는 방법은 빠른 시작 가이드를
|
||||
따라주세요.
|
||||
</Card>
|
||||
|
||||
## 지원 및 리소스
|
||||
|
||||
Enterprise 전용 지원 또는 문의가 필요하신 경우, [support@crewai.com](mailto:support@crewai.com)으로 저희 전담 지원팀에 연락해 주시기 바랍니다.
|
||||
|
||||
<Card title="데모 예약" icon="calendar" href="mailto:support@crewai.com">
|
||||
Enterprise 기능과 해당 기능이 귀사의 조직에 어떻게 도움이 될 수 있는지
|
||||
알아보시려면 저희 팀과 상담 일정을 예약하세요.
|
||||
</Card>
|
||||
63
docs/edge/ko/enterprise/guides/capture_telemetry_logs.mdx
Normal file
63
docs/edge/ko/enterprise/guides/capture_telemetry_logs.mdx
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: "OpenTelemetry 내보내기"
|
||||
description: "CrewAI AMP 배포에서 자체 OpenTelemetry 수집기로 트레이스와 로그를 내보내기"
|
||||
icon: "magnifying-glass-chart"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자체 수집기로 직접 내보낼 수 있습니다. 이를 통해 기존 관측 가능성 스택을 사용하여 에이전트 성능을 모니터링하고, LLM 호출을 추적하고, 문제를 디버깅할 수 있습니다.
|
||||
|
||||
텔레메트리 데이터는 [OpenTelemetry GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)과 추가적인 CrewAI 전용 속성을 따릅니다.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="CrewAI AMP 계정" icon="users">
|
||||
조직에 활성 CrewAI AMP 계정이 있어야 합니다.
|
||||
</Card>
|
||||
<Card title="OpenTelemetry 수집기" icon="server">
|
||||
OpenTelemetry 호환 수집기 엔드포인트가 필요합니다 (예: 자체 OTel Collector, Datadog, Grafana 또는 OTLP 호환 백엔드).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 수집기 설정
|
||||
|
||||
1. CrewAI AMP에서 **Settings** > **OpenTelemetry Collectors**로 이동합니다.
|
||||
2. **Add Collector**를 클릭합니다.
|
||||
3. 통합을 선택합니다:
|
||||
- **OpenTelemetry Traces** 및 **OpenTelemetry Logs** — OTLP 호환 수집기 또는 백엔드로 내보냅니다.
|
||||
- **Datadog** — 별도의 수집기나 Datadog Agent 없이 트레이스를 Datadog의 OTLP 인테이크로 직접 전송합니다.
|
||||
4. 연결을 구성합니다. 필드는 선택한 통합에 따라 달라집니다:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenTelemetry Traces / Logs">
|
||||
**OpenTelemetry Traces**와 **OpenTelemetry Logs**는 동일한 필드를 공유하는 별개의 통합입니다 — 내보내려는 신호에 맞는 것을 선택하세요.
|
||||
|
||||
- **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`).
|
||||
- **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름.
|
||||
- **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다.
|
||||
- **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
<Tab title="Datadog">
|
||||
- **Datadog Site Domain** — Datadog 사이트의 OTLP 호스트만 입력합니다 (프로토콜이나 경로 제외). CrewAI가 전체 HTTPS OTLP 엔드포인트를 자동으로 구성합니다. [Datadog 사이트](https://docs.datadoghq.com/getting_started/site/)에 맞는 호스트를 사용하세요:
|
||||
- `otlp.datadoghq.com` (US1)
|
||||
- `otlp.us3.datadoghq.com` (US3)
|
||||
- `otlp.us5.datadoghq.com` (US5)
|
||||
- `otlp.datadoghq.eu` (EU1)
|
||||
- `otlp.ap1.datadoghq.com` (AP1)
|
||||
- **API Key** — Datadog API 키입니다. [키 생성 방법](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)을 참고하세요.
|
||||
|
||||
Datadog 통합은 **트레이스**를 내보냅니다.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
5. *(선택 사항)* **Test Connection**을 클릭하여 제공한 자격 증명으로 CrewAI가 엔드포인트에 연결할 수 있는지 확인합니다.
|
||||
6. **Save**를 클릭합니다.
|
||||
|
||||
<Tip>
|
||||
여러 수집기를 추가할 수 있습니다 — 예를 들어, 트레이스용 하나와 로그용 하나를 추가하거나, 다른 목적을 위해 다른 백엔드로 전송할 수 있습니다.
|
||||
</Tip>
|
||||
136
docs/edge/ko/enterprise/guides/custom-mcp-server.mdx
Normal file
136
docs/edge/ko/enterprise/guides/custom-mcp-server.mdx
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
title: "커스텀 MCP 서버"
|
||||
description: "공개 액세스, API 키 인증 또는 OAuth 2.0을 사용하여 자체 MCP 서버를 CrewAI AMP에 연결하세요"
|
||||
icon: "plug"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AMP는 [Model Context Protocol](https://modelcontextprotocol.io/)을 구현하는 모든 MCP 서버에 연결할 수 있습니다. 인증이 필요 없는 공개 서버, API 키 또는 Bearer 토큰으로 보호되는 서버, OAuth 2.0을 사용하는 서버를 연결할 수 있습니다.
|
||||
|
||||
## 사전 요구사항
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="CrewAI AMP 계정" icon="user">
|
||||
활성화된 [CrewAI AMP](https://app.crewai.com) 계정이 필요합니다.
|
||||
</Card>
|
||||
<Card title="MCP 서버 URL" icon="link">
|
||||
연결하려는 MCP 서버의 URL입니다. 서버는 인터넷에서 접근 가능해야 하며 Streamable HTTP 전송을 지원해야 합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 커스텀 MCP 서버 추가하기
|
||||
|
||||
<Steps>
|
||||
<Step title="Tools & Integrations 열기">
|
||||
CrewAI AMP 왼쪽 사이드바에서 **Tools & Integrations**로 이동한 후 **Connections** 탭을 선택합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="커스텀 MCP 서버 추가 시작">
|
||||
**Add Custom MCP Server** 버튼을 클릭합니다. 구성 양식이 포함된 대화 상자가 나타납니다.
|
||||
</Step>
|
||||
|
||||
<Step title="기본 정보 입력">
|
||||
- **Name** (필수): MCP 서버의 설명적 이름 (예: "내부 도구 서버").
|
||||
- **Description**: 이 MCP 서버가 제공하는 기능에 대한 선택적 요약.
|
||||
- **Server URL** (필수): MCP 서버 엔드포인트의 전체 URL (예: `https://my-server.example.com/mcp`).
|
||||
</Step>
|
||||
|
||||
<Step title="인증 방법 선택">
|
||||
MCP 서버의 보안 방식에 따라 세 가지 인증 방법 중 하나를 선택합니다. 각 방법에 대한 자세한 내용은 아래 섹션을 참조하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="커스텀 헤더 추가 (선택사항)">
|
||||
MCP 서버가 모든 요청에 추가 헤더를 요구하는 경우 (예: 테넌트 식별자 또는 라우팅 헤더), **+ Add Header**를 클릭하고 헤더 이름과 값을 입력합니다. 여러 커스텀 헤더를 추가할 수 있습니다.
|
||||
</Step>
|
||||
|
||||
<Step title="연결 생성">
|
||||
**Create MCP Server**를 클릭하여 연결을 저장합니다. 커스텀 MCP 서버가 Connections 목록에 나타나고 해당 도구를 crew에서 사용할 수 있게 됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 인증 방법
|
||||
|
||||
### 인증 없음
|
||||
|
||||
MCP 서버가 공개적으로 접근 가능하고 자격 증명이 필요 없을 때 이 옵션을 선택합니다. 오픈 소스 서버나 VPN 뒤에서 실행되는 내부 서버에 일반적입니다.
|
||||
|
||||
### 인증 토큰
|
||||
|
||||
MCP 서버가 API 키 또는 Bearer 토큰으로 보호되는 경우 이 방법을 사용합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/custom-mcp-auth-token.png" alt="인증 토큰을 사용하는 커스텀 MCP 서버" />
|
||||
</Frame>
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
|------|------|------|
|
||||
| **Header Name** | 예 | 토큰을 전달하는 HTTP 헤더 이름 (예: `X-API-Key`, `Authorization`). |
|
||||
| **Value** | 예 | API 키 또는 Bearer 토큰. |
|
||||
| **Add to** | 아니오 | 자격 증명을 첨부할 위치 — **Header** (기본값) 또는 **Query parameter**. |
|
||||
|
||||
<Tip>
|
||||
서버가 `Authorization` 헤더에 `Bearer` 토큰을 예상하는 경우, Header Name을 `Authorization`으로, Value를 `Bearer <토큰>`으로 설정하세요.
|
||||
</Tip>
|
||||
|
||||
### OAuth 2.0
|
||||
|
||||
OAuth 2.0 인증이 필요한 MCP 서버에 이 방법을 사용합니다. CrewAI가 토큰 갱신을 포함한 전체 OAuth 흐름을 처리합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/custom-mcp-oauth.png" alt="OAuth 2.0을 사용하는 커스텀 MCP 서버" />
|
||||
</Frame>
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
|------|------|------|
|
||||
| **Redirect URI** | — | 자동으로 채워지며 읽기 전용입니다. 이 URI를 복사하여 OAuth 제공자에 승인된 리디렉션 URI로 등록하세요. |
|
||||
| **Authorization Endpoint** | 예 | 사용자가 접근을 승인하기 위해 이동하는 URL (예: `https://auth.example.com/oauth/authorize`). |
|
||||
| **Token Endpoint** | 예 | 인증 코드를 액세스 토큰으로 교환하는 데 사용되는 URL (예: `https://auth.example.com/oauth/token`). |
|
||||
| **Client ID** | 예 | OAuth 제공자가 발급한 클라이언트 ID. |
|
||||
| **Client Secret** | 아니오 | OAuth 클라이언트 시크릿. PKCE를 사용하는 공개 클라이언트에는 필요하지 않습니다. |
|
||||
| **Scopes** | 아니오 | 요청할 스코프의 공백으로 구분된 목록 (예: `read write`). |
|
||||
| **Token Auth Method** | 아니오 | 토큰 교환 시 클라이언트 자격 증명을 보내는 방법 — **Standard (POST body)** 또는 **Basic Auth (header)**. 기본값은 Standard입니다. |
|
||||
| **PKCE Supported** | 아니오 | OAuth 제공자가 Proof Key for Code Exchange를 지원하는 경우 활성화합니다. 보안 강화를 위해 권장됩니다. |
|
||||
|
||||
<Info>
|
||||
**Discover OAuth Config**: OAuth 제공자가 OpenID Connect Discovery를 지원하는 경우, **Discover OAuth Config** 링크를 클릭하여 제공자의 `/.well-known/openid-configuration` URL에서 인증 및 토큰 엔드포인트를 자동으로 채울 수 있습니다.
|
||||
</Info>
|
||||
|
||||
#### OAuth 2.0 단계별 설정
|
||||
|
||||
<Steps>
|
||||
<Step title="리디렉션 URI 등록">
|
||||
양식에 표시된 **Redirect URI**를 복사하여 OAuth 제공자의 애플리케이션 설정에서 승인된 리디렉션 URI로 추가합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="엔드포인트 및 자격 증명 입력">
|
||||
**Authorization Endpoint**, **Token Endpoint**, **Client ID**를 입력하고, 선택적으로 **Client Secret**과 **Scopes**를 입력합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="토큰 교환 방법 구성">
|
||||
적절한 **Token Auth Method**를 선택합니다. 대부분의 제공자는 기본값인 **Standard (POST body)**를 사용합니다. 일부 오래된 제공자는 **Basic Auth (header)**를 요구합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="PKCE 활성화 (권장)">
|
||||
제공자가 지원하는 경우 **PKCE Supported**를 체크합니다. PKCE는 인증 코드 흐름에 추가 보안 계층을 제공하며 모든 새 통합에 권장됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="생성 및 인증">
|
||||
**Create MCP Server**를 클릭합니다. OAuth 제공자로 리디렉션되어 접근을 인증합니다. 인증 완료 후 CrewAI가 토큰을 저장하고 필요에 따라 자동으로 갱신합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 커스텀 MCP 서버 사용하기
|
||||
|
||||
연결이 완료되면 커스텀 MCP 서버의 도구가 **Tools & Integrations** 페이지에서 기본 제공 연결과 함께 표시됩니다. 다음을 수행할 수 있습니다:
|
||||
|
||||
- 다른 CrewAI 도구와 마찬가지로 crew의 **에이전트에 도구를 할당**합니다.
|
||||
- **가시성을 관리**하여 어떤 팀원이 서버를 사용할 수 있는지 제어합니다.
|
||||
- Connections 목록에서 언제든지 연결을 **편집하거나 제거**합니다.
|
||||
|
||||
<Warning>
|
||||
MCP 서버에 접근할 수 없거나 자격 증명이 만료되면 해당 서버를 사용하는 도구 호출이 실패합니다. 서버 URL이 안정적이고 자격 증명이 최신 상태인지 확인하세요.
|
||||
</Warning>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
커스텀 MCP 서버 구성 또는 문제 해결에 대한 도움이 필요하면 지원팀에 문의하세요.
|
||||
</Card>
|
||||
449
docs/edge/ko/enterprise/guides/deploy-to-amp.mdx
Normal file
449
docs/edge/ko/enterprise/guides/deploy-to-amp.mdx
Normal file
@@ -0,0 +1,449 @@
|
||||
---
|
||||
title: "AMP에 배포하기"
|
||||
description: "Crew 또는 Flow를 CrewAI AMP에 배포하기"
|
||||
icon: "rocket"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
로컬에서 또는 Crew Studio를 통해 Crew나 Flow를 생성한 후, 다음 단계는 이를 CrewAI AMP
|
||||
플랫폼에 배포하는 것입니다. 본 가이드에서는 다양한 배포 방법을 다루며,
|
||||
여러분의 워크플로우에 가장 적합한 방식을 선택할 수 있도록 안내합니다.
|
||||
</Note>
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="배포 준비가 완료된 프로젝트" icon="check-circle">
|
||||
로컬에서 성공적으로 실행되는 Crew 또는 Flow가 있어야 합니다.
|
||||
[배포 준비 가이드](/ko/enterprise/guides/prepare-for-deployment)를 따라 프로젝트 구조를 확인하세요.
|
||||
</Card>
|
||||
<Card title="GitHub 저장소" icon="github">
|
||||
코드가 GitHub 저장소에 있어야 합니다(GitHub 연동 방식의 경우).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
**Crews vs Flows**: 두 프로젝트 유형 모두 CrewAI AMP에서 "자동화"로 배포할 수 있습니다.
|
||||
배포 과정은 동일하지만, 프로젝트 구조가 다릅니다.
|
||||
자세한 내용은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.
|
||||
</Info>
|
||||
|
||||
## 옵션 1: CrewAI CLI를 사용한 배포
|
||||
|
||||
CLI는 로컬에서 개발된 Crew 또는 Flow를 AMP 플랫폼에 가장 빠르게 배포할 수 있는 방법을 제공합니다.
|
||||
CLI는 `pyproject.toml`에서 프로젝트 유형을 자동으로 감지하고 그에 맞게 빌드합니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="CrewAI CLI 설치">
|
||||
아직 설치하지 않았다면 CrewAI CLI를 설치하세요:
|
||||
|
||||
```bash
|
||||
pip install crewai[tools]
|
||||
```
|
||||
|
||||
<Tip>
|
||||
CLI는 기본 CrewAI 패키지에 포함되어 있지만, `[tools]` 추가 옵션을 사용하면 모든 배포 종속성을 함께 설치할 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Enterprise 플랫폼에 인증">
|
||||
먼저, CrewAI AMP 플랫폼에 CLI를 인증해야 합니다:
|
||||
|
||||
```bash
|
||||
# 이미 CrewAI AMP 계정이 있거나 새로 생성하고 싶을 때:
|
||||
crewai login
|
||||
```
|
||||
|
||||
위 명령어를 실행하면 CLI가 다음을 진행합니다:
|
||||
1. URL과 고유 기기 코드를 표시합니다
|
||||
2. 브라우저를 열어 인증 페이지로 이동합니다
|
||||
3. 기기 확인을 요청합니다
|
||||
4. 인증 과정을 완료합니다
|
||||
|
||||
인증이 성공적으로 완료되면 터미널에 확인 메시지가 표시됩니다!
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="배포 생성">
|
||||
|
||||
프로젝트 디렉터리에서 다음 명령어를 실행하세요:
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
|
||||
이 명령어는 다음을 수행합니다:
|
||||
1. GitHub 저장소 정보를 감지합니다
|
||||
2. 로컬 `.env` 파일의 환경 변수를 식별합니다
|
||||
3. 이러한 변수를 Enterprise 플랫폼으로 안전하게 전송합니다
|
||||
4. 고유 식별자가 부여된 새 배포를 만듭니다
|
||||
|
||||
성공적으로 생성되면 다음과 같은 메시지가 표시됩니다:
|
||||
```shell
|
||||
Deployment created successfully!
|
||||
Name: your_project_name
|
||||
Deployment ID: 01234567-89ab-cdef-0123-456789abcdef
|
||||
Current Status: Deploy Enqueued
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="배포 진행 상황 모니터링">
|
||||
|
||||
다음 명령어로 배포 상태를 추적할 수 있습니다:
|
||||
|
||||
```bash
|
||||
crewai deploy status
|
||||
```
|
||||
|
||||
빌드 과정의 상세 로그가 필요하다면:
|
||||
|
||||
```bash
|
||||
crewai deploy logs
|
||||
```
|
||||
|
||||
<Tip>
|
||||
첫 배포는 보통 약 1분 정도 소요됩니다.
|
||||
</Tip>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 추가 CLI 명령어
|
||||
|
||||
CrewAI CLI는 배포를 관리하기 위한 여러 명령어를 제공합니다:
|
||||
|
||||
```bash
|
||||
# 모든 배포 목록 확인
|
||||
crewai deploy list
|
||||
|
||||
# 배포 상태 확인
|
||||
crewai deploy status
|
||||
|
||||
# 배포 로그 보기
|
||||
crewai deploy logs
|
||||
|
||||
# 코드 변경 후 업데이트 푸시
|
||||
crewai deploy push
|
||||
|
||||
# 배포 삭제
|
||||
crewai deploy remove <deployment_id>
|
||||
```
|
||||
|
||||
## 옵션 2: 웹 인터페이스를 통한 직접 배포
|
||||
|
||||
GitHub 계정을 연결하여 CrewAI AMP 웹 인터페이스를 통해 Crew 또는 Flow를 직접 배포할 수도 있습니다. 이 방법은 로컬 머신에서 CLI를 사용할 필요가 없습니다. 플랫폼은 자동으로 프로젝트 유형을 감지하고 적절하게 빌드를 처리합니다.
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step title="GitHub로 푸시하기">
|
||||
|
||||
Crew를 GitHub 저장소에 푸시해야 합니다. 아직 Crew를 만들지 않았다면, [이 튜토리얼](/ko/quickstart)을 따라할 수 있습니다.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="GitHub를 CrewAI AMP에 연결하기">
|
||||
|
||||
1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다.
|
||||
2. "Connect GitHub" 버튼을 클릭합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="저장소 선택하기">
|
||||
|
||||
GitHub 계정을 연결한 후 배포할 저장소를 선택할 수 있습니다:
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
Crew 또는 Flow가 모노레포 하위 폴더 안에 있다면 배포 전에
|
||||
**Advanced**를 펼치고 작업 디렉터리를 설정하세요.
|
||||
[모노레포 배포](/ko/enterprise/guides/monorepo-deployments)를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="환경 변수 설정하기">
|
||||
|
||||
배포 전에, LLM 제공업체 또는 기타 서비스에 연결할 환경 변수를 설정해야 합니다:
|
||||
|
||||
1. 변수를 개별적으로 또는 일괄적으로 추가할 수 있습니다.
|
||||
2. 환경 변수는 `KEY=VALUE` 형식(한 줄에 하나씩)으로 입력합니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Info>
|
||||
프라이빗 Python 패키지를 사용하시나요? 여기에 레지스트리 자격 증명도 추가해야 합니다.
|
||||
필요한 변수는 [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry)를 참조하세요.
|
||||
</Info>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Crew 배포하기">
|
||||
|
||||
1. "Deploy" 버튼을 클릭하여 배포 프로세스를 시작합니다.
|
||||
2. 진행 바를 통해 진행 상황을 모니터링할 수 있습니다.
|
||||
3. 첫 번째 배포에는 일반적으로 약 1분 정도 소요됩니다
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
배포가 완료되면 다음을 확인할 수 있습니다:
|
||||
- Crew의 고유 URL
|
||||
- Crew API를 보호할 Bearer 토큰
|
||||
- 배포를 삭제해야 하는 경우 "Delete" 버튼
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 옵션 3: API를 통한 재배포 (CI/CD 통합)
|
||||
|
||||
CI/CD 파이프라인에서 자동화된 배포를 위해 CrewAI API를 사용하여 기존 crew의 재배포를 트리거할 수 있습니다. 이 방법은 GitHub Actions, Jenkins 또는 기타 자동화 워크플로우에 특히 유용합니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="개인 액세스 토큰 발급">
|
||||
|
||||
CrewAI AMP 계정 설정에서 API 토큰을 생성합니다:
|
||||
|
||||
1. [app.crewai.com](https://app.crewai.com)으로 이동합니다
|
||||
2. **Settings** → **Account** → **Personal Access Token**을 클릭합니다
|
||||
3. 새 토큰을 생성하고 안전하게 복사합니다
|
||||
4. 이 토큰을 CI/CD 시스템의 시크릿으로 저장합니다
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Automation UUID 찾기">
|
||||
|
||||
배포된 crew의 고유 식별자를 찾습니다:
|
||||
|
||||
1. CrewAI AMP 대시보드에서 **Automations**로 이동합니다
|
||||
2. 기존 automation/crew를 선택합니다
|
||||
3. **Additional Details**를 클릭합니다
|
||||
4. **UUID**를 복사합니다 - 이것이 특정 crew 배포를 식별합니다
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="API를 통한 재배포 트리거">
|
||||
|
||||
Deploy API 엔드포인트를 사용하여 재배포를 트리거합니다:
|
||||
|
||||
```bash
|
||||
curl -i -X POST \
|
||||
-H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
|
||||
https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy
|
||||
|
||||
# HTTP/2 200
|
||||
# content-type: application/json
|
||||
#
|
||||
# {
|
||||
# "uuid": "your-automation-uuid",
|
||||
# "status": "Deploy Enqueued",
|
||||
# "public_url": "https://your-crew-deployment.crewai.com",
|
||||
# "token": "your-bearer-token"
|
||||
# }
|
||||
```
|
||||
|
||||
<Info>
|
||||
Git에 연결되어 처음 생성된 automation의 경우, API가 재배포 전에 자동으로 저장소에서 최신 변경 사항을 가져옵니다.
|
||||
</Info>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="GitHub Actions 통합 예시">
|
||||
|
||||
더 복잡한 배포 트리거가 있는 GitHub Actions 워크플로우 예시입니다:
|
||||
|
||||
```yaml
|
||||
name: Deploy CrewAI Automation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
types: [ labeled ]
|
||||
release:
|
||||
types: [ published ]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
if: |
|
||||
(github.event_name == 'push' && github.ref == 'refs/heads/main') ||
|
||||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) ||
|
||||
(github.event_name == 'release')
|
||||
steps:
|
||||
- name: Trigger CrewAI Redeployment
|
||||
run: |
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \
|
||||
https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`CREWAI_PAT`와 `CREWAI_AUTOMATION_UUID`를 저장소 시크릿으로 추가하세요. PR 배포의 경우 "deploy" 라벨을 추가하여 워크플로우를 트리거합니다.
|
||||
</Tip>
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 배포된 Automation과 상호작용하기
|
||||
|
||||
배포가 완료되면 다음을 통해 crew에 접근할 수 있습니다:
|
||||
|
||||
1. **REST API**: 플랫폼에서 아래의 주요 경로가 포함된 고유한 HTTPS 엔드포인트를 생성합니다:
|
||||
|
||||
- `/inputs`: 필요한 입력 파라미터 목록
|
||||
- `/kickoff`: 제공된 입력값으로 실행 시작
|
||||
- `/status/{kickoff_id}`: 실행 상태 확인
|
||||
|
||||
2. **웹 인터페이스**: [app.crewai.com](https://app.crewai.com)에 방문하여 다음을 확인할 수 있습니다:
|
||||
- **Status 탭**: 배포 정보, API 엔드포인트 세부 정보 및 인증 토큰 확인
|
||||
- **Run 탭**: Crew 구조의 시각적 표현
|
||||
- **Executions 탭**: 모든 실행 내역
|
||||
- **Metrics 탭**: 성능 분석
|
||||
- **Traces 탭**: 상세 실행 인사이트
|
||||
|
||||
### 실행 트리거하기
|
||||
|
||||
Enterprise 대시보드에서 다음 작업을 수행할 수 있습니다:
|
||||
|
||||
1. Crew 이름을 클릭하여 상세 정보를 엽니다
|
||||
2. 관리 인터페이스에서 "Trigger Crew"를 선택합니다
|
||||
3. 나타나는 모달에 필요한 입력값을 입력합니다
|
||||
4. 파이프라인을 따라 실행의 진행 상황을 모니터링합니다
|
||||
|
||||
### 모니터링 및 분석
|
||||
|
||||
Enterprise 플랫폼은 포괄적인 가시성 기능을 제공합니다:
|
||||
|
||||
- **실행 관리**: 활성 및 완료된 실행 추적
|
||||
- **트레이스**: 각 실행의 상세 분해
|
||||
- **메트릭**: 토큰 사용량, 실행 시간, 비용
|
||||
- **타임라인 보기**: 작업 시퀀스의 시각적 표현
|
||||
|
||||
### 고급 기능
|
||||
|
||||
Enterprise 플랫폼은 또한 다음을 제공합니다:
|
||||
|
||||
- **환경 변수 관리**: API 키를 안전하게 저장 및 관리
|
||||
- **LLM 연결**: 다양한 LLM 공급자와의 통합 구성
|
||||
- **Custom Tools Repository**: 도구 생성, 공유 및 설치
|
||||
- **Crew Studio**: 코드를 작성하지 않고 채팅 인터페이스를 통해 crew 빌드
|
||||
|
||||
## 배포 실패 문제 해결
|
||||
|
||||
배포가 실패하면 다음과 같은 일반적인 문제를 확인하세요:
|
||||
|
||||
### 빌드 실패
|
||||
|
||||
#### uv.lock 파일 누락
|
||||
|
||||
**증상**: 의존성 해결 오류와 함께 빌드 초기에 실패
|
||||
|
||||
**해결책**: lock 파일을 생성하고 커밋합니다:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
git add uv.lock
|
||||
git commit -m "Add uv.lock for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`uv.lock` 파일은 모든 배포에 필수입니다. 이 파일이 없으면 플랫폼에서
|
||||
의존성을 안정적으로 설치할 수 없습니다.
|
||||
</Warning>
|
||||
|
||||
#### 잘못된 프로젝트 구조
|
||||
|
||||
**증상**: "Could not find entry point" 또는 "Module not found" 오류
|
||||
|
||||
**해결책**: 프로젝트가 예상 구조와 일치하는지 확인합니다:
|
||||
|
||||
- **JSON-first Crews**: `crew.jsonc` 또는 `crew.json`과 `agents/`를 프로젝트 루트에 둡니다
|
||||
- **클래식 Crews**: `src/project_name/main.py`에 `run()` 진입점을 둡니다
|
||||
- **Flows**: `src/project_name/main.py`에 `kickoff()` 진입점을 둡니다
|
||||
|
||||
자세한 구조 다이어그램은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.
|
||||
|
||||
#### 클래식 Crew의 CrewBase 데코레이터 누락
|
||||
|
||||
**증상**: "Crew not found", "Config not found" 또는 agent/task 구성 오류
|
||||
|
||||
**해결책**: 클래식 Python/YAML crew에서는 모든 crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다. JSON-first crew에는 이 데코레이터가 필요하지 않습니다.
|
||||
|
||||
```python
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
|
||||
@CrewBase # 이 데코레이터는 필수입니다
|
||||
class YourCrew():
|
||||
"""Crew 설명"""
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# ... 나머지 crew 정의
|
||||
```
|
||||
|
||||
<Info>
|
||||
이것은 Flow 프로젝트에 포함된 클래식 crew를 포함하여 클래식 Python crew 클래스에 적용됩니다.
|
||||
JSON-first crew는 `crew.jsonc`와 `agents/`를 기준으로 검증됩니다.
|
||||
</Info>
|
||||
|
||||
#### 잘못된 pyproject.toml 타입
|
||||
|
||||
**증상**: 빌드는 성공하지만 런타임에서 실패하거나 예상치 못한 동작
|
||||
|
||||
**해결책**: `[tool.crewai]` 섹션이 프로젝트 유형과 일치하는지 확인합니다:
|
||||
|
||||
```toml
|
||||
# Crew 프로젝트의 경우:
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
|
||||
# Flow 프로젝트의 경우:
|
||||
[tool.crewai]
|
||||
type = "flow"
|
||||
```
|
||||
|
||||
### 런타임 실패
|
||||
|
||||
#### LLM 연결 실패
|
||||
|
||||
**증상**: API 키 오류, "model not found" 또는 인증 실패
|
||||
|
||||
**해결책**:
|
||||
1. LLM 제공업체의 API 키가 환경 변수에 올바르게 설정되어 있는지 확인합니다
|
||||
2. 환경 변수 이름이 코드에서 예상하는 것과 일치하는지 확인합니다
|
||||
3. 배포 전에 동일한 환경 변수로 로컬에서 테스트합니다
|
||||
|
||||
#### Crew 실행 오류
|
||||
|
||||
**증상**: Crew가 시작되지만 실행 중에 실패
|
||||
|
||||
**해결책**:
|
||||
1. AMP 대시보드에서 실행 로그를 확인합니다 (Traces 탭)
|
||||
2. 모든 도구에 필요한 API 키가 구성되어 있는지 확인합니다
|
||||
3. JSON-first crew의 경우 `crew.jsonc`와 `agents/`에서 참조한 파일을 검증합니다
|
||||
4. 클래식 crew의 경우 `agents.yaml`과 `tasks.yaml`이 유효한지 확인합니다
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
배포 문제 또는 AMP 플랫폼에 대한 문의 사항이 있으시면 지원팀에 연락해 주세요.
|
||||
</Card>
|
||||
180
docs/edge/ko/enterprise/guides/enable-crew-studio.mdx
Normal file
180
docs/edge/ko/enterprise/guides/enable-crew-studio.mdx
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: "Crew Studio 활성화"
|
||||
description: "CrewAI AOP에서 Crew Studio 활성화하기"
|
||||
icon: "comments"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Crew Studio는 대화형 인터페이스를 통해 빠르게 Crew를 스캐폴딩하거나 구축할 수
|
||||
있는 강력한 **노코드/로우코드** 도구입니다.
|
||||
</Tip>
|
||||
|
||||
## Crew Studio란?
|
||||
|
||||
Crew Studio는 코드를 작성하지 않고도 AI agent crew를 생성할 수 있는 혁신적인 방법입니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Crew Studio를 사용하면 다음과 같은 작업이 가능합니다:
|
||||
|
||||
- Crew Assistant와 채팅하여 문제를 설명
|
||||
- agent 및 task를 자동으로 생성
|
||||
- 적절한 tool 선택
|
||||
- 필요한 입력값 구성
|
||||
- 커스터마이징을 위한 다운로드 가능한 코드 생성
|
||||
- CrewAI AMP 플랫폼에 직접 배포
|
||||
|
||||
## 구성 단계
|
||||
|
||||
Crew Studio를 사용하기 전에 LLM 연결을 구성해야 합니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="LLM 연결 설정">
|
||||
CrewAI AMP 대시보드의 **LLM Connections** 탭으로 이동하여 새 LLM 연결을 만듭니다.
|
||||
|
||||
<Note>
|
||||
CrewAI에서 지원하는 원하는 LLM 공급자를 자유롭게 사용하실 수 있습니다.
|
||||
</Note>
|
||||
|
||||
LLM 연결을 구성하세요:
|
||||
|
||||
- `Connection Name`(예: `OpenAI`)을 입력하세요.
|
||||
- 모델 공급자를 선택하세요: `openai` 또는 `azure`
|
||||
- Studio에서 생성되는 Crews에 사용할 모델을 선택하세요.
|
||||
- 최소한 `gpt-4o`, `o1-mini`, `gpt-4o-mini`를 권장합니다.
|
||||
- API 키를 환경 변수로 추가하세요:
|
||||
- OpenAI의 경우: `OPENAI_API_KEY`에 API 키를 추가
|
||||
- Azure OpenAI의 경우: [이 글](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/)을 참고하여 구성
|
||||
- `Add Connection`을 클릭하여 구성을 저장하세요.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="연결 추가 확인">
|
||||
설정이 완료되면 새 연결이 사용 가능한 연결 목록에 추가된 것을 볼 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="LLM 기본값 구성">
|
||||
메인 메뉴에서 **Settings → Defaults**로 이동하여 LLM 기본값을 구성하세요:
|
||||
|
||||
- 에이전트 및 기타 구성 요소의 기본 모델을 선택하세요
|
||||
- Crew Studio의 기본 구성을 설정하세요
|
||||
|
||||
변경 사항을 적용하려면 `Save Settings`를 클릭하세요.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Crew Studio 사용하기
|
||||
|
||||
LLM 연결과 기본 설정을 구성했다면 이제 Crew Studio 사용을 시작할 준비가 완료되었습니다!
|
||||
|
||||
<Steps>
|
||||
<Step title="Studio 접속">
|
||||
CrewAI AMP 대시보드에서 **Studio** 섹션으로 이동하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="대화 시작">
|
||||
Crew Assistant와 대화를 시작하며 해결하고자 하는 문제를 설명하세요:
|
||||
|
||||
```md
|
||||
I need a crew that can research the latest AI developments and create a summary report.
|
||||
```
|
||||
|
||||
Crew Assistant는 귀하의 요구 사항을 더 잘 이해하기 위해 추가 질문을 할 것입니다.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="생성된 crew 검토">
|
||||
생성된 crew 구성을 검토하세요. 구성에는 다음이 포함됩니다:
|
||||
|
||||
- 에이전트 및 그들의 역할
|
||||
- 수행할 작업
|
||||
- 필요한 입력값
|
||||
- 사용할 도구
|
||||
|
||||
이 단계에서 구성 내용을 세부적으로 수정할 수 있습니다.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="배포 또는 다운로드">
|
||||
구성에 만족하면 다음을 수행할 수 있습니다:
|
||||
|
||||
- 생성된 코드를 다운로드하여 로컬에서 커스터마이징
|
||||
- crew를 CrewAI AMP 플랫폼에 직접 배포
|
||||
- 구성을 수정하고 crew를 재생성
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="crew 테스트">
|
||||
배포 후 샘플 입력으로 crew를 테스트하여 기대한 대로 동작하는지 확인하세요.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
최상의 결과를 얻으려면 crew가 달성해야 할 목표를 명확하고 상세하게 설명하세요.
|
||||
원하는 입력값과 예상 결과를 설명에 포함시키는 것이 좋습니다.
|
||||
</Tip>
|
||||
|
||||
## 예시 워크플로우
|
||||
|
||||
다음은 Crew Studio를 사용하여 crew를 생성하는 일반적인 워크플로우입니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="문제 설명하기">
|
||||
먼저 문제를 설명하세요:
|
||||
|
||||
```md
|
||||
I need a crew that can analyze financial news and provide investment recommendations
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="질문에 답하기">
|
||||
crew assistant가 요구 사항을 구체화할 수 있도록 하는 추가 질문에 답변하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="계획 검토하기">
|
||||
생성된 crew 계획을 검토하세요. 여기에는 다음과 같은 항목이 포함될 수 있습니다:
|
||||
|
||||
- 금융 뉴스를 수집하는 Research Agent
|
||||
- 데이터를 해석하는 Analysis Agent
|
||||
- 투자 조언을 제공하는 Recommendations Agent
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="승인 또는 수정">
|
||||
계획을 승인하거나 필요하다면 변경을 요청하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="다운로드 또는 배포">
|
||||
사용자화를 위해 코드를 다운로드하거나 플랫폼에 직접 배포하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="테스트 및 개선">
|
||||
샘플 입력으로 crew를 테스트하고 필요에 따라 개선하세요.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Card
|
||||
title="도움이 필요하세요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Crew Studio 또는 기타 CrewAI AMP 기능 지원이 필요하다면 지원팀에 문의하세요.
|
||||
</Card>
|
||||
96
docs/edge/ko/enterprise/guides/gmail-trigger.mdx
Normal file
96
docs/edge/ko/enterprise/guides/gmail-trigger.mdx
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: "Gmail Trigger"
|
||||
description: "Trigger automations when Gmail events occur (e.g., new emails, labels)."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter.
|
||||
|
||||
<Tip>
|
||||
Make sure Gmail is connected in Tools & Integrations and the trigger is
|
||||
enabled for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Gmail Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Gmail** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/trigger-selected.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Process new emails
|
||||
|
||||
When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload.
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class GmailProcessingCrew:
|
||||
@agent
|
||||
def parser(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['parser'],
|
||||
)
|
||||
|
||||
@task
|
||||
def parse_gmail_payload(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['parse_gmail_payload'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
|
||||
@task
|
||||
def act_on_email(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['act_on_email'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
```
|
||||
|
||||
The Gmail payload will be available via the standard context mechanisms.
|
||||
|
||||
### 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 Gmail 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 Gmail 트리거 시뮬레이션
|
||||
crewai triggers run gmail/new_email_received
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 Gmail payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run gmail/new_email_received`을 사용하세요
|
||||
(`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
Track history and performance of triggered runs:
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure Gmail is connected in Tools & Integrations
|
||||
- Verify the Gmail Trigger is enabled on the Triggers tab
|
||||
- `crewai triggers run gmail/new_email_received`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- Check the execution logs and confirm the payload is passed as `crewai_trigger_payload`
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
82
docs/edge/ko/enterprise/guides/google-calendar-trigger.mdx
Normal file
82
docs/edge/ko/enterprise/guides/google-calendar-trigger.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "Google Calendar Trigger"
|
||||
description: "Kick off crews when Google Calendar events are created, updated, or cancelled"
|
||||
icon: "calendar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules.
|
||||
|
||||
<Tip>
|
||||
Make sure Google Calendar is connected in **Tools & Integrations** and enabled
|
||||
for the deployment you want to automate.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Google Calendar Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Google Calendar** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/calendar-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize meeting details
|
||||
|
||||
The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools.
|
||||
|
||||
```python
|
||||
from calendar_event_crew import GoogleCalendarEventTrigger
|
||||
|
||||
crew = GoogleCalendarEventTrigger().crew()
|
||||
result = crew.kickoff({
|
||||
"crewai_trigger_payload": calendar_payload,
|
||||
})
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields.
|
||||
|
||||
## 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 Google Calendar 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 Google Calendar 트리거 시뮬레이션
|
||||
crewai triggers run google_calendar/event_changed
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 Calendar payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run google_calendar/event_changed`를 사용하세요
|
||||
(`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the correct Google account is connected and the trigger is enabled
|
||||
- `crewai triggers run google_calendar/event_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps)
|
||||
- Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
79
docs/edge/ko/enterprise/guides/google-drive-trigger.mdx
Normal file
79
docs/edge/ko/enterprise/guides/google-drive-trigger.mdx
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Google Drive Trigger"
|
||||
description: "Respond to Google Drive file events with automated crews"
|
||||
icon: "folder"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change.
|
||||
|
||||
<Tip>
|
||||
Connect Google Drive in **Tools & Integrations** and confirm the trigger is
|
||||
enabled for the automation you want to monitor.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Google Drive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Google Drive** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/gdrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize file activity
|
||||
|
||||
The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary.
|
||||
|
||||
```python
|
||||
from drive_file_crew import GoogleDriveFileTrigger
|
||||
|
||||
crew = GoogleDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": drive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
## 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 Google Drive 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 Google Drive 트리거 시뮬레이션
|
||||
crewai triggers run google_drive/file_changed
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 Drive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run google_drive/file_changed`를 사용하세요
|
||||
(`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
|
||||
</Warning>
|
||||
|
||||
## Monitoring Executions
|
||||
|
||||
Track history and performance of triggered runs with the **Executions** list in the deployment dashboard.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/list-executions.png"
|
||||
alt="List of executions triggered by automation"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Verify Google Drive is connected and the trigger toggle is enabled
|
||||
- `crewai triggers run google_drive/file_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- If a payload is missing permission data, ensure the connected account has access to the file or folder
|
||||
- The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
61
docs/edge/ko/enterprise/guides/hubspot-trigger.mdx
Normal file
61
docs/edge/ko/enterprise/guides/hubspot-trigger.mdx
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "HubSpot 트리거"
|
||||
description: "HubSpot 워크플로우에서 CrewAI 크루를 직접 트리거하세요"
|
||||
icon: "hubspot"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이 가이드는 HubSpot Workflows에서 직접 crew를 시작할 수 있도록 CrewAI AOP용 HubSpot 트리거를 설정하는 단계별 과정을 제공합니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
- CrewAI AMP 계정
|
||||
- [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) 기능이 활성화된 HubSpot 계정
|
||||
|
||||
## 설정 단계
|
||||
|
||||
<Steps>
|
||||
<Step title="HubSpot 계정을 CrewAI AOP와 연결하기">
|
||||
- `CrewAI AMP 계정 > 트리거`에 로그인합니다. - 사용 가능한 트리거 목록에서
|
||||
`HubSpot`을 선택합니다. - CrewAI AOP와 연결하고자 하는 HubSpot 계정을
|
||||
선택합니다. - 화면에 나타나는 안내에 따라 CrewAI AOP가 HubSpot 계정에
|
||||
접근하도록 승인합니다. - HubSpot이 CrewAI AOP와 성공적으로 연결되면 확인
|
||||
메시지가 표시됩니다.
|
||||
</Step>
|
||||
<Step title="HubSpot 워크플로우 생성하기">
|
||||
- `HubSpot 계정 > 자동화 > 워크플로우 > 새 워크플로우`에 로그인합니다. -
|
||||
필요에 맞는 워크플로우 유형을 선택합니다 (예: 처음부터 시작). - 워크플로우
|
||||
빌더에서 더하기(+) 아이콘을 클릭하여 새로운 작업을 추가합니다. - `통합 앱 >
|
||||
CrewAI > Crew 시작하기`를 선택합니다. - 시작할 Crew를 선택합니다. - `저장`을
|
||||
클릭하여 워크플로우에 작업을 추가합니다.
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/hubspot-workflow-1.png"
|
||||
alt="HubSpot Workflow 1"
|
||||
/>
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Crew 결과를 다른 작업과 함께 사용하기">
|
||||
- Crew 시작 단계 이후, 더하기(+) 아이콘을 클릭하여 새로운 작업을 추가합니다.
|
||||
- 예를 들어, 내부 이메일 알림을 전송하려면 `커뮤니케이션 > 내부 이메일 알림
|
||||
전송`을 선택합니다. - 본문 필드에서 `데이터 삽입`을 클릭하고, `다음에서 속성
|
||||
또는 작업 결과 보기 > 작업 결과 > Crew 결과`를 선택하여 이메일에 Crew
|
||||
데이터를 포함합니다.
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/hubspot-workflow-2.png"
|
||||
alt="HubSpot Workflow 2"
|
||||
/>
|
||||
</Frame>
|
||||
- 필요에 따라 추가 작업을 구성합니다. - 모든 워크플로우 단계를
|
||||
검토하여 올바르게 설정되었는지 확인합니다. - 워크플로우를 활성화합니다.
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/hubspot-workflow-3.png"
|
||||
alt="HubSpot Workflow 3"
|
||||
/>
|
||||
</Frame>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
사용 가능한 작업과 사용자 지정 옵션에 대한 자세한 정보는 [HubSpot 워크플로우 문서](https://knowledge.hubspot.com/workflows/create-workflows)를 참고하세요.
|
||||
157
docs/edge/ko/enterprise/guides/human-in-the-loop.mdx
Normal file
157
docs/edge/ko/enterprise/guides/human-in-the-loop.mdx
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: "HITL 워크플로우"
|
||||
description: "CrewAI에서 의사결정 향상을 위한 Human-In-The-Loop 워크플로우 구현 방법을 알아보세요"
|
||||
icon: "user-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
인간-중심(Human-In-The-Loop, HITL)은 인공지능과 인간 전문 지식을 결합하여 의사결정을 강화하고 작업 결과를 향상시키는 강력한 접근 방식입니다. 이 가이드는 CrewAI Enterprise 내에서 HITL을 구현하는 방법을 보여줍니다.
|
||||
|
||||
## CrewAI의 HITL 접근 방식
|
||||
|
||||
CrewAI는 human-in-the-loop 워크플로우를 구현하기 위한 두 가지 접근 방식을 제공합니다:
|
||||
|
||||
| 접근 방식 | 적합한 용도 | 버전 |
|
||||
|----------|----------|---------|
|
||||
| **Flow 기반** (`@human_feedback` 데코레이터) | Enterprise UI를 사용한 프로덕션, 이메일 우선 워크플로우, 전체 플랫폼 기능 | **1.8.0+** |
|
||||
| **Webhook 기반** | 커스텀 통합, 외부 시스템 (Slack, Teams 등), 레거시 설정 | 모든 버전 |
|
||||
|
||||
## Enterprise 플랫폼과 Flow 기반 HITL
|
||||
|
||||
<Note>
|
||||
`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다.
|
||||
</Note>
|
||||
|
||||
Flow에서 `@human_feedback` 데코레이터를 사용하면, CrewAI Enterprise는 이메일 주소가 있는 누구나 검토 요청에 응답할 수 있는 **이메일 우선 HITL 시스템**을 제공합니다:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="이메일 우선 설계" icon="envelope">
|
||||
응답자가 이메일 알림을 받고 직접 회신할 수 있습니다—로그인이 필요 없습니다.
|
||||
</Card>
|
||||
<Card title="대시보드 검토" icon="desktop">
|
||||
원할 때 Enterprise 대시보드에서 HITL 요청을 검토하고 응답하세요.
|
||||
</Card>
|
||||
<Card title="유연한 라우팅" icon="route">
|
||||
메서드 패턴에 따라 특정 이메일로 요청을 라우팅하거나 Flow 상태에서 가져오세요.
|
||||
</Card>
|
||||
<Card title="자동 응답" icon="clock">
|
||||
타임아웃 내에 인간이 응답하지 않을 경우 자동 대체 응답을 구성하세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### 주요 이점
|
||||
|
||||
- **외부 응답자**: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
|
||||
- **동적 할당**: Flow 상태에서 담당자 이메일 가져오기 (예: `account_owner_email`)
|
||||
- **간단한 구성**: 이메일 기반 라우팅은 사용자/역할 관리보다 설정이 쉬움
|
||||
- **배포 생성자 대체**: 라우팅 규칙이 일치하지 않으면 배포 생성자에게 알림
|
||||
|
||||
<Tip>
|
||||
`@human_feedback` 데코레이터의 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
## Webhook 기반 HITL 워크플로 설정
|
||||
|
||||
Slack, Microsoft Teams 또는 자체 애플리케이션과 같은 외부 시스템과의 커스텀 통합을 위해 webhook 기반 접근 방식을 사용할 수 있습니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="작업 구성">
|
||||
사람 입력이 활성화된 상태로 작업을 설정하세요:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/crew-human-input.png" alt="Crew Human Input" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Webhook URL 제공">
|
||||
crew를 시작할 때 인간 입력을 위한 webhook URL을 포함하세요:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/crew-webhook-url.png" alt="Crew Webhook URL" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Webhook 알림 받기">
|
||||
crew가 사람 입력이 필요한 작업을 완료하면 다음 정보를 포함한 webhook 알림을 받게 됩니다:
|
||||
- **Execution ID**
|
||||
- **Task ID**
|
||||
- **Task output**
|
||||
</Step>
|
||||
|
||||
<Step title="작업 출력 검토">
|
||||
시스템이 `Pending Human Input` 상태에서 일시 중지됩니다. 작업 출력을 신중하게 검토하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="사람 피드백 제출">
|
||||
다음 정보를 포함하여 crew의 resume endpoint를 호출하세요:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/crew-resume-endpoint.png" alt="Crew Resume Endpoint" />
|
||||
</Frame>
|
||||
|
||||
<Warning>
|
||||
**중요: Webhook URL을 다시 제공해야 합니다**:
|
||||
kickoff 호출에서 사용한 것과 동일한 webhook URL(`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`)을 resume 호출에서 **반드시** 제공해야 합니다. Webhook 설정은 kickoff에서 자동으로 전달되지 **않으므로**, 작업 완료, 에이전트 단계, crew 완료에 대한 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 합니다.
|
||||
</Warning>
|
||||
|
||||
Webhook을 포함한 resume 호출 예시:
|
||||
```bash
|
||||
curl -X POST {BASE_URL}/resume \
|
||||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
|
||||
"task_id": "research_task",
|
||||
"human_feedback": "훌륭한 작업입니다! 더 자세한 내용을 추가해주세요.",
|
||||
"is_approve": true,
|
||||
"taskWebhookUrl": "https://your-server.com/webhooks/task",
|
||||
"stepWebhookUrl": "https://your-server.com/webhooks/step",
|
||||
"crewWebhookUrl": "https://your-server.com/webhooks/crew"
|
||||
}'
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**피드백이 작업 실행에 미치는 영향**:
|
||||
피드백 전체 내용이 이후 작업 실행을 위한 추가 컨텍스트로 통합되므로 피드백 제공 시 신중함이 매우 중요합니다.
|
||||
</Warning>
|
||||
이는 다음을 의미합니다:
|
||||
- 피드백에 입력한 모든 정보가 작업의 컨텍스트 일부가 됩니다.
|
||||
- 관련 없는 상세 정보는 부정적인 영향을 줄 수 있습니다.
|
||||
- 간결하고 관련성 높은 피드백이 작업의 집중도와 효율성을 유지하는 데 도움이 됩니다.
|
||||
- 제출 전 항상 피드백을 신중히 검토하여 작업 실행을 긍정적으로 안내할 수 있는 관련 정보만 포함되어 있는지 확인하세요.
|
||||
</Step>
|
||||
<Step title="부정적 피드백 처리">
|
||||
부정적인 피드백을 제공하는 경우:
|
||||
- crew가 귀하의 피드백에서 추가된 컨텍스트와 함께 작업을 재시도합니다.
|
||||
- 추가 확인을 위한 다른 webhook 알림을 받게 됩니다.
|
||||
- 만족할 때까지 4-6단계를 반복하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="작업 실행 계속 진행">
|
||||
긍정적인 피드백을 제출하면 실행이 다음 단계로 진행됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 모범 사례
|
||||
|
||||
- **구체적으로 작성하세요**: 해당 작업에 직접적으로 관련된 명확하고 실행 가능한 피드백을 제공하세요
|
||||
- **관련성 유지**: 작업 수행 개선에 도움이 되는 정보만 포함하세요
|
||||
- **적시에 응답하세요**: 워크플로우 지연을 피하기 위해 HITL 프롬프트에 신속하게 응답하세요
|
||||
- **꼼꼼하게 검토하세요**: 제출 전에 피드백을 다시 확인하여 정확성을 보장하세요
|
||||
|
||||
## 일반적인 사용 사례
|
||||
|
||||
HITL 워크플로우는 특히 다음과 같은 경우에 유용합니다:
|
||||
- 품질 보증 및 검증
|
||||
- 복잡한 의사 결정 시나리오
|
||||
- 민감하거나 위험도가 높은 작업
|
||||
- 인간의 판단이 필요한 창의적 작업
|
||||
- 준수 및 규제 검토
|
||||
|
||||
## 자세히 알아보기
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Flow HITL 관리" icon="users-gear" href="/ko/enterprise/features/flow-hitl-management">
|
||||
이메일 알림, 라우팅 규칙, 자동 응답 및 분석을 포함한 전체 Enterprise Flow HITL 플랫폼 기능을 살펴보세요.
|
||||
</Card>
|
||||
<Card title="Flow에서 인간 피드백" icon="code" href="/ko/learn/human-feedback-in-flows">
|
||||
Flow에서 `@human_feedback` 데코레이터 구현 가이드.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
182
docs/edge/ko/enterprise/guides/kickoff-crew.mdx
Normal file
182
docs/edge/ko/enterprise/guides/kickoff-crew.mdx
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "Kickoff Crew"
|
||||
description: "CrewAI AOP에서 Crew를 시작하세요"
|
||||
icon: "flag-checkered"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Crew를 CrewAI AMP 플랫폼에 배포한 후에는 웹 인터페이스 또는 API를 통해 실행을 시작할 수 있습니다. 이 가이드는 두 가지 접근 방식을 모두 다룹니다.
|
||||
|
||||
## 방법 1: 웹 인터페이스 사용
|
||||
|
||||
### 1단계: 배포된 Crew로 이동하기
|
||||
|
||||
1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다.
|
||||
2. 프로젝트 목록에서 crew 이름을 클릭합니다.
|
||||
3. crew의 상세 페이지로 이동합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 2단계: 실행 시작
|
||||
|
||||
crew의 상세 페이지에서 실행을 시작할 수 있는 두 가지 옵션이 있습니다:
|
||||
|
||||
#### 옵션 A: 빠른 시작
|
||||
|
||||
1. Test Endpoints 섹션에서 `Kickoff` 링크를 클릭합니다.
|
||||
2. JSON 에디터에서 crew에 필요한 입력 파라미터를 입력합니다.
|
||||
3. `Send Request` 버튼을 클릭합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
#### 옵션 B: 시각적 인터페이스 사용
|
||||
|
||||
1. crew 상세 페이지에서 `Run` 탭을 클릭합니다.
|
||||
2. 양식 필드에 필요한 입력값을 입력합니다.
|
||||
3. `Run Crew` 버튼을 클릭합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 3단계: 실행 진행 상황 모니터링
|
||||
|
||||
실행을 시작한 후:
|
||||
|
||||
1. `kickoff_id`가 포함된 응답을 받게 됩니다. - **이 ID를 복사하세요**
|
||||
2. 이 ID는 실행을 추적하는 데 필수적입니다
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 4단계: 실행 상태 확인
|
||||
|
||||
실행 진행 상황을 모니터링하려면:
|
||||
|
||||
1. Test Endpoints 섹션에서 "Status" 엔드포인트를 클릭하세요
|
||||
2. 지정된 필드에 `kickoff_id`를 붙여넣으세요
|
||||
3. "Get Status" 버튼을 클릭하세요
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
상태 응답에는 다음이 표시됩니다:
|
||||
|
||||
- 현재 실행 상태(`running`, `completed` 등)
|
||||
- 진행 중인 작업에 대한 세부 정보
|
||||
- 지금까지 생성된 모든 출력
|
||||
|
||||
### 5단계: 최종 결과 보기
|
||||
|
||||
실행이 완료되면:
|
||||
|
||||
1. 상태가 `completed`로 변경됩니다.
|
||||
2. 전체 실행 결과와 출력을 확인할 수 있습니다.
|
||||
3. 더 자세한 내용을 보려면 crew 상세 페이지의 `Executions` 탭을 확인하세요.
|
||||
|
||||
## 방법 2: API 사용
|
||||
|
||||
CrewAI AMP REST API를 사용하여 프로그래밍 방식으로 crews를 시작할 수도 있습니다.
|
||||
|
||||
### 인증
|
||||
|
||||
모든 API 요청에는 인증을 위한 베어러 토큰이 필요합니다:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
|
||||
```
|
||||
|
||||
베어러 토큰은 crew의 상세 페이지의 Status 탭에서 확인할 수 있습니다.
|
||||
|
||||
### 크루 상태 확인
|
||||
|
||||
작업을 실행하기 전에 크루가 정상적으로 실행되고 있는지 확인할 수 있습니다:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com
|
||||
```
|
||||
|
||||
요청이 성공하면 크루가 정상적으로 동작 중임을 나타내는 메시지가 반환됩니다:
|
||||
|
||||
```
|
||||
Healthy%
|
||||
```
|
||||
|
||||
### 1단계: 필요한 입력값 확인
|
||||
|
||||
먼저, crew에서 요구하는 입력값이 무엇인지 확인합니다:
|
||||
|
||||
```bash
|
||||
curl -X GET \
|
||||
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
https://your-crew-url.crewai.com/inputs
|
||||
```
|
||||
|
||||
응답은 예를 들어 다음과 같이 필수 입력 파라미터 배열을 포함한 JSON 객체로 반환됩니다:
|
||||
|
||||
```json
|
||||
{ "inputs": ["topic", "current_year"] }
|
||||
```
|
||||
|
||||
이 예시에서는 해당 crew에서 두 개의 입력값인 `topic`과 `current_year`를 필요로 함을 보여줍니다.
|
||||
|
||||
### 2단계: kickoff 실행
|
||||
|
||||
필수 입력값을 제공하여 실행을 시작합니다:
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
-d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
|
||||
https://your-crew-url.crewai.com/kickoff
|
||||
```
|
||||
|
||||
응답에는 추적에 필요한 `kickoff_id`가 포함됩니다:
|
||||
|
||||
```json
|
||||
{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" }
|
||||
```
|
||||
|
||||
### 3단계: 실행 상태 확인
|
||||
|
||||
kickoff_id를 사용하여 실행 진행 상황을 모니터링하세요:
|
||||
|
||||
```bash
|
||||
curl -X GET \
|
||||
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
|
||||
```
|
||||
|
||||
## 실행 처리
|
||||
|
||||
### 장기 실행
|
||||
|
||||
오랜 시간이 걸릴 수 있는 실행의 경우:
|
||||
|
||||
1. 주기적으로 상태를 확인하는 폴링 메커니즘을 구현하는 것을 고려하세요
|
||||
2. 실행 완료 시 알림을 받을 수 있도록 웹훅(가능한 경우)을 사용하세요
|
||||
3. 잠재적인 타임아웃에 대비하여 오류 처리를 구현하세요
|
||||
|
||||
### 실행 컨텍스트
|
||||
|
||||
실행 컨텍스트에는 다음이 포함됩니다:
|
||||
|
||||
- 시작 시 제공된 입력값
|
||||
- 배포 중에 구성된 환경 변수
|
||||
- 태스크 간에 유지되는 상태
|
||||
|
||||
### 실행 실패 디버깅
|
||||
|
||||
실행이 실패할 경우:
|
||||
|
||||
1. "Executions" 탭에서 자세한 로그를 확인하세요
|
||||
2. "Traces" 탭에서 단계별 실행 세부 정보를 검토하세요
|
||||
3. 트레이스 세부 정보에서 LLM 응답과 도구 사용 내역을 확인하세요
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
실행 문제 또는 엔터프라이즈 플랫폼 관련 질문이 있으신 경우, 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
70
docs/edge/ko/enterprise/guides/microsoft-teams-trigger.mdx
Normal file
70
docs/edge/ko/enterprise/guides/microsoft-teams-trigger.mdx
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: "Microsoft Teams Trigger"
|
||||
description: "Kick off crews from Microsoft Teams chat activity"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems.
|
||||
|
||||
<Tip>
|
||||
Confirm Microsoft Teams is connected under **Tools & Integrations** and
|
||||
enabled in the **Triggers** tab for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Microsoft Teams Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Microsoft Teams** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft Teams trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/msteams-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize a new chat thread
|
||||
|
||||
```python
|
||||
from teams_chat_created_crew import MicrosoftTeamsChatTrigger
|
||||
|
||||
crew = MicrosoftTeamsChatTrigger().crew()
|
||||
result = crew.kickoff({
|
||||
"crewai_trigger_payload": teams_payload,
|
||||
})
|
||||
print(result.raw)
|
||||
```
|
||||
|
||||
The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team.
|
||||
|
||||
## 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 Microsoft Teams 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 Microsoft Teams 트리거 시뮬레이션
|
||||
crewai triggers run microsoft_teams/teams_message_created
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 Teams payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run microsoft_teams/teams_message_created`를
|
||||
사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를
|
||||
받습니다.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions
|
||||
- `crewai triggers run microsoft_teams/teams_message_created`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving
|
||||
- Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
226
docs/edge/ko/enterprise/guides/monorepo-deployments.mdx
Normal file
226
docs/edge/ko/enterprise/guides/monorepo-deployments.mdx
Normal file
@@ -0,0 +1,226 @@
|
||||
---
|
||||
title: "모노레포 배포"
|
||||
description: "더 큰 저장소의 하위 폴더에서 Crew 또는 Flow 배포하기"
|
||||
icon: "folder-tree"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Crew 또는 Flow가 더 큰 저장소 안에 있을 때 작업 디렉터리를 사용하세요.
|
||||
CrewAI AMP는 저장소 루트 대신 해당 하위 폴더에서 자동화를 검증, 빌드,
|
||||
실행합니다.
|
||||
</Note>
|
||||
|
||||
## 사용 시점
|
||||
|
||||
모노레포 배포는 하나의 저장소에 여러 자동화, 공유 패키지 또는 다른 애플리케이션
|
||||
코드가 함께 있을 때 유용합니다:
|
||||
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
|-- support_agent/
|
||||
| |-- pyproject.toml
|
||||
| |-- crew.jsonc
|
||||
| `-- agents/
|
||||
| `-- support_agent.jsonc
|
||||
`-- research_flow/
|
||||
|-- pyproject.toml
|
||||
`-- src/
|
||||
`-- research_flow/
|
||||
`-- main.py
|
||||
```
|
||||
|
||||
`support_agent`를 배포하려면 작업 디렉터리를 다음과 같이 설정합니다:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
AMP는 여전히 전체 저장소를 가져오거나 업로드하지만, 선택한 폴더를 자동화
|
||||
프로젝트 루트로 처리합니다.
|
||||
|
||||
## 작업 디렉터리가 제어하는 항목
|
||||
|
||||
작업 디렉터리가 설정되면 AMP는 해당 폴더를 다음 용도로 사용합니다:
|
||||
|
||||
- `pyproject.toml`, JSON crew 파일, 클래식 Crew 또는 Flow 진입점을 포함한 프로젝트 검증
|
||||
- `uv`를 사용한 종속성 설치
|
||||
- 실행 중인 프로세스의 작업 디렉터리
|
||||
- `CREW_ROOT_DIR` 환경 변수
|
||||
|
||||
필드를 비워 두면 기존 동작이 유지되며 저장소 루트를 사용합니다.
|
||||
|
||||
## 지원되는 소스
|
||||
|
||||
다음 소스에서 배포를 만들 때 작업 디렉터리를 설정할 수 있습니다:
|
||||
|
||||
- 연결된 GitHub 저장소
|
||||
- AMP에 구성된 Git 저장소
|
||||
- ZIP 업로드
|
||||
|
||||
<Info>
|
||||
작업 디렉터리는 AMP 웹 인터페이스에서 구성하세요.
|
||||
`crewai deploy create` CLI 흐름은 이 필드를 묻지 않습니다.
|
||||
</Info>
|
||||
|
||||
기존 배포의 **Settings** 페이지에서도 작업 디렉터리를 추가하거나 변경할 수
|
||||
있습니다. 변경 사항은 다음 배포부터 적용됩니다.
|
||||
|
||||
<Warning>
|
||||
작업 디렉터리와 auto-deploy는 함께 사용할 수 없습니다. 배포에 작업
|
||||
디렉터리가 설정되어 있으면 해당 배포의 auto-deploy가 비활성화됩니다.
|
||||
작업 디렉터리를 설정하기 전에 auto-deploy를 끄세요.
|
||||
</Warning>
|
||||
|
||||
## 새 배포 구성
|
||||
|
||||
<Steps>
|
||||
<Step title="Deploy from Code 열기">
|
||||
CrewAI AMP에서 새 배포를 만들고 소스를 선택합니다: GitHub, Git
|
||||
Repository 또는 ZIP 업로드.
|
||||
</Step>
|
||||
|
||||
<Step title="저장소, 브랜치 또는 ZIP 파일 선택">
|
||||
모노레포가 들어 있는 저장소와 브랜치를 선택하거나, 루트에 모노레포 내용이
|
||||
포함된 ZIP 파일을 업로드합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="고급 설정 열기">
|
||||
배포 양식에서 **Advanced** 섹션을 펼칩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="작업 디렉터리 입력">
|
||||
저장소 루트에서 Crew 또는 Flow 프로젝트까지의 경로를 입력합니다:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
앞에 슬래시를 붙이지 마세요.
|
||||
</Step>
|
||||
|
||||
<Step title="배포">
|
||||
필요한 환경 변수를 추가한 다음 배포를 시작합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 기존 배포 구성
|
||||
|
||||
<Steps>
|
||||
<Step title="배포 설정 열기">
|
||||
AMP에서 자동화로 이동한 뒤 **Settings**를 엽니다.
|
||||
</Step>
|
||||
|
||||
<Step title="필요한 경우 auto-deploy 끄기">
|
||||
auto-deploy가 활성화되어 있으면 먼저 끄세요. auto-deploy가 켜져 있는
|
||||
동안에는 작업 디렉터리 필드를 사용할 수 없습니다.
|
||||
</Step>
|
||||
|
||||
<Step title="작업 디렉터리 설정">
|
||||
**Basic settings**에서 다음과 같은 하위 폴더 경로를 입력합니다:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="다시 배포">
|
||||
설정을 저장하고 자동화를 다시 배포합니다. 새 작업 디렉터리는 다음 배포부터
|
||||
사용됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 경로 규칙
|
||||
|
||||
작업 디렉터리는 저장소 또는 ZIP 루트 안의 상대 경로여야 합니다.
|
||||
|
||||
| 규칙 | 예시 |
|
||||
|------|------|
|
||||
| 상대 경로를 사용합니다 | `crews/support_agent` |
|
||||
| `/`로 시작하지 않습니다 | `/crews/support_agent`는 유효하지 않습니다 |
|
||||
| `.` 또는 `..` 경로 세그먼트를 사용하지 않습니다 | `crews/../support_agent`는 유효하지 않습니다 |
|
||||
| 문자, 숫자, 하이픈, 밑줄, 점, 슬래시만 사용합니다 | `crews/support agent`는 유효하지 않습니다 |
|
||||
| 경로는 255자 이하로 유지합니다 | 더 긴 경로는 거부됩니다 |
|
||||
|
||||
AMP는 앞뒤 공백을 제거하고, 반복된 슬래시를 하나로 줄이며, 끝의 슬래시를
|
||||
제거합니다. 빈 값은 저장소 루트를 사용합니다.
|
||||
|
||||
## Lock 파일과 UV 워크스페이스
|
||||
|
||||
선택한 폴더에는 자동화의 `pyproject.toml`과 프로젝트 유형에 맞는 파일이
|
||||
있어야 합니다:
|
||||
|
||||
- JSON-first crew: `crew.jsonc` 또는 `crew.json`과 `agents/`
|
||||
- 클래식 Crew 또는 Flow: Python 진입점이 있는 `src/`
|
||||
|
||||
`uv.lock` 또는 `poetry.lock` 파일은 선택한 폴더나 저장소 루트에 둘 수
|
||||
있습니다.
|
||||
|
||||
이 방식은 일반적인 두 가지 lock 파일 배치를 모두 지원합니다:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="프로젝트 lock 파일">
|
||||
```text
|
||||
company-ai/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- uv.lock
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="워크스페이스 lock 파일">
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
자동화가 모노레포의 다른 위치에 있는 공유 패키지를 가져온다면, UV
|
||||
workspace, path 또는 source 설정을 사용해 해당 패키지를 `pyproject.toml`에
|
||||
선언하세요. AMP는 선택한 폴더에서 자동화를 실행하므로, 저장소 루트가
|
||||
Python path에 있다고 가정하기보다 공유 코드를 종속성으로 설치해야 합니다.
|
||||
</Tip>
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 작업 디렉터리를 찾을 수 없음
|
||||
|
||||
경로가 저장소 또는 ZIP 루트를 기준으로 한 상대 경로인지 확인하세요. ZIP
|
||||
업로드의 경우 ZIP 내용에 입력한 작업 디렉터리 경로가 정확히 포함되어야 합니다.
|
||||
|
||||
### pyproject.toml 누락
|
||||
|
||||
작업 디렉터리는 여러 프로젝트를 담은 상위 폴더가 아니라 Crew 또는 Flow 프로젝트
|
||||
폴더를 가리켜야 합니다.
|
||||
|
||||
### uv.lock 또는 poetry.lock 누락
|
||||
|
||||
선택한 프로젝트 폴더 또는 저장소 루트에 lock 파일을 커밋하세요. UV
|
||||
워크스페이스의 경우 `uv.lock`을 워크스페이스 루트에 두는 방식이 지원됩니다.
|
||||
|
||||
### Auto-Deploy를 사용할 수 없음
|
||||
|
||||
작업 디렉터리가 설정되어 있으면 auto-deploy가 비활성화됩니다. 수동 재배포를
|
||||
사용하거나 AMP API로 CI/CD에서 재배포를 트리거하세요.
|
||||
|
||||
<Card title="AMP에 배포하기" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
모노레포 작업 디렉터리를 선택한 뒤 배포 가이드를 계속 진행하세요.
|
||||
</Card>
|
||||
68
docs/edge/ko/enterprise/guides/onedrive-trigger.mdx
Normal file
68
docs/edge/ko/enterprise/guides/onedrive-trigger.mdx
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: "OneDrive Trigger"
|
||||
description: "Automate responses to OneDrive file activity"
|
||||
icon: "cloud"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata.
|
||||
|
||||
<Tip>
|
||||
Connect OneDrive in **Tools & Integrations** and toggle the trigger on for
|
||||
your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the OneDrive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **OneDrive** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft OneDrive trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/onedrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Audit file permissions
|
||||
|
||||
```python
|
||||
from onedrive_file_crew import OneDriveFileTrigger
|
||||
|
||||
crew = OneDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": onedrive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary.
|
||||
|
||||
## 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 OneDrive 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 OneDrive 트리거 시뮬레이션
|
||||
crewai triggers run microsoft_onedrive/file_changed
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 OneDrive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run microsoft_onedrive/file_changed`를 사용하세요
|
||||
(`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Ensure the connected account has permission to read the file metadata included in the webhook
|
||||
- `crewai triggers run microsoft_onedrive/file_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field
|
||||
- For large tenants, filter notifications upstream so the crew only runs on relevant directories
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
69
docs/edge/ko/enterprise/guides/outlook-trigger.mdx
Normal file
69
docs/edge/ko/enterprise/guides/outlook-trigger.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Outlook Trigger"
|
||||
description: "Launch automations from Outlook emails and calendar updates"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations.
|
||||
|
||||
<Tip>
|
||||
Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled
|
||||
for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Outlook Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Outlook** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft Outlook trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/outlook-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize a new email
|
||||
|
||||
```python
|
||||
from outlook_message_crew import OutlookMessageTrigger
|
||||
|
||||
crew = OutlookMessageTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": outlook_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew extracts sender details, subject, body preview, and attachments before generating a structured response.
|
||||
|
||||
## 로컬에서 테스트
|
||||
|
||||
CrewAI CLI를 사용하여 Outlook 트리거 통합을 로컬에서 테스트하세요:
|
||||
|
||||
```bash
|
||||
# 사용 가능한 모든 트리거 보기
|
||||
crewai triggers list
|
||||
|
||||
# 실제 payload로 Outlook 트리거 시뮬레이션
|
||||
crewai triggers run microsoft_outlook/email_received
|
||||
```
|
||||
|
||||
`crewai triggers run` 명령은 완전한 Outlook payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다.
|
||||
|
||||
<Warning>
|
||||
개발 중에는 `crewai triggers run microsoft_outlook/email_received`를
|
||||
사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를
|
||||
받습니다.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Verify the Outlook connector is still authorized; the subscription must be renewed periodically
|
||||
- `crewai triggers run microsoft_outlook/email_received`로 로컬 테스트하여 정확한 payload 구조를 확인하세요
|
||||
- If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag
|
||||
- Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that
|
||||
- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님)
|
||||
342
docs/edge/ko/enterprise/guides/prepare-for-deployment.mdx
Normal file
342
docs/edge/ko/enterprise/guides/prepare-for-deployment.mdx
Normal file
@@ -0,0 +1,342 @@
|
||||
---
|
||||
title: "배포 준비하기"
|
||||
description: "Crew 또는 Flow가 CrewAI AMP에 배포될 준비가 되었는지 확인하기"
|
||||
icon: "clipboard-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다.
|
||||
Crews와 Flows 모두 "자동화"로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는
|
||||
서로 다른 프로젝트 구조와 요구 사항이 있습니다.
|
||||
</Note>
|
||||
|
||||
## 자동화 이해하기
|
||||
|
||||
CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다:
|
||||
|
||||
- **Crew**: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀
|
||||
- **Flow**: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우
|
||||
|
||||
배포하는 유형을 이해하는 것은 프로젝트 구조와 진입점이 다르기 때문에 필수적입니다.
|
||||
|
||||
## Crews vs Flows: 주요 차이점
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Crew 프로젝트" icon="users">
|
||||
독립 실행형 AI 에이전트 팀입니다. 새 crew는 `crew.jsonc`와 `agents/`를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 `crew.py`를 사용할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="Flow 프로젝트" icon="diagram-project">
|
||||
`crews/` 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
| 측면 | Crew | Flow |
|
||||
|------|------|------|
|
||||
| **프로젝트 구조** | 프로젝트 루트의 `crew.jsonc`와 `agents/` | `crews/` 폴더가 있는 `src/project_name/` |
|
||||
| **메인 로직 위치** | `crew.jsonc` (클래식: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow 클래스) |
|
||||
| **진입점 함수** | `crew.jsonc`에서 로드됨 (클래식: `main.py`의 `run()`) | `main.py`의 `kickoff()` |
|
||||
| **pyproject.toml 타입** | `type = "crew"` | `type = "flow"` |
|
||||
| **CLI 생성 명령어** | `crewai create crew name` | `crewai create flow name` |
|
||||
| **설정 위치** | `crew.jsonc`, `agents/`, 선택적 `tools/` | `src/project_name/crews/crew_name/config/` 또는 포함된 JSON crew 폴더 |
|
||||
| **다른 crew 포함 가능** | 아니오 | 예 (`crews/` 폴더 내) |
|
||||
|
||||
## 프로젝트 구조 참조
|
||||
|
||||
### Crew 프로젝트 구조
|
||||
|
||||
`crewai create crew my_crew`를 실행하면 JSON-first 구조를 얻습니다:
|
||||
|
||||
```
|
||||
my_crew/
|
||||
├── .gitignore
|
||||
├── pyproject.toml # type = "crew"여야 함
|
||||
├── README.md
|
||||
├── .env
|
||||
├── uv.lock # 배포에 필수
|
||||
├── crew.jsonc # Crew 설정, 태스크, 프로세스, 입력
|
||||
├── agents/
|
||||
│ └── researcher.jsonc # 에이전트 정의
|
||||
├── tools/ # 선택적 custom:<name> 도구
|
||||
├── knowledge/
|
||||
└── skills/
|
||||
```
|
||||
|
||||
<Warning>
|
||||
JSON-first crew에서는 `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, `skills/`를
|
||||
프로젝트 루트에 두세요. 이를 `src/` 아래에 두면 `crewai run`과 배포 검증이 crew 정의를 찾지 못합니다.
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
`crewai create crew my_crew --classic`으로 만든 클래식 프로젝트는 기존
|
||||
`src/project_name/crew.py`, `src/project_name/config/agents.yaml`,
|
||||
`src/project_name/config/tasks.yaml` 구조를 사용합니다. 이 구조는 decorator 기반 Python crew를 위해 계속 지원됩니다.
|
||||
</Info>
|
||||
|
||||
### Flow 프로젝트 구조
|
||||
|
||||
`crewai create flow my_flow`를 실행하면 다음 구조를 얻습니다:
|
||||
|
||||
```
|
||||
my_flow/
|
||||
├── .gitignore
|
||||
├── pyproject.toml # type = "flow"여야 함
|
||||
├── README.md
|
||||
├── .env
|
||||
├── uv.lock # 배포에 필수
|
||||
└── src/
|
||||
└── my_flow/
|
||||
├── __init__.py
|
||||
├── main.py # kickoff() 함수 + Flow 클래스가 있는 진입점
|
||||
├── crews/ # 포함된 crews 폴더
|
||||
│ └── poem_crew/
|
||||
│ ├── __init__.py
|
||||
│ ├── poem_crew.py # @CrewBase 데코레이터가 있는 Crew
|
||||
│ └── config/
|
||||
│ ├── agents.yaml
|
||||
│ └── tasks.yaml
|
||||
└── tools/
|
||||
├── __init__.py
|
||||
└── custom_tool.py
|
||||
```
|
||||
|
||||
<Info>
|
||||
JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다.
|
||||
Flow는 여전히 `src/project_name/`을 사용하며, 클래식 포함 crew나
|
||||
`crewai.project.load_crew`로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다.
|
||||
</Info>
|
||||
|
||||
## 배포 전 체크리스트
|
||||
|
||||
이 체크리스트를 사용하여 프로젝트가 배포 준비가 되었는지 확인하세요.
|
||||
|
||||
### 1. pyproject.toml 설정 확인
|
||||
|
||||
`pyproject.toml`에 올바른 `[tool.crewai]` 섹션이 포함되어야 합니다:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Crews의 경우">
|
||||
```toml
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Flows의 경우">
|
||||
```toml
|
||||
[tool.crewai]
|
||||
type = "flow"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
`type`이 프로젝트 구조와 일치하지 않으면 빌드가 실패하거나
|
||||
자동화가 올바르게 실행되지 않습니다.
|
||||
</Warning>
|
||||
|
||||
### 2. uv.lock 파일 존재 확인
|
||||
|
||||
CrewAI는 의존성 관리를 위해 `uv`를 사용합니다. `uv.lock` 파일은 재현 가능한 빌드를 보장하며 배포에 **필수**입니다.
|
||||
|
||||
```bash
|
||||
# lock 파일 생성 또는 업데이트
|
||||
uv lock
|
||||
|
||||
# 존재 여부 확인
|
||||
ls -la uv.lock
|
||||
```
|
||||
|
||||
파일이 존재하지 않으면 `uv lock`을 실행하고 저장소에 커밋하세요:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
git add uv.lock
|
||||
git commit -m "Add uv.lock for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
### 3. Crew 정의 검증
|
||||
|
||||
<Tabs>
|
||||
<Tab title="JSON-first Crews">
|
||||
JSON-first crew는 프로젝트 루트에 `crew.jsonc` 또는 `crew.json` 파일이 있어야 합니다.
|
||||
`agents` 배열은 `agents/` 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Research Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research_task",
|
||||
"description": "Research {topic}.",
|
||||
"expected_output": "A concise report.",
|
||||
"agent": "researcher"
|
||||
}
|
||||
],
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
커스텀 도구는 `"custom:<name>"`으로 참조하며, `tools/<name>.py`에 `BaseTool` 서브클래스로 구현해야 합니다.
|
||||
</Tab>
|
||||
<Tab title="클래식 Python/YAML Crews">
|
||||
클래식 crew와 Flow 안에 포함된 Python crew는 `@CrewBase` 데코레이터를 사용해야 합니다.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class MyCrew():
|
||||
"""내 crew 설명"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def my_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['my_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 4. 프로젝트 진입점 확인
|
||||
|
||||
JSON-first 독립 실행형 crew는 직접 작성한 `src/project_name/main.py`가 필요하지 않습니다.
|
||||
`crewai run`과 배포 패키징이 `crew.jsonc`를 직접 로드합니다. 클래식 crew와 Flow는 Python 진입점을 사용합니다:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="JSON-first Crews">
|
||||
프로젝트 루트에서 로컬 실행합니다:
|
||||
|
||||
```bash
|
||||
crewai run
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="클래식 Crews">
|
||||
진입점은 `run()` 함수를 사용합니다:
|
||||
|
||||
```python
|
||||
# src/my_crew/main.py
|
||||
from my_crew.crew import MyCrew
|
||||
|
||||
def run():
|
||||
"""crew를 실행합니다."""
|
||||
inputs = {'topic': 'AI in Healthcare'}
|
||||
result = MyCrew().crew().kickoff(inputs=inputs)
|
||||
return result
|
||||
|
||||
if __name__ == "__main__":
|
||||
run()
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Flows의 경우">
|
||||
진입점은 Flow 클래스와 함께 `kickoff()` 함수를 사용합니다:
|
||||
|
||||
```python
|
||||
# src/my_flow/main.py
|
||||
from crewai.flow import Flow, listen, start
|
||||
from my_flow.crews.poem_crew.poem_crew import PoemCrew
|
||||
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
def begin(self):
|
||||
# Flow 로직
|
||||
result = PoemCrew().crew().kickoff(inputs={...})
|
||||
return result
|
||||
|
||||
def kickoff():
|
||||
"""flow를 실행합니다."""
|
||||
MyFlow().kickoff()
|
||||
|
||||
if __name__ == "__main__":
|
||||
kickoff()
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 5. 환경 변수 준비
|
||||
|
||||
배포 전에 다음을 준비해야 합니다:
|
||||
|
||||
1. **LLM API 키** (OpenAI, Anthropic, Google 등)
|
||||
2. **도구 API 키** - 외부 도구를 사용하는 경우 (Serper 등)
|
||||
|
||||
<Info>
|
||||
프로젝트가 **프라이빗 PyPI 레지스트리**의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도
|
||||
환경 변수로 구성해야 합니다. 자세한 내용은
|
||||
[프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry) 가이드를 참조하세요.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
구성 문제를 조기에 발견하기 위해 배포 전에 동일한 환경 변수로
|
||||
로컬에서 프로젝트를 테스트하세요.
|
||||
</Tip>
|
||||
|
||||
## 빠른 검증 명령어
|
||||
|
||||
프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요:
|
||||
|
||||
```bash
|
||||
# 1. pyproject.toml에서 프로젝트 타입 확인
|
||||
grep -A2 "\[tool.crewai\]" pyproject.toml
|
||||
|
||||
# 2. uv.lock 존재 확인
|
||||
ls -la uv.lock || echo "오류: uv.lock이 없습니다! 'uv lock'을 실행하세요"
|
||||
|
||||
# 3. JSON-first crew의 경우 crew.jsonc와 agents/ 확인
|
||||
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "crew.jsonc 또는 crew.json을 찾을 수 없습니다"
|
||||
test -d agents || echo "agents/ 디렉터리를 찾을 수 없습니다"
|
||||
|
||||
# 4. 클래식 Crews의 경우 - crew.py 존재 확인
|
||||
ls -la src/*/crew.py 2>/dev/null || echo "crew.py가 없습니다 (Crews에서 예상됨)"
|
||||
|
||||
# 5. Flows의 경우 - crews/ 폴더 존재 확인
|
||||
ls -la src/*/crews/ 2>/dev/null || echo "crews/ 폴더가 없습니다 (Flows에서 예상됨)"
|
||||
|
||||
# 6. 클래식 Python crews의 경우 - CrewBase 사용 확인
|
||||
grep -r "@CrewBase" . --include="*.py"
|
||||
```
|
||||
|
||||
## 일반적인 설정 실수
|
||||
|
||||
| 실수 | 증상 | 해결 방법 |
|
||||
|------|------|----------|
|
||||
| `uv.lock` 누락 | 의존성 해결 중 빌드 실패 | `uv lock` 실행 후 커밋 |
|
||||
| pyproject.toml의 잘못된 `type` | 빌드 성공하지만 런타임 실패 | 올바른 타입으로 변경 |
|
||||
| JSON-first crew에서 `crew.jsonc` 또는 `agents/` 누락 | Crew 정의를 찾을 수 없음 | `crew.jsonc`와 `agents/`를 프로젝트 루트에 둠 |
|
||||
| 클래식 crew에서 `@CrewBase` 데코레이터 누락 | "Config not found" 오류 | 모든 클래식 crew 클래스에 데코레이터 추가 |
|
||||
| 클래식 파일을 `src/` 대신 루트에 배치 | 진입점을 찾을 수 없음 | 클래식 Python 파일을 `src/project_name/`으로 이동 |
|
||||
| `run()` 또는 `kickoff()` 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 |
|
||||
|
||||
## 다음 단계
|
||||
|
||||
프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다:
|
||||
|
||||
<Card title="AMP에 배포하기" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에
|
||||
배포하려면 배포 가이드를 따르세요.
|
||||
</Card>
|
||||
261
docs/edge/ko/enterprise/guides/private-package-registry.mdx
Normal file
261
docs/edge/ko/enterprise/guides/private-package-registry.mdx
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: "프라이빗 패키지 레지스트리"
|
||||
description: "CrewAI AMP에서 인증된 PyPI 레지스트리의 프라이빗 Python 패키지 설치하기"
|
||||
icon: "lock"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
이 가이드는 CrewAI AMP에 배포할 때 프라이빗 PyPI 레지스트리(Azure DevOps Artifacts, GitHub Packages,
|
||||
GitLab, AWS CodeArtifact 등)에서 Python 패키지를 설치하도록 CrewAI 프로젝트를 구성하는 방법을 다룹니다.
|
||||
</Note>
|
||||
|
||||
## 이 가이드가 필요한 경우
|
||||
|
||||
프로젝트가 공개 PyPI가 아닌 프라이빗 레지스트리에 호스팅된 내부 또는 독점 Python 패키지에
|
||||
의존하는 경우, 다음을 수행해야 합니다:
|
||||
|
||||
1. UV에 패키지를 **어디서** 찾을지 알려줍니다 (index URL)
|
||||
2. UV에 **어떤** 패키지가 해당 index에서 오는지 알려줍니다 (source 매핑)
|
||||
3. UV가 설치 중에 인증할 수 있도록 **자격 증명**을 제공합니다
|
||||
|
||||
CrewAI AMP는 의존성 해결 및 설치에 [UV](https://docs.astral.sh/uv/)를 사용합니다.
|
||||
UV는 `pyproject.toml` 구성과 자격 증명용 환경 변수를 결합하여 인증된 프라이빗 레지스트리를 지원합니다.
|
||||
|
||||
## 1단계: pyproject.toml 구성
|
||||
|
||||
`pyproject.toml`에서 세 가지 요소가 함께 작동합니다:
|
||||
|
||||
### 1a. 의존성 선언
|
||||
|
||||
프라이빗 패키지를 다른 의존성과 마찬가지로 `[project.dependencies]`에 추가합니다:
|
||||
|
||||
```toml
|
||||
[project]
|
||||
dependencies = [
|
||||
"crewai[tools]>=0.100.1,<1.0.0",
|
||||
"my-private-package>=1.2.0",
|
||||
]
|
||||
```
|
||||
|
||||
### 1b. index 정의
|
||||
|
||||
프라이빗 레지스트리를 `[[tool.uv.index]]` 아래에 명명된 index로 등록합니다:
|
||||
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "my-private-registry"
|
||||
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
|
||||
explicit = true
|
||||
```
|
||||
|
||||
<Info>
|
||||
`name` 필드는 중요합니다 — UV는 이를 사용하여 인증을 위한 환경 변수 이름을
|
||||
구성합니다 (아래 [2단계](#2단계-인증-자격-증명-설정)를 참조하세요).
|
||||
|
||||
`explicit = true`를 설정하면 UV가 모든 패키지에 대해 이 index를 검색하지 않습니다 —
|
||||
`[tool.uv.sources]`에서 명시적으로 매핑한 패키지만 검색합니다. 이렇게 하면 프라이빗
|
||||
레지스트리에 대한 불필요한 쿼리를 방지하고 의존성 혼동 공격을 차단할 수 있습니다.
|
||||
</Info>
|
||||
|
||||
### 1c. 패키지를 index에 매핑
|
||||
|
||||
`[tool.uv.sources]`를 사용하여 프라이빗 index에서 해결해야 할 패키지를 UV에 알려줍니다:
|
||||
|
||||
```toml
|
||||
[tool.uv.sources]
|
||||
my-private-package = { index = "my-private-registry" }
|
||||
```
|
||||
|
||||
### 전체 예시
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "my-crew-project"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.10,<=3.13"
|
||||
dependencies = [
|
||||
"crewai[tools]>=0.100.1,<1.0.0",
|
||||
"my-private-package>=1.2.0",
|
||||
]
|
||||
|
||||
[tool.crewai]
|
||||
type = "crew"
|
||||
|
||||
[[tool.uv.index]]
|
||||
name = "my-private-registry"
|
||||
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
my-private-package = { index = "my-private-registry" }
|
||||
```
|
||||
|
||||
`pyproject.toml`을 업데이트한 후 lock 파일을 다시 생성합니다:
|
||||
|
||||
```bash
|
||||
uv lock
|
||||
```
|
||||
|
||||
<Warning>
|
||||
업데이트된 `uv.lock`을 항상 `pyproject.toml` 변경 사항과 함께 커밋하세요.
|
||||
lock 파일은 배포에 필수입니다 — [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.
|
||||
</Warning>
|
||||
|
||||
## 2단계: 인증 자격 증명 설정
|
||||
|
||||
UV는 `pyproject.toml`에서 정의한 index 이름을 기반으로 한 명명 규칙을 따르는
|
||||
환경 변수를 사용하여 프라이빗 index에 인증합니다:
|
||||
|
||||
```
|
||||
UV_INDEX_{UPPER_NAME}_USERNAME
|
||||
UV_INDEX_{UPPER_NAME}_PASSWORD
|
||||
```
|
||||
|
||||
여기서 `{UPPER_NAME}`은 index 이름을 **대문자**로 변환하고 **하이픈을 언더스코어로 대체**한 것입니다.
|
||||
|
||||
예를 들어, `my-private-registry`라는 이름의 index는 다음을 사용합니다:
|
||||
|
||||
| 변수 | 값 |
|
||||
|------|-----|
|
||||
| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | 레지스트리 사용자 이름 또는 토큰 이름 |
|
||||
| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | 레지스트리 비밀번호 또는 토큰/PAT |
|
||||
|
||||
<Warning>
|
||||
이 환경 변수는 CrewAI AMP **환경 변수** 설정을 통해 **반드시** 추가해야 합니다 —
|
||||
전역적으로 또는 배포 수준에서. `.env` 파일에 설정하거나 프로젝트에 하드코딩할 수 없습니다.
|
||||
|
||||
아래 [AMP에서 환경 변수 설정](#amp에서-환경-변수-설정)을 참조하세요.
|
||||
</Warning>
|
||||
|
||||
## 레지스트리 제공업체 참조
|
||||
|
||||
아래 표는 일반적인 레지스트리 제공업체의 index URL 형식과 자격 증명 값을 보여줍니다.
|
||||
자리 표시자 값을 실제 조직 및 피드 세부 정보로 대체하세요.
|
||||
|
||||
| 제공업체 | Index URL | 사용자 이름 | 비밀번호 |
|
||||
|---------|-----------|-----------|---------|
|
||||
| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | 비어 있지 않은 임의의 문자열 (예: `token`) | Packaging Read 범위의 Personal Access Token (PAT) |
|
||||
| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | GitHub 사용자 이름 | `read:packages` 범위의 Personal Access Token (classic) |
|
||||
| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | `read_api` 범위의 Project 또는 Personal Access Token |
|
||||
| **AWS CodeArtifact** | `aws codeartifact get-repository-endpoint`의 URL 사용 | `aws` | `aws codeartifact get-authorization-token`의 토큰 |
|
||||
| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Base64로 인코딩된 서비스 계정 키 |
|
||||
| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | 사용자 이름 또는 이메일 | API 키 또는 ID 토큰 |
|
||||
| **자체 호스팅 (devpi, Nexus 등)** | 레지스트리의 simple API URL | 레지스트리 사용자 이름 | 레지스트리 비밀번호 |
|
||||
|
||||
<Tip>
|
||||
**AWS CodeArtifact**의 경우 인증 토큰이 주기적으로 만료됩니다.
|
||||
만료되면 `UV_INDEX_*_PASSWORD` 값을 갱신해야 합니다.
|
||||
CI/CD 파이프라인에서 이를 자동화하는 것을 고려하세요.
|
||||
</Tip>
|
||||
|
||||
## AMP에서 환경 변수 설정
|
||||
|
||||
프라이빗 레지스트리 자격 증명은 CrewAI AMP에서 환경 변수로 구성해야 합니다.
|
||||
두 가지 옵션이 있습니다:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="웹 인터페이스">
|
||||
1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다
|
||||
2. 자동화로 이동합니다
|
||||
3. **Environment Variables** 탭을 엽니다
|
||||
4. 각 변수 (`UV_INDEX_*_USERNAME` 및 `UV_INDEX_*_PASSWORD`)에 값을 추가합니다
|
||||
|
||||
자세한 내용은 [AMP에 배포하기 — 환경 변수 설정하기](/ko/enterprise/guides/deploy-to-amp#환경-변수-설정하기) 단계를 참조하세요.
|
||||
</Tab>
|
||||
<Tab title="CLI 배포">
|
||||
`crewai deploy create`를 실행하기 전에 로컬 `.env` 파일에 변수를 추가합니다.
|
||||
CLI가 이를 안전하게 플랫폼으로 전송합니다:
|
||||
|
||||
```bash
|
||||
# .env
|
||||
OPENAI_API_KEY=sk-...
|
||||
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
|
||||
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
|
||||
```
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
자격 증명을 저장소에 **절대** 커밋하지 마세요. 모든 비밀 정보에는 AMP 환경 변수를 사용하세요.
|
||||
`.env` 파일은 `.gitignore`에 포함되어야 합니다.
|
||||
</Warning>
|
||||
|
||||
기존 배포의 자격 증명을 업데이트하려면 [Crew 업데이트하기 — 환경 변수](/ko/enterprise/guides/update-crew)를 참조하세요.
|
||||
|
||||
## 전체 동작 흐름
|
||||
|
||||
CrewAI AMP가 자동화를 빌드할 때, 해결 흐름은 다음과 같이 작동합니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="빌드 시작">
|
||||
AMP가 저장소를 가져오고 `pyproject.toml`과 `uv.lock`을 읽습니다.
|
||||
</Step>
|
||||
<Step title="UV가 의존성 해결">
|
||||
UV가 `[tool.uv.sources]`를 읽어 각 패키지가 어떤 index에서 와야 하는지 결정합니다.
|
||||
</Step>
|
||||
<Step title="UV가 인증">
|
||||
각 프라이빗 index에 대해 UV가 AMP에서 구성한 환경 변수에서
|
||||
`UV_INDEX_{NAME}_USERNAME`과 `UV_INDEX_{NAME}_PASSWORD`를 조회합니다.
|
||||
</Step>
|
||||
<Step title="패키지 설치">
|
||||
UV가 공개(PyPI) 및 프라이빗(레지스트리) 패키지를 모두 다운로드하고 설치합니다.
|
||||
</Step>
|
||||
<Step title="자동화 실행">
|
||||
모든 의존성이 사용 가능한 상태에서 crew 또는 flow가 시작됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 빌드 중 인증 오류
|
||||
|
||||
**증상**: 프라이빗 패키지를 해결할 때 `401 Unauthorized` 또는 `403 Forbidden`으로 빌드가 실패합니다.
|
||||
|
||||
**확인사항**:
|
||||
- `UV_INDEX_*` 환경 변수 이름이 index 이름과 정확히 일치하는지 확인합니다 (대문자, 하이픈 -> 언더스코어)
|
||||
- 자격 증명이 로컬 `.env`뿐만 아니라 AMP 환경 변수에 설정되어 있는지 확인합니다
|
||||
- 토큰/PAT에 패키지 피드에 필요한 읽기 권한이 있는지 확인합니다
|
||||
- 토큰이 만료되지 않았는지 확인합니다 (특히 AWS CodeArtifact의 경우)
|
||||
|
||||
### 패키지를 찾을 수 없음
|
||||
|
||||
**증상**: `No matching distribution found for my-private-package`.
|
||||
|
||||
**확인사항**:
|
||||
- `pyproject.toml`의 index URL이 `/simple/`로 끝나는지 확인합니다
|
||||
- `[tool.uv.sources]` 항목이 올바른 패키지 이름을 올바른 index 이름에 매핑하는지 확인합니다
|
||||
- 패키지가 실제로 프라이빗 레지스트리에 게시되어 있는지 확인합니다
|
||||
- 동일한 자격 증명으로 로컬에서 `uv lock`을 실행하여 해결이 작동하는지 확인합니다
|
||||
|
||||
### Lock 파일 충돌
|
||||
|
||||
**증상**: 프라이빗 index를 추가한 후 `uv lock`이 실패하거나 예상치 못한 결과를 생성합니다.
|
||||
|
||||
**해결책**: 로컬에서 자격 증명을 설정하고 다시 생성합니다:
|
||||
|
||||
```bash
|
||||
export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
|
||||
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
|
||||
uv lock
|
||||
```
|
||||
|
||||
그런 다음 업데이트된 `uv.lock`을 커밋합니다.
|
||||
|
||||
## 관련 가이드
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="배포 준비하기" icon="clipboard-check" href="/ko/enterprise/guides/prepare-for-deployment">
|
||||
배포 전에 프로젝트 구조와 의존성을 확인합니다.
|
||||
</Card>
|
||||
<Card title="AMP에 배포하기" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
crew 또는 flow를 배포하고 환경 변수를 구성합니다.
|
||||
</Card>
|
||||
<Card title="Crew 업데이트하기" icon="arrows-rotate" href="/ko/enterprise/guides/update-crew">
|
||||
환경 변수를 업데이트하고 실행 중인 배포에 변경 사항을 푸시합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
112
docs/edge/ko/enterprise/guides/react-component-export.mdx
Normal file
112
docs/edge/ko/enterprise/guides/react-component-export.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "React 컴포넌트 내보내기"
|
||||
description: "CrewAI AMP React 컴포넌트를 애플리케이션에 내보내고 통합하는 방법을 알아보세요"
|
||||
icon: "react"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이 가이드는 CrewAI AMP crew를 React 컴포넌트로 내보내고 이를 여러분의 애플리케이션에 통합하는 방법을 설명합니다.
|
||||
|
||||
## React 컴포넌트 내보내기
|
||||
|
||||
<Steps>
|
||||
<Step title="컴포넌트 내보내기">
|
||||
배포된 crew 오른쪽에 있는 줄임표(세 개의 점)를 클릭한 다음 내보내기 옵션을 선택하고 파일을 로컬에 저장하세요. 본 예시에서는 `CrewLead.jsx`를 사용합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/export-react-component.png" alt="React 컴포넌트 내보내기" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 리액트 환경 설정
|
||||
|
||||
이 리액트 컴포넌트를 로컬에서 실행하려면 리액트 개발 환경을 설정하고 이 컴포넌트를 리액트 프로젝트에 통합해야 합니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="Node.js 설치">
|
||||
- 공식 웹사이트(https://nodejs.org/)에서 Node.js를 다운로드하고 설치하세요.
|
||||
- 안정성을 위해 LTS(장기 지원) 버전을 선택하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="새 리액트 프로젝트 생성">
|
||||
- 명령 프롬프트 또는 PowerShell을 엽니다.
|
||||
- 프로젝트를 생성하고자 하는 디렉터리로 이동하세요.
|
||||
- 다음 명령어를 실행하여 새로운 리액트 프로젝트를 생성합니다:
|
||||
|
||||
```bash
|
||||
npx create-react-app my-crew-app
|
||||
```
|
||||
- 프로젝트 디렉터리로 이동합니다:
|
||||
|
||||
```bash
|
||||
cd my-crew-app
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="필요한 의존성 설치">
|
||||
```bash
|
||||
npm install react-dom
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="CrewLead 컴포넌트 생성">
|
||||
- 다운로드한 파일 `CrewLead.jsx`를 프로젝트의 `src` 폴더로 이동하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="App.js를 수정하여 CrewLead 컴포넌트 사용">
|
||||
- `src/App.js`를 엽니다.
|
||||
- 내용물을 아래와 같이 교체하세요:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
import CrewLead from './CrewLead';
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<div className="App">
|
||||
<CrewLead baseUrl="YOUR_API_BASE_URL" bearerToken="YOUR_BEARER_TOKEN" />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export default App;
|
||||
```
|
||||
- `YOUR_API_BASE_URL` 및 `YOUR_BEARER_TOKEN` 부분을 실제 API 값으로 바꿔주세요.
|
||||
</Step>
|
||||
|
||||
<Step title="개발 서버 시작">
|
||||
- 프로젝트 디렉터리에서 다음 명령어를 실행하세요:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
- 개발 서버가 시작되며, 기본 웹 브라우저가 자동으로 http://localhost:3000 을 열고 리액트 앱이 실행되는 것을 확인할 수 있습니다.
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 커스터마이징
|
||||
|
||||
그런 다음 `CrewLead.jsx`를 커스터마이즈하여 색상, 제목 등을 추가할 수 있습니다.
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/customise-react-component.png"
|
||||
alt="React 컴포넌트 커스터마이즈"
|
||||
/>
|
||||
</Frame>
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/customise-react-component-2.png"
|
||||
alt="React 컴포넌트 커스터마이즈"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- 구성 요소 스타일을 애플리케이션 디자인에 맞게 맞춤화하세요
|
||||
- 추가 구성을 위한 props를 추가하세요
|
||||
- 애플리케이션의 상태 관리와 통합하세요
|
||||
- 오류 처리 및 로딩 상태를 추가하세요
|
||||
50
docs/edge/ko/enterprise/guides/salesforce-trigger.mdx
Normal file
50
docs/edge/ko/enterprise/guides/salesforce-trigger.mdx
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Salesforce 트리거"
|
||||
description: "Salesforce 워크플로우에서 CrewAI crew를 트리거하여 CRM 자동화"
|
||||
icon: "salesforce"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AOP는 Salesforce에서 트리거되어 고객 관계 관리 워크플로우를 자동화하고 영업 운영을 강화할 수 있습니다.
|
||||
|
||||
## 개요
|
||||
|
||||
Salesforce는 기업이 영업, 서비스, 마케팅 운영을 효율화할 수 있도록 돕는 선도적인 고객 관계 관리(CRM) 플랫폼입니다. Salesforce에서 CrewAI 트리거를 설정하면 다음과 같은 작업을 수행할 수 있습니다:
|
||||
|
||||
- 리드 점수 산정 및 자격 심사 자동화
|
||||
- 개인화된 영업 자료 생성
|
||||
- AI 기반 응답으로 고객 서비스 강화
|
||||
- 데이터 분석 및 보고 간소화
|
||||
|
||||
## 데모
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/oJunVqjjfu4"
|
||||
title="CrewAI + Salesforce trigger demo"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
## 시작하기
|
||||
|
||||
Salesforce 트리거를 설정하려면:
|
||||
|
||||
1. **지원팀 문의**: Salesforce 트리거 설정을 위해 CrewAI AMP 지원팀에 연락하세요.
|
||||
2. **요구 사항 검토**: 필요한 Salesforce 권한과 API 액세스 권한이 있는지 확인하세요.
|
||||
3. **연결 구성**: 지원팀과 협력하여 CrewAI와 귀하의 Salesforce 인스턴스 간의 연결을 설정하세요.
|
||||
4. **트리거 테스트**: 트리거가 귀하의 특정 사용 사례에 맞게 올바르게 작동하는지 확인하세요.
|
||||
|
||||
## 사용 사례
|
||||
|
||||
일반적인 Salesforce + CrewAI 트리거 시나리오는 다음과 같습니다:
|
||||
|
||||
- **Lead 처리**: 들어오는 리드를 자동으로 분석하고 점수화
|
||||
- **제안서 생성**: 기회 데이터를 기반으로 맞춤형 제안서 생성
|
||||
- **고객 인사이트**: 고객 상호작용 이력에서 분석 보고서 생성
|
||||
- **후속 조치 자동화**: 개인화된 후속 메시지 및 추천 생성
|
||||
|
||||
## 다음 단계
|
||||
|
||||
자세한 설정 지침 및 고급 구성 옵션에 대해서는 CrewAI AMP 지원팀에 문의해 주시기 바랍니다. 지원팀은 귀하의 특정 Salesforce 환경과 비즈니스 요구에 맞는 맞춤형 안내를 제공해 드릴 수 있습니다.
|
||||
62
docs/edge/ko/enterprise/guides/slack-trigger.mdx
Normal file
62
docs/edge/ko/enterprise/guides/slack-trigger.mdx
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: "Slack 트리거"
|
||||
description: "슬래시 명령어를 사용해 Slack에서 CrewAI crew를 직접 트리거합니다"
|
||||
icon: "slack"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이 가이드는 CrewAI 트리거를 사용하여 Slack에서 직접 crew를 시작하는 방법을 설명합니다.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
- CrewAI Slack 트리거가 설치되어 있고 Slack 워크스페이스에 연결되어 있음
|
||||
- CrewAI에서 하나 이상의 crew가 구성되어 있음
|
||||
|
||||
## 설정 단계
|
||||
|
||||
<Steps>
|
||||
<Step title="CrewAI Slack 트리거가 설정되어 있는지 확인">
|
||||
CrewAI 대시보드에서 **트리거** 섹션으로 이동합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/slack-integration.png" alt="CrewAI Slack Integration" />
|
||||
</Frame>
|
||||
|
||||
Slack이 나열되어 있고 연결되어 있는지 확인합니다.
|
||||
</Step>
|
||||
<Step title="Slack 채널을 엽니다">
|
||||
- crew를 시작하려는 채널로 이동합니다.
|
||||
- 슬래시 명령어 "**/kickoff**"를 입력하여 crew 시작 프로세스를 시작합니다.
|
||||
- 입력하는 동안 "**Kickoff crew**"가 나타나야 합니다:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/kickoff-slack-crew.png" alt="Kickoff crew" />
|
||||
</Frame>
|
||||
- Enter를 누르거나 "**Kickoff crew**" 옵션을 선택합니다. "**Kickoff an AI Crew**"라는 제목의 대화상자가 나타납니다.
|
||||
</Step>
|
||||
<Step title="시작할 crew를 선택합니다">
|
||||
- "**Select of the crews online:**"라는 드롭다운 메뉴에서 시작할 crew를 선택합니다.
|
||||
- 아래 예시에서는 "**prep-for-meeting**"이 선택되어 있습니다:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/kickoff-slack-crew-dropdown.png" alt="Kickoff crew dropdown" />
|
||||
</Frame>
|
||||
- crew에 입력값이 필요한 경우 "**Add Inputs**" 버튼을 클릭하여 입력값을 제공합니다.
|
||||
<Note>
|
||||
위 예시에서 "**Add Inputs**" 버튼이 보이지만 아직 클릭되지 않았습니다.
|
||||
</Note>
|
||||
</Step>
|
||||
<Step title="Kickoff을 클릭하고 crew가 완료될 때까지 기다립니다">
|
||||
- crew를 선택하고 필요한 입력값을 추가했다면, "**Kickoff**"를 클릭하여 crew를 시작합니다.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/kickoff-slack-crew-kickoff.png" alt="Kickoff crew" />
|
||||
</Frame>
|
||||
- crew가 실행을 시작하면 Slack 채널에서 결과를 확인할 수 있습니다.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/kickoff-slack-crew-results.png" alt="Kickoff crew results" />
|
||||
</Frame>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 팁
|
||||
|
||||
- Slack 워크스페이스에서 `/kickoff` 명령어를 사용할 수 있는 필요한 권한이 있는지 확인하세요.
|
||||
- 드롭다운에서 원하는 crew가 보이지 않는 경우, CrewAI에서 해당 crew가 올바르게 구성되어 있고 온라인 상태인지 확인하세요.
|
||||
88
docs/edge/ko/enterprise/guides/team-management.mdx
Normal file
88
docs/edge/ko/enterprise/guides/team-management.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "팀 관리"
|
||||
description: "CrewAI AMP 조직에서 팀원을 초대하고 관리하는 방법을 알아보세요"
|
||||
icon: "users"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AMP 계정의 관리자라면 새로운 팀원을 조직에 쉽게 초대할 수 있습니다. 이 안내서는 단계별로 프로세스를 안내합니다.
|
||||
|
||||
## 팀 멤버 초대하기
|
||||
|
||||
<Steps>
|
||||
<Step title="설정 페이지 접속">
|
||||
- CrewAI AMP 계정에 로그인합니다 - 대시보드 오른쪽 상단에 있는 기어
|
||||
아이콘(⚙️)을 찾습니다 - 기어 아이콘을 클릭하여 **설정** 페이지에 접속합니다:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/settings-page.png" alt="Settings Page" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="멤버 섹션으로 이동">
|
||||
- 설정 페이지에서 `Members` 탭이 보입니다 - `Members` 탭을 클릭하여 **멤버**
|
||||
페이지에 접속합니다:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/members-tab.png" alt="Members Tab" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="새 멤버 초대">
|
||||
- 멤버 섹션에서 현재 멤버 목록(본인 포함)을 확인할 수 있습니다 - `Email`
|
||||
입력 필드를 찾습니다 - 초대하고자 하는 사람의 이메일 주소를 입력합니다 -
|
||||
`Invite` 버튼을 클릭하여 초대장을 보냅니다
|
||||
</Step>
|
||||
<Step title="필요에 따라 반복">
|
||||
- 이 과정을 반복하여 여러 팀 멤버를 초대할 수 있습니다 - 초대한 각 멤버는
|
||||
조직에 가입할 수 있는 이메일 초대장을 받게 됩니다
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 역할 추가하기
|
||||
|
||||
플랫폼의 다양한 부분에 대한 접근 권한을 제어하기 위해 팀원들에게 역할을 추가할 수 있습니다.
|
||||
|
||||
<Steps>
|
||||
<Step title="설정 페이지 접근">
|
||||
- CrewAI AMP 계정에 로그인하세요 - 대시보드 오른쪽 상단에서 기어
|
||||
아이콘(⚙️)을 찾으세요 - 기어 아이콘을 클릭하여 **설정** 페이지에 접근하세요:
|
||||
<Frame>
|
||||
<img src="/images/enterprise/settings-page.png" alt="설정 페이지" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="멤버 섹션으로 이동">
|
||||
- 설정 페이지에서 `Roles` 탭을 확인할 수 있습니다 - `Roles` 탭을 클릭하여
|
||||
**Roles** 페이지로 이동하세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/roles-tab.png" alt="Roles 탭" />
|
||||
</Frame>
|
||||
- 새로운 역할을 추가하려면 `Add Role` 버튼을 클릭하세요. - 역할의
|
||||
세부 정보와 권한을 입력한 후 `Create Role` 버튼을 클릭하여 역할을
|
||||
생성하세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/add-role-modal.png" alt="Add Role 모달" />
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="멤버에게 역할 추가하기">
|
||||
- 멤버 섹션에서 현재 멤버(본인 포함) 목록을 확인할 수 있습니다
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/member-accepted-invitation.png"
|
||||
alt="멤버 초대 수락 완료"
|
||||
/>
|
||||
</Frame>
|
||||
- 멤버가 초대를 수락하면 역할을 추가할 수 있습니다. - 다시 `Roles`
|
||||
탭으로 이동하세요 - 역할을 추가할 멤버로 이동한 후 `Role` 열에서 드롭다운을
|
||||
클릭하세요 - 멤버에게 추가할 역할을 선택하세요 - `Update` 버튼을 클릭하여
|
||||
역할을 저장하세요
|
||||
<Frame>
|
||||
<img src="/images/enterprise/assign-role.png" alt="멤버에 역할 추가" />
|
||||
</Frame>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 중요 참고 사항
|
||||
|
||||
- **관리자 권한**: 관리자 권한이 있는 사용자만 새 멤버를 초대할 수 있습니다
|
||||
- **이메일 정확성**: 팀 멤버의 정확한 이메일 주소를 확인하세요
|
||||
- **초대 수락**: 초대된 멤버는 조직에 가입하기 위해 초대를 수락해야 합니다
|
||||
- **이메일 알림**: 팀 멤버에게 초대 이메일(스팸 폴더 포함)을 확인하도록 안내할 수 있습니다
|
||||
|
||||
이 단계들을 따르면 팀을 손쉽게 확장하고 CrewAI AMP 조직 내에서 더욱 효과적으로 협업할 수 있습니다.
|
||||
111
docs/edge/ko/enterprise/guides/tool-repository.mdx
Normal file
111
docs/edge/ko/enterprise/guides/tool-repository.mdx
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: 도구 저장소
|
||||
description: "도구 저장소를 사용하여 도구를 관리하기"
|
||||
icon: "toolbox"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
Tool Repository는 CrewAI 도구를 위한 패키지 관리자입니다. 사용자는 CrewAI crew와 flow에 통합되는 도구를 게시, 설치 및 관리할 수 있습니다.
|
||||
|
||||
도구는 다음과 같이 분류됩니다:
|
||||
|
||||
- **비공개**: 조직 내에서만 접근할 수 있습니다(기본값)
|
||||
- **공개**: `--public` 플래그로 게시하면 모든 CrewAI 사용자가 접근할 수 있습니다
|
||||
|
||||
이 저장소는 버전 관리 시스템이 아닙니다. 코드 변경 사항을 추적하고 협업을 활성화하려면 Git을 사용하십시오.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
Tool Repository를 사용하기 전에 다음이 준비되어 있어야 합니다:
|
||||
|
||||
- [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- [CrewAI CLI](/ko/concepts/cli#cli) 설치됨
|
||||
- uv>=0.5.0 이 설치되어 있어야 합니다. [업그레이드 방법](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv)을 참고하세요.
|
||||
- [Git](https://git-scm.com) 설치 및 구성 완료
|
||||
- CrewAI AMP 조직에서 도구를 게시하거나 설치할 수 있는 액세스 권한
|
||||
|
||||
## 도구 설치
|
||||
|
||||
도구를 설치하려면:
|
||||
|
||||
```bash
|
||||
crewai tool install <tool-name>
|
||||
```
|
||||
|
||||
이 명령은 도구를 설치하고 `pyproject.toml`에 추가합니다.
|
||||
|
||||
## 도구 생성 및 게시
|
||||
|
||||
새 도구 프로젝트를 생성하려면:
|
||||
|
||||
```bash
|
||||
crewai tool create <tool-name>
|
||||
```
|
||||
|
||||
이 명령은 로컬에 스캐폴딩된 도구 프로젝트를 생성합니다.
|
||||
|
||||
변경 사항을 적용한 후, Git 저장소를 초기화하고 코드를 커밋합니다:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial version"
|
||||
```
|
||||
|
||||
도구를 게시하려면:
|
||||
|
||||
```bash
|
||||
crewai tool publish
|
||||
```
|
||||
|
||||
기본적으로 도구는 비공개로 게시됩니다. 도구를 공개로 설정하려면:
|
||||
|
||||
```bash
|
||||
crewai tool publish --public
|
||||
```
|
||||
|
||||
도구 빌드에 대한 자세한 내용은 [나만의 도구 만들기](/ko/concepts/tools#creating-your-own-tools)를 참고하세요.
|
||||
|
||||
## 도구 업데이트
|
||||
|
||||
공개된 도구를 업데이트하려면:
|
||||
|
||||
1. 로컬에서 도구를 수정합니다.
|
||||
2. `pyproject.toml`에서 버전을 업데이트합니다(예: `0.1.0`에서 `0.1.1`로).
|
||||
3. 변경 사항을 커밋하고 배포합니다.
|
||||
|
||||
```bash
|
||||
git commit -m "Update version to 0.1.1"
|
||||
crewai tool publish
|
||||
```
|
||||
|
||||
## 도구 삭제
|
||||
|
||||
도구를 삭제하려면:
|
||||
|
||||
1. [CrewAI AMP](https://app.crewai.com)로 이동합니다.
|
||||
2. **Tools**로 이동합니다.
|
||||
3. 도구를 선택합니다.
|
||||
4. **Delete**를 클릭합니다.
|
||||
|
||||
<Warning>
|
||||
삭제는 영구적입니다. 삭제된 도구는 복구하거나 다시 설치할 수 없습니다.
|
||||
</Warning>
|
||||
|
||||
## 보안 점검
|
||||
|
||||
모든 공개된 버전은 자동화된 보안 점검을 거치며, 통과한 후에만 설치할 수 있습니다.
|
||||
|
||||
도구의 보안 점검 상태는 다음에서 확인할 수 있습니다:
|
||||
|
||||
`CrewAI AMP > Tools > Your Tool > Versions`
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
API 통합 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 문의해 주세요.
|
||||
</Card>
|
||||
132
docs/edge/ko/enterprise/guides/training-crews.mdx
Normal file
132
docs/edge/ko/enterprise/guides/training-crews.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: "Crew 훈련"
|
||||
description: "CrewAI AMP 플랫폼에서 직접 배포된 Crew를 훈련하여 시간이 지남에 따라 에이전트 성능을 개선하세요"
|
||||
icon: "dumbbell"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
훈련을 통해 CrewAI AMP의 **Training** 탭에서 직접 반복 훈련 세션을 실행하여 Crew 성능을 개선할 수 있습니다. 플랫폼은 **자동 훈련 모드**를 사용합니다 — 반복 프로세스를 자동으로 처리하며, 반복마다 대화형 피드백이 필요한 CLI 훈련과는 다릅니다.
|
||||
|
||||
훈련이 완료되면 CrewAI는 에이전트 출력을 평가하고 각 에이전트에 대한 실행 가능한 제안으로 피드백을 통합합니다. 이러한 제안은 향후 Crew 실행에 적용되어 출력 품질을 개선합니다.
|
||||
|
||||
<Tip>
|
||||
CrewAI 훈련이 내부적으로 어떻게 작동하는지에 대한 자세한 내용은 [훈련 개념](/ko/concepts/training) 페이지를 참조하세요.
|
||||
</Tip>
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="활성 배포" icon="rocket">
|
||||
**Ready** 상태의 활성 배포(Crew 유형)가 있는 CrewAI AMP 계정이 필요합니다.
|
||||
</Card>
|
||||
<Card title="실행 권한" icon="key">
|
||||
훈련하려는 배포에 대한 실행 권한이 계정에 있어야 합니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Crew 훈련 방법
|
||||
|
||||
<Steps>
|
||||
<Step title="Training 탭 열기">
|
||||
**Deployments**로 이동하여 배포를 클릭한 다음 **Training** 탭을 선택합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="훈련 이름 입력">
|
||||
**Training Name**을 입력합니다 — 이것은 훈련 결과를 저장하는 데 사용되는 `.pkl` 파일 이름이 됩니다. 예를 들어, "Expert Mode Training"은 `expert_mode_training.pkl`을 생성합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="Crew 입력값 작성">
|
||||
Crew의 입력 필드를 입력합니다. 이는 일반 kickoff에 제공하는 것과 동일한 입력값입니다 — Crew 구성에 따라 동적으로 로드됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="훈련 시작">
|
||||
**Train Crew**를 클릭합니다. 프로세스가 실행되는 동안 버튼이 스피너와 함께 "Training..."으로 변경됩니다.
|
||||
|
||||
내부적으로:
|
||||
- 배포에 대한 훈련 레코드가 생성됩니다
|
||||
- 플랫폼이 배포의 자동 훈련 엔드포인트를 호출합니다
|
||||
- Crew가 자동으로 반복을 실행합니다 — 수동 피드백이 필요하지 않습니다
|
||||
</Step>
|
||||
|
||||
<Step title="진행 상황 모니터링">
|
||||
**Current Training Status** 패널에 다음이 표시됩니다:
|
||||
- **Status** — 훈련 실행의 현재 상태
|
||||
- **Nº Iterations** — 구성된 훈련 반복 횟수
|
||||
- **Filename** — 생성 중인 `.pkl` 파일
|
||||
- **Started At** — 훈련 시작 시간
|
||||
- **Training Inputs** — 제공한 입력값
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 훈련 결과 이해
|
||||
|
||||
훈련이 완료되면 다음 정보가 포함된 에이전트별 결과 카드가 표시됩니다:
|
||||
|
||||
- **Agent Role** — Crew에서 에이전트의 이름/역할
|
||||
- **Final Quality** — 에이전트 출력 품질을 평가하는 0~10점 점수
|
||||
- **Final Summary** — 훈련 중 에이전트 성능 요약
|
||||
- **Suggestions** — 에이전트 동작 개선을 위한 실행 가능한 권장 사항
|
||||
|
||||
### 제안 편집
|
||||
|
||||
모든 에이전트의 제안을 개선할 수 있습니다:
|
||||
|
||||
<Steps>
|
||||
<Step title="Edit 클릭">
|
||||
에이전트의 결과 카드에서 제안 옆에 있는 **Edit** 버튼을 클릭합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="제안 수정">
|
||||
원하는 개선 사항을 더 잘 반영하도록 제안 텍스트를 업데이트합니다.
|
||||
</Step>
|
||||
|
||||
<Step title="변경 사항 저장">
|
||||
**Save**를 클릭합니다. 편집된 제안이 배포에 다시 동기화되고 이후 모든 실행에 사용됩니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 훈련 데이터 사용
|
||||
|
||||
Crew에 훈련 결과를 적용하려면:
|
||||
|
||||
1. 완료된 훈련 세션에서 **Training Filename**(`.pkl` 파일)을 확인합니다.
|
||||
2. 배포의 kickoff 또는 실행 구성에서 이 파일 이름을 지정합니다.
|
||||
3. Crew가 자동으로 훈련 파일을 로드하고 저장된 제안을 각 에이전트에 적용합니다.
|
||||
|
||||
이는 에이전트가 이후 모든 실행에서 훈련 중에 생성된 피드백의 혜택을 받는다는 것을 의미합니다.
|
||||
|
||||
## 이전 훈련
|
||||
|
||||
Training 탭 하단에는 배포에 대한 **모든 과거 훈련 세션 기록**이 표시됩니다. 이전 훈련 실행을 검토하거나 결과를 비교하거나 사용할 다른 훈련 파일을 선택하는 데 사용합니다.
|
||||
|
||||
## 오류 처리
|
||||
|
||||
훈련 실행이 실패하면 상태 패널에 무엇이 잘못되었는지 설명하는 메시지와 함께 오류 상태가 표시됩니다.
|
||||
|
||||
훈련 실패의 일반적인 원인:
|
||||
- **배포 런타임이 업데이트되지 않음** — 배포가 최신 버전을 실행하고 있는지 확인하세요
|
||||
- **Crew 실행 오류** — Crew의 작업 로직 또는 에이전트 구성 내 문제
|
||||
- **네트워크 문제** — 플랫폼과 배포 간의 연결 문제
|
||||
|
||||
## 제한 사항
|
||||
|
||||
<Info>
|
||||
훈련 워크플로를 계획할 때 다음 제약 사항을 염두에 두세요:
|
||||
- **배포당 한 번에 하나의 활성 훈련** — 다른 훈련을 시작하기 전에 현재 실행이 완료될 때까지 기다리세요
|
||||
- **자동 훈련 모드만** — 플랫폼은 CLI처럼 반복당 대화형 피드백을 지원하지 않습니다
|
||||
- **훈련 데이터는 배포별** — 훈련 결과는 특정 배포 인스턴스 및 버전에 연결됩니다
|
||||
</Info>
|
||||
|
||||
## 관련 리소스
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="훈련 개념" icon="book" href="/ko/concepts/training">
|
||||
CrewAI 훈련이 내부적으로 어떻게 작동하는지 알아보세요.
|
||||
</Card>
|
||||
<Card title="Crew 시작" icon="play" href="/ko/enterprise/guides/kickoff-crew">
|
||||
AMP 플랫폼에서 배포된 Crew를 실행하세요.
|
||||
</Card>
|
||||
<Card title="AMP에 배포" icon="cloud-arrow-up" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
Crew를 배포하고 훈련 준비를 완료하세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
91
docs/edge/ko/enterprise/guides/update-crew.mdx
Normal file
91
docs/edge/ko/enterprise/guides/update-crew.mdx
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: "크루 업데이트"
|
||||
description: "CrewAI AOP에서 크루 업데이트하기"
|
||||
icon: "pencil"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
CrewAI AOP에 crew를 배포한 후, 코드, 보안 설정 또는 구성을 업데이트해야 할 수
|
||||
있습니다. 이 가이드는 이러한 일반적인 업데이트 작업을 수행하는 방법을
|
||||
설명합니다.
|
||||
</Note>
|
||||
|
||||
## 왜 Crew를 업데이트해야 하나요?
|
||||
|
||||
CrewAI는 기본적으로 GitHub 업데이트를 자동으로 반영하지 않으므로, 배포 시 `Auto-update` 옵션을 선택하지 않았다면 수동으로 업데이트를 트리거해야 합니다.
|
||||
|
||||
Crew 배포를 업데이트하고 싶은 이유는 여러 가지가 있을 수 있습니다:
|
||||
|
||||
- GitHub에 푸시한 최신 커밋으로 코드를 업데이트하고 싶은 경우
|
||||
- 보안상의 이유로 bearer 토큰을 재설정하고 싶은 경우
|
||||
- 환경 변수를 업데이트하고 싶은 경우
|
||||
|
||||
## 1. 최신 커밋으로 Crew 코드 업데이트하기
|
||||
|
||||
GitHub 저장소에 새로운 커밋을 푸시한 후 배포를 업데이트하려면 다음 단계를 따르세요:
|
||||
|
||||
1. CrewAI AMP 플랫폼에서 자신의 crew로 이동하세요.
|
||||
2. crew 상세 페이지에서 `Re-deploy` 버튼을 클릭하세요.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
이 작업을 수행하면 진행률 표시줄을 통해 추적할 수 있는 업데이트가 트리거됩니다. 시스템은 저장소에서 최신 코드를 가져와서 배포를 다시 빌드합니다.
|
||||
|
||||
## 2. 베어러 토큰 재설정
|
||||
|
||||
현재 토큰이 유출되었을 가능성이 있다고 의심되는 경우 등, 새 베어러 토큰을 생성해야 한다면 다음 단계를 따르세요:
|
||||
|
||||
1. CrewAI AMP 플랫폼에서 해당 crew로 이동하세요.
|
||||
2. `Bearer Token` 섹션을 찾으세요.
|
||||
3. 현재 토큰 옆에 있는 `Reset` 버튼을 클릭하세요.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
<Warning>
|
||||
베어러 토큰을 재설정하면 이전 토큰은 즉시 사용할 수 없게 됩니다. 이전 토큰을
|
||||
사용하고 있는 모든 애플리케이션이나 스크립트에서 토큰을 반드시 업데이트하세요.
|
||||
</Warning>
|
||||
|
||||
## 3. 환경 변수 업데이트하기
|
||||
|
||||
crew의 환경 변수를 업데이트하려면 다음 단계를 따르세요:
|
||||
|
||||
1. 먼저 crew 이름을 클릭하여 배포 페이지에 접속합니다.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
2. `Environment Variables` 섹션을 찾습니다 (`Settings` 아이콘을 클릭해야 접근할 수 있습니다)
|
||||
3. 제공된 필드에서 기존 변수를 수정하거나 새 변수를 추가합니다
|
||||
4. 수정한 각 변수 옆의 `Update` 버튼을 클릭합니다
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
5. 마지막으로, 변경 사항을 적용하려면 페이지 하단의 `Update Deployment` 버튼을 클릭합니다
|
||||
|
||||
<Note>
|
||||
환경 변수를 업데이트하면 새로운 배포가 트리거되지만, 이는 환경 설정만
|
||||
업데이트하며 코드 자체는 변경되지 않습니다.
|
||||
</Note>
|
||||
|
||||
## 업데이트 후
|
||||
|
||||
업데이트를 수행한 후:
|
||||
|
||||
1. 시스템이 crew를 다시 빌드하고 배포합니다
|
||||
2. 실시간으로 배포 진행 상황을 모니터링할 수 있습니다
|
||||
3. 완료되면 변경 사항이 예상대로 작동하는지 crew를 테스트합니다
|
||||
|
||||
<Tip>
|
||||
업데이트 후 문제가 발생하면 플랫폼에서 배포 로그를 확인하거나 지원팀에
|
||||
문의하여 도움을 받을 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
crew 업데이트나 배포 문제 해결에 대해 지원이 필요하시면 지원팀에 문의해
|
||||
주세요.
|
||||
</Card>
|
||||
126
docs/edge/ko/enterprise/guides/webhook-automation.mdx
Normal file
126
docs/edge/ko/enterprise/guides/webhook-automation.mdx
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: "웹후크 자동화"
|
||||
description: "ActivePieces, Zapier, Make.com과 같은 플랫폼을 사용하여 CrewAI AMP 워크플로우를 웹후크로 자동화하세요"
|
||||
icon: "webhook"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
CrewAI AOP를 사용하면 웹훅을 통해 워크플로우를 자동화할 수 있습니다. 이 문서에서는 웹훅을 설정하고 사용하는 과정을 안내하며, Zapier와 Make.com과 유사한 워크플로우 자동화 플랫폼인 ActivePieces와의 통합에 중점을 두고 crew 실행을 시작하는 방법을 설명합니다.
|
||||
|
||||
## Webhook 설정하기
|
||||
|
||||
<Steps>
|
||||
<Step title="Kickoff 인터페이스 접근">
|
||||
- CrewAI AMP 대시보드로 이동하세요.
|
||||
- crew 실행을 시작할 때 사용하는 `/kickoff` 섹션을 찾으세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/kickoff-interface.png" alt="Kickoff 인터페이스" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="JSON Content 구성하기">
|
||||
JSON Content 섹션에서 다음 정보를 입력해야 합니다:
|
||||
|
||||
- **inputs**: 다음 항목이 포함된 JSON 객체:
|
||||
- `company`: 회사 이름 (예: "tesla")
|
||||
- `product_name`: 제품 이름 (예: "crewai")
|
||||
- `form_response`: 응답 유형 (예: "financial")
|
||||
- `icp_description`: 이상적인 고객 프로필(ICP)에 대한 간략한 설명
|
||||
- `product_description`: 제품에 대한 짧은 설명
|
||||
- `taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`: 다양한 webhook 엔드포인트의 URL (ActivePieces, Zapier, Make.com 또는 기타 호환 플랫폼)
|
||||
</Step>
|
||||
|
||||
<Step title="ActivePieces와 통합하기">
|
||||
이 예시에서는 ActivePieces를 사용합니다. 또한 Zapier, Make.com 등 다른 플랫폼도 사용할 수 있습니다.
|
||||
|
||||
ActivePieces와 통합하려면:
|
||||
|
||||
1. ActivePieces에서 새 flow를 설정하세요.
|
||||
2. 트리거를 추가하세요 (예: `Every Day` 스케줄).
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-trigger.png" alt="ActivePieces 트리거" />
|
||||
</Frame>
|
||||
|
||||
3. HTTP 액션 단계를 추가하세요.
|
||||
- 액션을 `Send HTTP request`로 설정하세요.
|
||||
- 메소드는 `POST`로 사용하세요.
|
||||
- URL은 CrewAI AMP kickoff 엔드포인트로 설정하세요.
|
||||
- 필요한 헤더 추가 (예: `Bearer Token`)
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-headers.png" alt="ActivePieces 헤더" />
|
||||
</Frame>
|
||||
|
||||
- Body에는 2단계에서 구성한 JSON content를 포함하세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-body.png" alt="ActivePieces 본문" />
|
||||
</Frame>
|
||||
|
||||
- crew가 미리 정의된 시간에 kickoff됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="Webhook 설정하기">
|
||||
1. ActivePieces에서 새 flow를 만들고 이름을 지정하세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-flow.png" alt="ActivePieces Flow" />
|
||||
</Frame>
|
||||
|
||||
2. 트리거로 webhook 단계를 추가하세요:
|
||||
- 트리거 유형으로 `Catch Webhook`을 선택하세요.
|
||||
- 이 작업을 통해 HTTP 요청을 수신하고 flow를 트리거하는 고유 URL이 생성됩니다.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-webhook.png" alt="ActivePieces Webhook" />
|
||||
</Frame>
|
||||
|
||||
- 이메일이 crew webhook 본문 텍스트를 사용하도록 구성하세요.
|
||||
<Frame>
|
||||
<img src="/images/enterprise/activepieces-email.png" alt="ActivePieces 이메일" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## Webhook 출력 예시
|
||||
|
||||
**참고:** kickoff 요청에 제공된 모든 `meta` 객체는 모든 webhook 페이로드에 포함되어, 전체 crew 실행 생명주기에 걸쳐 요청을 추적하고 컨텍스트를 유지할 수 있습니다.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Step Webhook">
|
||||
`stepWebhookUrl` - 각 agent의 inner thought가 실행될 때마다 호출되는 콜백
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "**crewai 엔터프라이즈 솔루션을 위한 금융 산업에 대한 예비 조사 보고서**\n1. 산업 개요 및 동향\n금융 산업은 ....\n결론:\n금융 산업은 디지털 고객 참여, 위험 관리, 규정 준수와 같은 분야에서 crewai와 같은 AI 솔루션을 적용하기에 비옥한 토양을 제공합니다. 고객의 구체적인 요구와 규모에 더 맞춘 crewai 솔루션을 제안하기 위해 리드와의 추가적인 접촉이 추천됩니다.",
|
||||
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Task Webhook">
|
||||
`taskWebhookUrl` - 각 task가 종료될 때마다 호출되는 콜백
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "리드의 데이터에서 수집한 정보를 활용해 리드가 속한 산업, 기업 배경, 그리고 crewai의 잠재적 활용 사례에 대해 예비 조사를 수행합니다. 리드 스코어링 및 crewai 피치 전략 수립에 도움이 되는 관련 데이터를 중심으로 조사하세요. 금융 산업은 디지털 고객 참여, 리스크 관리, 규제 준수와 같은 분야에서 crewai와 같은 AI 솔루션을 적용하기에 매우 적합한 환경을 제공합니다. 리드에 맞춤화된 crewai 솔루션을 제안하기 위해 추가적인 접촉을 권장합니다.",
|
||||
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Crew Webhook">
|
||||
`crewWebhookUrl` - crew 실행 종료 시 호출되는 콜백
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
|
||||
"result": {
|
||||
"lead_score": "고객 서비스 향상 및 컴플라이언스가 특히 관련성이 높습니다.",
|
||||
"talking_points": [
|
||||
"crewai의 AI 솔루션이 자동화된 맞춤형 경험과 24/7 지원으로 고객 서비스를 혁신하고, 고객 만족도와 운영 효율성을 모두 개선할 수 있음을 강조하세요.",
|
||||
"crewai가 더 나은 데이터 분석 및 의사 결정으로 기관의 지속 가능성 목표 달성(책임 투자 및 친환경 이니셔티브 기여)에 도움이 될 수 있음을 논의하세요.",
|
||||
"지속적으로 변화하는 규정에 효율적인 데이터 처리 및 보고 기능으로 crewai가 컴플라이언스 준수를 강화하고, 위반 시 발생할 수 있는 벌금을 줄일 수 있음을 강조하세요.",
|
||||
"crewai의 뛰어난 적응성으로 인해 대규모 다국적 운영뿐 아니라 소규모 맞춤형 프로젝트도 지원하여, 기관의 성장과 함께 솔루션도 확장될 수 있음을 강조하세요."
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
</Tabs>
|
||||
105
docs/edge/ko/enterprise/guides/zapier-trigger.mdx
Normal file
105
docs/edge/ko/enterprise/guides/zapier-trigger.mdx
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "Zapier 트리거"
|
||||
description: "Zapier 워크플로우에서 CrewAI crew를 트리거하여 앱 간 워크플로우를 자동화합니다"
|
||||
icon: "bolt"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
이 가이드는 CrewAI AOP용 Zapier 트리거를 설정하는 과정을 안내합니다. 이를 통해 CrewAI AOP와 기타 애플리케이션 간의 워크플로우를 자동화할 수 있습니다.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
- CrewAI AMP 계정
|
||||
- Zapier 계정
|
||||
- Slack 계정 (이 특정 예시에 해당)
|
||||
|
||||
## 단계별 설정
|
||||
|
||||
<Steps>
|
||||
<Step title="Slack 트리거 설정">
|
||||
- Zapier에서 새 Zap을 만듭니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-1.png" alt="Zapier 1" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="트리거 앱으로 Slack 선택">
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-2.png" alt="Zapier 2" />
|
||||
</Frame>
|
||||
- 트리거 이벤트로 `New Pushed Message`를 선택합니다.
|
||||
- 아직 Slack 계정을 연결하지 않았다면 연결하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="CrewAI AMP 액션 구성">
|
||||
- Zap에 새 액션 단계를 추가합니다.
|
||||
- CrewAI+를 액션 앱으로, Kickoff를 액션 이벤트로 선택합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-3.png" alt="Zapier 5" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="CrewAI AMP 계정 연결">
|
||||
- CrewAI AMP 계정을 연결하세요.
|
||||
- 워크플로에 적합한 Crew를 선택하세요.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-4.png" alt="Zapier 6" />
|
||||
</Frame>
|
||||
- Slack 메시지의 데이터를 사용하여 Crew의 입력값을 구성하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="CrewAI AMP 출력 포맷팅">
|
||||
- CrewAI AOP에서 출력된 텍스트를 포맷팅하기 위해 추가 액션 단계를 추가합니다.
|
||||
- Zapier의 포매팅 도구를 사용하여 Markdown 출력을 HTML로 변환합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-5.png" alt="Zapier 8" />
|
||||
</Frame>
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-6.png" alt="Zapier 9" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="출력 이메일로 전송">
|
||||
- 포맷팅된 출력을 이메일로 전송하는 마지막 액션 단계를 추가합니다.
|
||||
- 원하는 이메일 서비스를 선택하세요 (예: Gmail, Outlook).
|
||||
- 수신자, 제목, 본문 등 이메일 상세 정보를 구성하세요.
|
||||
- 포맷팅된 CrewAI AMP 출력을 이메일 본문에 삽입합니다.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-7.png" alt="Zapier 7" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Slack에서 crew 실행">
|
||||
- Slack 채널에 텍스트를 입력하세요.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-7b.png" alt="Zapier 10" />
|
||||
</Frame>
|
||||
|
||||
- 3점 버튼을 선택한 후 'Push to Zapier'를 선택하세요.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-8.png" alt="Zapier 11" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="crew 선택 후 Kick Off로 Push">
|
||||
<Frame>
|
||||
<img src="/images/enterprise/zapier-9.png" alt="Zapier 12" />
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 성공을 위한 팁
|
||||
|
||||
- CrewAI AMP 입력값이 Slack 메시지에서 올바르게 매핑되었는지 확인하세요.
|
||||
- Zap을 활성화하기 전에 철저히 테스트하여 잠재적인 문제를 미리 파악하세요.
|
||||
- 워크플로우 내에서 발생할 수 있는 실패 상황을 관리하기 위해 오류 처리 단계를 추가하는 것을 고려하세요.
|
||||
|
||||
이 단계를 따르면 Slack 메시지로 트리거되는 자동화된 워크플로우와 CrewAI AMP 출력이 포함된 이메일 알림을 설정할 수 있습니다.
|
||||
265
docs/edge/ko/enterprise/integrations/asana.mdx
Normal file
265
docs/edge/ko/enterprise/integrations/asana.mdx
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: Asana 연동
|
||||
description: "CrewAI를 위한 Asana 연동으로 팀 작업 및 프로젝트 조정."
|
||||
icon: "circle"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Asana를 통해 업무, 프로젝트, 팀 협업을 관리할 수 있도록 지원하세요. 작업 생성, 프로젝트 상태 업데이트, 담당 할당 관리, AI 기반 자동화를 통한 팀의 워크플로우 최적화를 손쉽게 할 수 있습니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
Asana 연동을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 권한이 있는 Asana 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Asana 계정 연결
|
||||
|
||||
## 아사나(Asana) 연동 설정
|
||||
|
||||
### 1. Asana 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Asana**를 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다.
|
||||
4. 작업 및 프로젝트 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="asana/create_comment">
|
||||
**설명:** Asana에 댓글을 생성합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `task` (string, 필수): 작업 ID - 댓글이 추가될 작업의 ID입니다. 댓글 작성자는 현재 인증된 사용자입니다.
|
||||
- `text` (string, 필수): 텍스트 (예: "This is a comment.").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/create_project">
|
||||
**설명:** Asana에 프로젝트를 생성합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `name` (string, 필수): 이름 (예: "Stuff to buy").
|
||||
- `workspace` (string, 필수): 워크스페이스 - Connect Portal Workflow 설정을 사용해 사용자가 프로젝트를 생성할 워크스페이스를 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 워크스페이스가 선택됩니다.
|
||||
- `team` (string, 선택): 팀 - Connect Portal Workflow 설정을 사용해 사용자가 이 프로젝트를 공유할 팀을 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 팀이 선택됩니다.
|
||||
- `notes` (string, 선택): 노트 (예: "These are things we need to purchase.").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_projects">
|
||||
**설명:** Asana의 프로젝트 목록을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `archived` (string, 선택): 보관됨 - 보관된 프로젝트를 보려면 "true", 활성 프로젝트만 보려면 "false", 보관됨과 활성 모두 보려면 "default"를 선택합니다.
|
||||
- 옵션: `default`, `true`, `false`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_project_by_id">
|
||||
**설명:** Asana에서 ID로 프로젝트를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `projectFilterId` (string, 필수): 프로젝트 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/create_task">
|
||||
**설명:** Asana에 작업을 생성합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `name` (string, 필수): 이름 (예: "Task Name").
|
||||
- `workspace` (string, 선택): 워크스페이스 - Connect Portal Workflow 설정을 사용해 사용자가 작업을 생성할 워크스페이스를 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 워크스페이스가 선택됩니다.
|
||||
- `project` (string, 선택): 프로젝트 - Connect Portal Workflow 설정을 사용해 사용자가 이 작업을 생성할 프로젝트를 선택할 수 있도록 합니다.
|
||||
- `notes` (string, 선택): 노트.
|
||||
- `dueOnDate` (string, 선택): 마감일 - 이 작업이 완료되어야 하는 날짜입니다. Due At과 함께 사용할 수 없습니다. (예: "YYYY-MM-DD").
|
||||
- `dueAtDate` (string, 선택): 마감 시각 - 이 작업이 완료되어야 하는 날짜와 시간 (ISO 타임스탬프) 입니다. Due On과 함께 사용할 수 없습니다. (예: "2019-09-15T02:06:58.147Z").
|
||||
- `assignee` (string, 선택): 담당자 - 이 작업이 할당될 Asana 사용자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다.
|
||||
- `gid` (string, 선택): 외부 ID - 이 작업과 연결할 애플리케이션의 ID입니다. 이 ID를 사용하여 이후 작업 업데이트를 동기화할 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/update_task">
|
||||
**설명:** Asana의 작업을 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `taskId` (string, 필수): 작업 ID - 업데이트할 작업의 ID입니다.
|
||||
- `completeStatus` (string, 선택): 완료 상태.
|
||||
- 옵션: `true`, `false`
|
||||
- `name` (string, 선택): 이름 (예: "Task Name").
|
||||
- `notes` (string, 선택): 노트.
|
||||
- `dueOnDate` (string, 선택): 마감일 - 이 작업이 완료되어야 하는 날짜입니다. Due At과 함께 사용할 수 없습니다. (예: "YYYY-MM-DD").
|
||||
- `dueAtDate` (string, 선택): 마감 시각 - 이 작업이 완료되어야 하는 날짜와 시간 (ISO 타임스탬프) 입니다. Due On과 함께 사용할 수 없습니다. (예: "2019-09-15T02:06:58.147Z").
|
||||
- `assignee` (string, 선택): 담당자 - 이 작업이 할당될 Asana 사용자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다.
|
||||
- `gid` (string, 선택): 외부 ID - 이 작업과 연결할 애플리케이션의 ID입니다. 이 ID를 사용하여 이후 작업 업데이트를 동기화할 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_tasks">
|
||||
**설명:** Asana의 작업 목록을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `workspace` (string, 선택): 워크스페이스 - 작업을 필터링할 워크스페이스의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 워크스페이스를 선택할 수 있도록 합니다.
|
||||
- `project` (string, 선택): 프로젝트 - 작업을 필터링할 프로젝트의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 프로젝트를 선택할 수 있도록 합니다.
|
||||
- `assignee` (string, 선택): 담당자 - 작업을 필터링할 담당자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다.
|
||||
- `completedSince` (string, 선택): 이후 완료됨 - 미완료이거나 해당 시간(ISO 또는 Unix 타임스탬프) 이후에 완료된 작업만 반환합니다. (예: "2014-04-25T16:15:47-04:00").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_tasks_by_id">
|
||||
**설명:** Asana에서 ID로 작업 목록을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `taskId` (string, 필수): 작업 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_task_by_external_id">
|
||||
**설명:** Asana에서 외부 ID로 작업을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `gid` (string, 필수): 외부 ID - 이 작업이 애플리케이션과 연동(또는 동기화)된 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/add_task_to_section">
|
||||
**설명:** Asana에서 섹션에 작업을 추가합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `sectionId` (string, 필수): 섹션 ID - 작업을 추가할 섹션의 ID입니다.
|
||||
- `taskId` (string, 필수): 작업 ID - 작업의 ID입니다. (예: "1204619611402340").
|
||||
- `beforeTaskId` (string, 선택): 이전 작업 ID - 이 작업이 삽입될 섹션 내의 작업 ID입니다. 이후 작업 ID와 함께 사용할 수 없습니다. (예: "1204619611402340").
|
||||
- `afterTaskId` (string, 선택): 이후 작업 ID - 이 작업이 삽입될 섹션 내의 작업 ID입니다. 이전 작업 ID와 함께 사용할 수 없습니다. (예: "1204619611402340").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_teams">
|
||||
**설명:** Asana에서 팀 목록을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `workspace` (string, 필수): 워크스페이스 - 인증된 사용자가 볼 수 있는 이 워크스페이스 내의 팀을 반환합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="asana/get_workspaces">
|
||||
**설명:** Asana에서 워크스페이스 목록을 가져옵니다.
|
||||
|
||||
**매개변수:** 필요 없음.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Asana 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Asana capabilities
|
||||
asana_agent = Agent(
|
||||
role="Project Manager",
|
||||
goal="Manage tasks and projects in Asana efficiently",
|
||||
backstory="An AI assistant specialized in project management and task coordination.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# Task to create a new project
|
||||
create_project_task = Task(
|
||||
description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace",
|
||||
agent=asana_agent,
|
||||
expected_output="Confirmation that the project was created successfully with project ID"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[asana_agent],
|
||||
tasks=[create_project_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Asana 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
task_manager_agent = Agent(
|
||||
role="Task Manager",
|
||||
goal="Create and manage tasks efficiently",
|
||||
backstory="An AI assistant that focuses on task creation and management.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# Task to create and assign a task
|
||||
task_management = Task(
|
||||
description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member",
|
||||
agent=task_manager_agent,
|
||||
expected_output="Task created and assigned successfully"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[task_manager_agent],
|
||||
tasks=[task_management]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 고급 프로젝트 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
project_coordinator = Agent(
|
||||
role="Project Coordinator",
|
||||
goal="Coordinate project activities and track progress",
|
||||
backstory="An experienced project coordinator who ensures projects run smoothly.",
|
||||
apps=['asana']
|
||||
)
|
||||
|
||||
# Complex task involving multiple Asana operations
|
||||
coordination_task = Task(
|
||||
description="""
|
||||
1. Get all active projects in the workspace
|
||||
2. For each project, get the list of incomplete tasks
|
||||
3. Create a summary report task in the 'Management Reports' project
|
||||
4. Add comments to overdue tasks to request status updates
|
||||
""",
|
||||
agent=project_coordinator,
|
||||
expected_output="Summary report created and status update requests sent for overdue tasks"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[project_coordinator],
|
||||
tasks=[coordination_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
277
docs/edge/ko/enterprise/integrations/box.mdx
Normal file
277
docs/edge/ko/enterprise/integrations/box.mdx
Normal file
@@ -0,0 +1,277 @@
|
||||
---
|
||||
title: Box 통합
|
||||
description: "CrewAI용 Box 통합을 통한 파일 저장 및 문서 관리."
|
||||
icon: "box"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Box를 통해 파일, 폴더, 문서를 관리할 수 있도록 지원하세요. 파일을 업로드하고, 폴더 구조를 조직하며, 콘텐츠를 검색하고, AI 기반 자동화를 통해 팀의 문서 관리를 효율적으로 진행할 수 있습니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
Box 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 권한이 있는 Box 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Box 계정 연결
|
||||
|
||||
## Box 통합 설정
|
||||
|
||||
### 1. Box 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Box**를 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다.
|
||||
4. 파일 및 폴더 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 액션
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="box/save_file">
|
||||
**설명:** Box에서 URL로부터 파일을 저장합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `fileAttributes` (object, 필수): 속성 - 이름, 상위 폴더, 타임스탬프 등 파일 메타데이터.
|
||||
```json
|
||||
{
|
||||
"content_created_at": "2012-12-12T10:53:43-08:00",
|
||||
"content_modified_at": "2012-12-12T10:53:43-08:00",
|
||||
"name": "qwerty.png",
|
||||
"parent": { "id": "1234567" }
|
||||
}
|
||||
```
|
||||
- `file` (string, 필수): 파일 URL - 파일 크기는 50MB 미만이어야 합니다. (예시: "https://picsum.photos/200/300").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/save_file_from_object">
|
||||
**설명:** Box에 파일을 저장합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `file` (string, 필수): 파일 - 파일 데이터를 포함하는 파일 객체를 허용합니다. 파일 크기는 50MB 미만이어야 합니다.
|
||||
- `fileName` (string, 필수): 파일명 (예시: "qwerty.png").
|
||||
- `folder` (string, 선택): 폴더 - Connect Portal Workflow Settings를 사용하여 사용자가 파일의 폴더 목적지를 선택할 수 있도록 합니다. 비워두면 기본적으로 사용자의 루트 폴더에 저장됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/get_file_by_id">
|
||||
**설명:** Box에서 ID로 파일을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `fileId` (string, 필수): 파일 ID - 파일을 나타내는 고유 식별자. (예시: "12345").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/list_files">
|
||||
**설명:** Box에서 파일 목록을 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0").
|
||||
- `filterFormula` (object, 선택): 쿼리 normal form (DNF)의 필터 - 단일 조건의 AND 그룹의 OR.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "direction",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "ASC"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/create_folder">
|
||||
**설명:** Box에 폴더를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderName` (string, 필수): 이름 - 새 폴더의 이름. (예시: "New Folder").
|
||||
- `folderParent` (object, 필수): 상위 폴더 - 새 폴더가 생성될 상위 폴더.
|
||||
```json
|
||||
{
|
||||
"id": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/move_folder">
|
||||
**설명:** Box에서 폴더를 이동합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0").
|
||||
- `folderName` (string, 필수): 이름 - 폴더의 이름. (예시: "New Folder").
|
||||
- `folderParent` (object, 필수): 상위 폴더 - 새 상위 폴더 목적지.
|
||||
```json
|
||||
{
|
||||
"id": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/get_folder_by_id">
|
||||
**설명:** Box에서 ID로 폴더를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/search_folders">
|
||||
**설명:** Box에서 폴더를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderId` (string, 필수): 폴더 ID - 검색할 폴더.
|
||||
- `filterFormula` (object, 선택): 쿼리 normal form (DNF)의 필터 - 단일 조건의 AND 그룹의 OR.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "sort",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "name"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="box/delete_folder">
|
||||
**설명:** Box에서 폴더를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0").
|
||||
- `recursive` (boolean, 선택): 재귀적 삭제 - 폴더가 비어 있지 않을 경우, 폴더와 그 모든 내용을 재귀적으로 삭제합니다.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Box Agent 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Box capabilities
|
||||
box_agent = Agent(
|
||||
role="Document Manager",
|
||||
goal="Manage files and folders in Box efficiently",
|
||||
backstory="An AI assistant specialized in document management and file organization.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# Task to create a folder structure
|
||||
create_structure_task = Task(
|
||||
description="Create a folder called 'Project Files' in the root directory and upload a document from URL",
|
||||
agent=box_agent,
|
||||
expected_output="Folder created and file uploaded successfully"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[box_agent],
|
||||
tasks=[create_structure_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Box 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
file_organizer_agent = Agent(
|
||||
role="File Organizer",
|
||||
goal="Organize and manage file storage efficiently",
|
||||
backstory="An AI assistant that focuses on file organization and storage management.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# Task to organize files
|
||||
organization_task = Task(
|
||||
description="Create a folder structure for the marketing team and organize existing files",
|
||||
agent=file_organizer_agent,
|
||||
expected_output="Folder structure created and files organized"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[file_organizer_agent],
|
||||
tasks=[organization_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 고급 파일 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
file_manager = Agent(
|
||||
role="File Manager",
|
||||
goal="Maintain organized file structure and manage document lifecycle",
|
||||
backstory="An experienced file manager who ensures documents are properly organized and accessible.",
|
||||
apps=['box']
|
||||
)
|
||||
|
||||
# Complex task involving multiple Box operations
|
||||
management_task = Task(
|
||||
description="""
|
||||
1. List all files in the root folder
|
||||
2. Create monthly archive folders for the current year
|
||||
3. Move old files to appropriate archive folders
|
||||
4. Generate a summary report of the file organization
|
||||
""",
|
||||
agent=file_manager,
|
||||
expected_output="Files organized into archive structure with summary report"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[file_manager],
|
||||
tasks=[management_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
304
docs/edge/ko/enterprise/integrations/clickup.mdx
Normal file
304
docs/edge/ko/enterprise/integrations/clickup.mdx
Normal file
@@ -0,0 +1,304 @@
|
||||
---
|
||||
title: ClickUp 연동
|
||||
description: "CrewAI를 위한 ClickUp 연동을 통한 작업 및 생산성 관리."
|
||||
icon: "list-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 ClickUp을 통해 작업, 프로젝트 및 생산성 워크플로우를 관리할 수 있도록 지원하세요. 작업을 생성 및 업데이트하고, 프로젝트를 구성하며, 팀 할당을 관리하고, AI 기반 자동화를 통해 생산성 관리를 간소화할 수 있습니다.
|
||||
|
||||
## 사전 준비사항
|
||||
|
||||
ClickUp 통합을 사용하기 전에 다음을 준비해야 합니다:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 권한이 있는 ClickUp 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 ClickUp 계정 연결
|
||||
|
||||
## ClickUp 통합 설정
|
||||
|
||||
### 1. ClickUp 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **ClickUp**을 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 과정을 완료합니다.
|
||||
4. 작업 및 프로젝트 관리에 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 동작
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="clickup/search_tasks">
|
||||
**설명:** 고급 필터를 사용하여 ClickUp에서 작업을 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `taskFilterFormula` (object, 선택): 이항 표준형(DNF)의 필터 - 단일 조건의 AND 그룹들의 OR.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "statuses%5B%5D",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "open"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `space_ids%5B%5D`, `project_ids%5B%5D`, `list_ids%5B%5D`, `statuses%5B%5D`, `include_closed`, `assignees%5B%5D`, `tags%5B%5D`, `due_date_gt`, `due_date_lt`, `date_created_gt`, `date_created_lt`, `date_updated_gt`, `date_updated_lt`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_task_in_list">
|
||||
**설명:** ClickUp의 특정 목록에서 작업을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `listId` (string, 필수): 목록 - 작업을 가져올 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `taskFilterFormula` (string, 선택): 지정된 필터와 일치하는 작업을 검색합니다. 예: name=task1.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/create_task">
|
||||
**설명:** ClickUp에 작업을 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `listId` (string, 필수): 목록 - 이 작업을 생성할 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `name` (string, 필수): 이름 - 작업 이름.
|
||||
- `description` (string, 선택): 설명 - 작업 설명.
|
||||
- `status` (string, 선택): 상태 - 이 작업에 대한 상태를 선택합니다. 사용자가 ClickUp 상태를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `assignees` (string, 선택): 담당자 - 이 작업에 할당할 멤버(또는 멤버 ID 배열)를 선택합니다. 사용자가 ClickUp 멤버를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `dueDate` (string, 선택): 마감일 - 이 작업의 마감일을 지정합니다.
|
||||
- `additionalFields` (string, 선택): 추가 필드 - 이 작업에 포함할 추가 필드를 JSON으로 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/update_task">
|
||||
**설명:** ClickUp의 작업을 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `taskId` (string, 필수): 작업 ID - 업데이트할 작업의 ID입니다.
|
||||
- `listId` (string, 필수): 목록 - 이 작업을 생성할 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `name` (string, 선택): 이름 - 작업 이름.
|
||||
- `description` (string, 선택): 설명 - 작업 설명.
|
||||
- `status` (string, 선택): 상태 - 이 작업에 대한 상태를 선택합니다. 사용자가 ClickUp 상태를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `assignees` (string, 선택): 담당자 - 이 작업에 할당할 멤버(또는 멤버 ID 배열)를 선택합니다. 사용자가 ClickUp 멤버를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요.
|
||||
- `dueDate` (string, 선택): 마감일 - 이 작업의 마감일을 지정합니다.
|
||||
- `additionalFields` (string, 선택): 추가 필드 - 이 작업에 포함할 추가 필드를 JSON으로 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/delete_task">
|
||||
**설명:** ClickUp에서 작업을 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `taskId` (string, 필수): 작업 ID - 삭제할 작업의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_list">
|
||||
**설명:** ClickUp에서 목록 정보를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `spaceId` (string, 필수): 스페이스 ID - 목록이 포함된 스페이스의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_custom_fields_in_list">
|
||||
**설명:** ClickUp에서 목록의 사용자 정의 필드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `listId` (string, 필수): 목록 ID - 사용자 정의 필드를 가져올 목록의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_all_fields_in_list">
|
||||
**설명:** ClickUp에서 목록의 모든 필드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `listId` (string, 필수): 목록 ID - 모든 필드를 가져올 목록의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_space">
|
||||
**설명:** ClickUp에서 스페이스 정보를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `spaceId` (string, 선택): 스페이스 ID - 조회할 스페이스의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_folders">
|
||||
**설명:** ClickUp에서 폴더를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `spaceId` (string, 필수): 스페이스 ID - 폴더가 포함된 스페이스의 ID입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="clickup/get_member">
|
||||
**설명:** ClickUp에서 멤버 정보를 가져옵니다.
|
||||
|
||||
**파라미터:** 필요 없음.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 ClickUp 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with ClickUp capabilities
|
||||
clickup_agent = Agent(
|
||||
role="Task Manager",
|
||||
goal="Manage tasks and projects in ClickUp efficiently",
|
||||
backstory="An AI assistant specialized in task management and productivity coordination.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# Task to create a new task
|
||||
create_task = Task(
|
||||
description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority",
|
||||
agent=clickup_agent,
|
||||
expected_output="Task created successfully with task ID"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[clickup_agent],
|
||||
tasks=[create_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 ClickUp 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
task_coordinator = Agent(
|
||||
role="Task Coordinator",
|
||||
goal="Create and manage tasks efficiently",
|
||||
backstory="An AI assistant that focuses on task creation and status management.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# Task to manage task workflow
|
||||
task_workflow = Task(
|
||||
description="Create a task for project planning and assign it to the development team",
|
||||
agent=task_coordinator,
|
||||
expected_output="Task created and assigned successfully"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[task_coordinator],
|
||||
tasks=[task_workflow]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 고급 프로젝트 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
project_manager = Agent(
|
||||
role="Project Manager",
|
||||
goal="Coordinate project activities and track team productivity",
|
||||
backstory="An experienced project manager who ensures projects are delivered on time.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# Complex task involving multiple ClickUp operations
|
||||
project_coordination = Task(
|
||||
description="""
|
||||
1. Get all open tasks in the current space
|
||||
2. Identify overdue tasks and update their status
|
||||
3. Create a weekly report task summarizing project progress
|
||||
4. Assign the report task to the team lead
|
||||
""",
|
||||
agent=project_manager,
|
||||
expected_output="Project status updated and weekly report task created and assigned"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[project_manager],
|
||||
tasks=[project_coordination]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 작업 검색 및 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
task_analyst = Agent(
|
||||
role="Task Analyst",
|
||||
goal="Analyze task patterns and optimize team productivity",
|
||||
backstory="An AI assistant that analyzes task data to improve team efficiency.",
|
||||
apps=['clickup']
|
||||
)
|
||||
|
||||
# Task to analyze and optimize task distribution
|
||||
task_analysis = Task(
|
||||
description="""
|
||||
Search for all tasks assigned to team members in the last 30 days,
|
||||
analyze completion patterns, and create optimization recommendations
|
||||
""",
|
||||
agent=task_analyst,
|
||||
expected_output="Task analysis report with optimization recommendations"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[task_analyst],
|
||||
tasks=[task_analysis]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
ClickUp 연동 설정 또는 문제 해결에 대한 지원이 필요하신 경우 저희 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
123
docs/edge/ko/enterprise/integrations/databricks.mdx
Normal file
123
docs/edge/ko/enterprise/integrations/databricks.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Databricks 연동
|
||||
description: "Databricks 관리형 MCP 서버를 통해 CrewAI 에이전트를 Databricks Genie, SQL, Unity Catalog Functions, Vector Search에 연결하세요."
|
||||
icon: "layer-group"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
[Databricks 관리형 MCP 서버](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 통해 CrewAI 에이전트를 Databricks 워크스페이스에 직접 연결하세요. Databricks 연동을 사용하면 에이전트가 **Genie**로 자연어 질문을 하고, 거버넌스가 적용된 **SQL**을 실행하며, **Unity Catalog Functions**를 호출하고, **Vector Search**로 문서를 검색할 수 있습니다. 커넥터 코드를 작성하거나 호스팅할 필요가 없으며, 모든 호출에 Unity Catalog 권한이 적용됩니다.
|
||||
|
||||
내부적으로 Databricks 연동은 CrewAI의 [커스텀 MCP 서버](/ko/enterprise/guides/custom-mcp-server) 지원을 감싼 관리형 래퍼입니다. Databricks는 각 기능을 개별 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트로 노출하며, CrewAI가 사용자를 대신해 안전하게 연결합니다. 각 서버를 개별적으로 추가하므로 크루에 필요한 기능만 정확히 활성화할 수 있습니다.
|
||||
|
||||
## 주요 기능
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Genie" icon="comments">
|
||||
[Genie](https://docs.databricks.com/aws/en/genie/)로 자연어 질문을 하고 데이터 기반의 근거 있는 답변을 받으세요. Genie는 Genie Spaces와 Unity Catalog를 조회하고 Databricks UI로 연결되는 링크를 제공합니다.
|
||||
</Card>
|
||||
<Card title="Databricks SQL" icon="database">
|
||||
에이전트에서 직접 Databricks 웨어하우스에 거버넌스가 적용된 SQL을 실행하여 데이터를 조회, 변환하고 데이터 파이프라인을 작성하세요.
|
||||
</Card>
|
||||
<Card title="Unity Catalog Functions" icon="function">
|
||||
[Unity Catalog 함수](https://docs.databricks.com/aws/en/udf/unity-catalog)를 호출하여 사전 정의된 SQL과 맞춤형 비즈니스 로직을 거버넌스가 적용된 재사용 가능한 도구로 실행하세요.
|
||||
</Card>
|
||||
<Card title="Vector Search" icon="magnifying-glass">
|
||||
[Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) 인덱스에서 의미 유사도를 사용해 RAG 및 지식 워크플로우에 필요한 관련 문서를 검색하세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
모든 서버는 Unity AI Gateway 뒤에서 실행되며 Unity Catalog 접근 제어를 적용하므로, 에이전트는 허용된 데이터와 도구만 볼 수 있습니다.
|
||||
|
||||
## 사전 준비사항
|
||||
|
||||
Databricks 연동을 사용하기 전에 다음을 준비해야 합니다:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 노출하려는 기능이 있는 Databricks 워크스페이스(Genie Spaces, SQL 웨어하우스, Unity Catalog 함수 또는 Vector Search 인덱스)
|
||||
- 기본 객체에 대한 적절한 [Unity Catalog 권한](https://docs.databricks.com/aws/en/data-governance/unity-catalog)
|
||||
- Databricks 워크스페이스 호스트명(예: `your-workspace.cloud.databricks.com`)
|
||||
|
||||
## Databricks 관리형 MCP 서버
|
||||
|
||||
Databricks는 각 기능마다 별도의 관리형 MCP 서버를 게시합니다. CrewAI는 이를 개별 연결로 노출하며, 각 연결은 워크스페이스 호스트와 관련 Unity Catalog 식별자로 구성됩니다. 엔드포인트는 다음 패턴을 따릅니다:
|
||||
|
||||
| 서버 | 기능 | MCP URL 패턴 |
|
||||
|------|------|--------------|
|
||||
| **Genie** | Genie Space에 대한 자연어 Q&A | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
|
||||
| **Databricks SQL** | 웨어하우스에 SQL 실행 | `https://<workspace-hostname>/api/2.0/mcp/sql` |
|
||||
| **Unity Catalog Functions** | 등록된 UC 함수 실행 | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
|
||||
| **Vector Search** | Vector Search 인덱스 조회 | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
|
||||
|
||||
<Note>
|
||||
이러한 URL을 직접 만들 필요는 없습니다. CrewAI는 연결을 구성할 때 입력한 워크스페이스 호스트와 식별자(Genie Space ID 또는 catalog/schema)로 각 엔드포인트를 생성합니다. 전체 사양과 최신 엔드포인트 세부 정보는 [Databricks 관리형 MCP 문서](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 참고하세요.
|
||||
</Note>
|
||||
|
||||
## CrewAI AMP에서 Databricks 연결하기
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/databricks-configure.png" alt="CrewAI AMP에서 Databricks 관리형 MCP 서버 구성" />
|
||||
</Frame>
|
||||
|
||||
각 Databricks 기능(**Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, **Databricks Vector Search**)은 **Tools & Integrations** 페이지의 Databricks 그룹 아래에 별도의 MCP 서버로 표시됩니다. 필요한 것을 구성하세요:
|
||||
|
||||
<Steps>
|
||||
<Step title="Tools & Integrations 열기">
|
||||
CrewAI AMP 왼쪽 사이드바에서 **Tools & Integrations**로 이동하여 Connections 목록에서 **Databricks** 그룹을 찾습니다. 그 아래에 Genie, SQL, Unity Catalog Functions, Vector Search 서버가 나열됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="서버 구성하기">
|
||||
활성화하려는 기능 옆의 **Configure**를 클릭하고 연결 세부 정보를 입력합니다:
|
||||
|
||||
- **Workspace Host** — Databricks 워크스페이스 호스트명(예: `my-workspace.cloud.databricks.com`).
|
||||
- **Genie** — 조회할 **Genie Space ID**.
|
||||
- **Unity Catalog Functions** — 함수가 포함된 **catalog**와 **schema**.
|
||||
- **Vector Search** — 인덱스가 포함된 **catalog**와 **schema**.
|
||||
- **Databricks SQL** — 추가 식별자가 필요 없으며, 쿼리는 워크스페이스의 SQL 웨어하우스에서 실행됩니다.
|
||||
</Step>
|
||||
|
||||
<Step title="인증 방법 선택하기">
|
||||
CrewAI가 Databricks에 인증하는 방법을 선택합니다. **OAuth**를 권장합니다.
|
||||
|
||||
- **Use OAuth** — OAuth 2.0으로 안전하게 연결합니다. 각 사용자가 개별적으로 인증하며, Databricks는 해당 기능(`genie`, `sql`, `unity-catalog` 또는 `vector-search`)으로 범위가 지정된 토큰을 발급합니다. CrewAI가 인증 흐름을 처리하고 토큰을 자동으로 갱신합니다.
|
||||
- **Use personal access token** — [Databricks 개인 액세스 토큰](https://docs.databricks.com/aws/en/dev-tools/auth/pat)으로 인증합니다. 노출을 제한하려면 최소 권한 ID를 사용하세요.
|
||||
</Step>
|
||||
|
||||
<Step title="인증하기">
|
||||
인증을 완료합니다. 연결되면 해당 서버의 도구를 크루에서 사용할 수 있습니다. 활성화하려는 다른 Databricks 기능에 대해서도 반복합니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
각 기능이 별도의 연결이므로 자유롭게 조합할 수 있습니다. 예를 들어 리서치 크루에는 Genie와 Vector Search를 활성화하고, 데이터 엔지니어링 크루에는 SQL과 Unity Catalog Functions를 사용하도록 할 수 있습니다. 가시성(Visibility) 설정으로 각 기능을 사용할 수 있는 팀원을 제어할 수 있습니다.
|
||||
</Tip>
|
||||
|
||||
## 크루에서 Databricks 도구 사용하기
|
||||
|
||||
연결되면 각 MCP 서버가 노출하는 도구가 **Tools & Integrations** 페이지의 기본 제공 연결과 함께 표시됩니다. 다음을 할 수 있습니다:
|
||||
|
||||
- 다른 CrewAI 도구와 마찬가지로 크루의 에이전트에 **도구 할당**.
|
||||
- 각 연결을 사용할 수 있는 팀원을 제어하는 **가시성 관리**.
|
||||
- Connections 목록에서 언제든지 연결 **편집 또는 제거**.
|
||||
|
||||
이제 에이전트는 Genie에 근거 있는 답변을 요청하고, 웨어하우스에 SQL을 실행하며, Unity Catalog 함수를 호출하고, Vector Search 인덱스를 검색할 수 있으며, 그 결과가 자동으로 추론에 반영됩니다.
|
||||
|
||||
<Warning>
|
||||
Databricks는 Unity Catalog와 Unity AI Gateway를 통해 거버넌스를 적용합니다. 사용자는 워크스페이스 ID에 허용된 도구만 검색하고 호출할 수 있습니다. 도구 호출이 실패하면 연결하는 사용자(또는 토큰 ID)가 Genie Space, 웨어하우스, 함수 또는 인덱스에 필요한 Unity Catalog 권한을 가지고 있는지 확인하세요. 일부 Genie 및 SQL 쿼리는 비동기로 실행되어 결과를 반환하는 데 시간이 걸릴 수 있습니다.
|
||||
</Warning>
|
||||
|
||||
## 더 알아보기
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Databricks 관리형 MCP 서버" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
|
||||
관리형 Genie, SQL, Unity Catalog Functions, Vector Search MCP 서버에 대한 공식 Databricks 문서입니다.
|
||||
</Card>
|
||||
<Card title="CrewAI의 커스텀 MCP 서버" icon="plug" href="/ko/enterprise/guides/custom-mcp-server">
|
||||
Databricks 연동의 기반이 되는, CrewAI가 모든 MCP 서버에 연결하는 방법을 알아보세요.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
Databricks 연동 구성 또는 문제 해결에 대한 지원이 필요하면 지원팀에 문의하세요.
|
||||
</Card>
|
||||
332
docs/edge/ko/enterprise/integrations/github.mdx
Normal file
332
docs/edge/ko/enterprise/integrations/github.mdx
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
title: GitHub 통합
|
||||
description: "CrewAI를 위한 GitHub 통합을 통한 리포지토리 및 이슈 관리."
|
||||
icon: "github"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 GitHub를 통해 리포지토리, 이슈, 릴리스를 관리할 수 있도록 지원합니다. 이슈를 생성 및 업데이트하고, 릴리스를 관리하고, 프로젝트 개발을 추적하며, AI 기반 자동화를 통해 소프트웨어 개발 워크플로우를 효율화하세요.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
GitHub 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 해당 리포지토리에 대한 적절한 권한이 있는 GitHub 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 GitHub 계정 연결 완료
|
||||
|
||||
## GitHub 연동 설정
|
||||
|
||||
### 1. GitHub 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **GitHub**을 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다.
|
||||
4. 리포지토리 및 이슈 관리를 위한 필수 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="github/create_issue">
|
||||
**설명:** GitHub에 이슈를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다.
|
||||
- `title` (string, 필수): 이슈 제목 - 생성할 이슈의 제목을 지정합니다.
|
||||
- `body` (string, 선택): 이슈 본문 - 생성할 이슈의 본문 내용을 지정합니다.
|
||||
- `assignees` (string, 선택): 담당자 - 이 이슈의 담당자 GitHub 로그인을 문자열 배열로 지정합니다. (예시: `["octocat"]`).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/update_issue">
|
||||
**설명:** GitHub에서 이슈를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다.
|
||||
- `issue_number` (string, 필수): 이슈 번호 - 업데이트할 이슈의 번호를 지정합니다.
|
||||
- `title` (string, 필수): 이슈 제목 - 업데이트할 이슈의 제목을 지정합니다.
|
||||
- `body` (string, 선택): 이슈 본문 - 업데이트할 이슈의 본문 내용을 지정합니다.
|
||||
- `assignees` (string, 선택): 담당자 - 이 이슈의 담당자 GitHub 로그인을 문자열 배열로 지정합니다. (예시: `["octocat"]`).
|
||||
- `state` (string, 선택): 상태 - 이슈의 변경된 상태를 지정합니다.
|
||||
- 옵션: `open`, `closed`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/get_issue_by_number">
|
||||
**설명:** GitHub에서 번호로 이슈를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다.
|
||||
- `issue_number` (string, 필수): 이슈 번호 - 가져올 이슈의 번호를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/lock_issue">
|
||||
**설명:** GitHub에서 이슈를 잠급니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다.
|
||||
- `issue_number` (string, 필수): 이슈 번호 - 잠글 이슈의 번호를 지정합니다.
|
||||
- `lock_reason` (string, 필수): 잠금 사유 - 이슈 또는 풀 리퀘스트 대화에 대한 잠금 이유를 지정합니다.
|
||||
- 옵션: `off-topic`, `too heated`, `resolved`, `spam`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/search_issue">
|
||||
**설명:** GitHub에서 이슈를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다.
|
||||
- `filter` (object, 필수): 불리언 표준형의 필터 - 단일 조건의 AND 그룹의 OR 조합.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "assignee",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "octocat"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `assignee`, `creator`, `mentioned`, `labels`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/create_release">
|
||||
**설명:** GitHub에 릴리스를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다.
|
||||
- `tag_name` (string, 필수): 이름 - 생성할 릴리스 태그의 이름을 지정합니다. (예시: "v1.0.0").
|
||||
- `target_commitish` (string, 선택): 대상 - 릴리스의 대상을 지정합니다. 브랜치 이름이나 커밋 SHA가 될 수 있으며, 기본값은 메인 브랜치입니다. (예시: "master").
|
||||
- `body` (string, 선택): 본문 - 이 릴리스에 대한 설명을 지정합니다.
|
||||
- `draft` (string, 선택): 초안 - 생성할 릴리스를 초안(비공개) 릴리스로 지정할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
- `prerelease` (string, 선택): 프리릴리스 - 생성할 릴리스를 프리릴리스로 지정할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
- `discussion_category_name` (string, 선택): 토론 카테고리 이름 - 지정 시, 해당 카테고리의 토론이 생성되어 릴리스와 연결됩니다. 값은 저장소에 이미 존재하는 카테고리여야 합니다.
|
||||
- `generate_release_notes` (string, 선택): 릴리스 노트 - 지정한 이름과 본문을 사용하여 릴리스 노트를 자동으로 생성할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/update_release">
|
||||
**설명:** GitHub에서 릴리스를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다.
|
||||
- `id` (string, 필수): 릴리스 ID - 업데이트할 릴리스의 ID를 지정합니다.
|
||||
- `tag_name` (string, 선택): 이름 - 업데이트할 릴리스 태그의 이름을 지정합니다. (예시: "v1.0.0").
|
||||
- `target_commitish` (string, 선택): 대상 - 릴리스의 대상을 지정합니다. 브랜치 이름이나 커밋 SHA가 될 수 있으며, 기본값은 메인 브랜치입니다. (예시: "master").
|
||||
- `body` (string, 선택): 본문 - 이 릴리스에 대한 설명을 지정합니다.
|
||||
- `draft` (string, 선택): 초안 - 생성할 릴리스를 초안(비공개) 릴리스로 지정할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
- `prerelease` (string, 선택): 프리릴리스 - 생성할 릴리스를 프리릴리스로 지정할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
- `discussion_category_name` (string, 선택): 토론 카테고리 이름 - 지정 시, 해당 카테고리의 토론이 생성되어 릴리스와 연결됩니다. 값은 저장소에 이미 존재하는 카테고리여야 합니다.
|
||||
- `generate_release_notes` (string, 선택): 릴리스 노트 - 지정한 이름과 본문을 사용하여 릴리스 노트를 자동으로 생성할지 여부를 지정합니다.
|
||||
- 옵션: `true`, `false`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/get_release_by_id">
|
||||
**설명:** GitHub에서 ID로 릴리스를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다.
|
||||
- `id` (string, 필수): 릴리스 ID - 조회할 릴리스의 ID를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/get_release_by_tag_name">
|
||||
**설명:** GitHub에서 태그 이름으로 릴리스를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다.
|
||||
- `tag_name` (string, 필수): 이름 - 가져올 릴리스의 태그를 지정합니다. (예시: "v1.0.0").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="github/delete_release">
|
||||
**설명:** GitHub에서 릴리스를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc").
|
||||
- `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다.
|
||||
- `id` (string, 필수): 릴리스 ID - 삭제할 릴리스의 ID를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 GitHub 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with GitHub capabilities
|
||||
github_agent = Agent(
|
||||
role="Repository Manager",
|
||||
goal="Manage GitHub repositories, issues, and releases efficiently",
|
||||
backstory="An AI assistant specialized in repository management and issue tracking.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# Task to create a new issue
|
||||
create_issue_task = Task(
|
||||
description="Create a bug report issue for the login functionality in the main repository",
|
||||
agent=github_agent,
|
||||
expected_output="Issue created successfully with issue number"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[github_agent],
|
||||
tasks=[create_issue_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 GitHub 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
issue_manager = Agent(
|
||||
role="Issue Manager",
|
||||
goal="Create and manage GitHub issues efficiently",
|
||||
backstory="An AI assistant that focuses on issue tracking and management.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# Task to manage issue workflow
|
||||
issue_workflow = Task(
|
||||
description="Create a feature request issue and assign it to the development team",
|
||||
agent=issue_manager,
|
||||
expected_output="Feature request issue created and assigned successfully"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[issue_manager],
|
||||
tasks=[issue_workflow]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 릴리즈 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
release_manager = Agent(
|
||||
role="Release Manager",
|
||||
goal="Manage software releases and versioning",
|
||||
backstory="An experienced release manager who handles version control and release processes.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# Task to create a new release
|
||||
release_task = Task(
|
||||
description="""
|
||||
Create a new release v2.1.0 for the project with:
|
||||
- Auto-generated release notes
|
||||
- Target the main branch
|
||||
- Include a description of new features and bug fixes
|
||||
""",
|
||||
agent=release_manager,
|
||||
expected_output="Release v2.1.0 created successfully with release notes"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[release_manager],
|
||||
tasks=[release_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 이슈 추적 및 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
project_coordinator = Agent(
|
||||
role="Project Coordinator",
|
||||
goal="Track and coordinate project issues and development progress",
|
||||
backstory="An AI assistant that helps coordinate development work and track project progress.",
|
||||
apps=['github']
|
||||
)
|
||||
|
||||
# Complex task involving multiple GitHub operations
|
||||
coordination_task = Task(
|
||||
description="""
|
||||
1. Search for all open issues assigned to the current milestone
|
||||
2. Identify overdue issues and update their priority labels
|
||||
3. Create a weekly progress report issue
|
||||
4. Lock resolved issues that have been inactive for 30 days
|
||||
""",
|
||||
agent=project_coordinator,
|
||||
expected_output="Project coordination completed with progress report and issue management"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[project_coordinator],
|
||||
tasks=[coordination_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
GitHub 통합 설정 또는 문제 해결에 대해 지원팀에 문의하세요.
|
||||
</Card>
|
||||
360
docs/edge/ko/enterprise/integrations/gmail.mdx
Normal file
360
docs/edge/ko/enterprise/integrations/gmail.mdx
Normal file
@@ -0,0 +1,360 @@
|
||||
---
|
||||
title: Gmail 연동
|
||||
description: "CrewAI를 위한 Gmail 연동을 통한 이메일 및 연락처 관리."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Gmail을 통해 이메일, 연락처, 임시 저장 메시지를 관리할 수 있도록 합니다. 이메일을 보내고, 메시지를 검색하며, 연락처를 관리하고, 임시 저장 메시지를 작성하며, AI 기반 자동화를 통해 이메일 커뮤니케이션을 효율화하세요.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
Gmail 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 권한이 있는 Gmail 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Gmail 계정 연결
|
||||
|
||||
## Gmail 연동 설정
|
||||
|
||||
### 1. Gmail 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Gmail**을 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다.
|
||||
4. 이메일 및 연락처 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="gmail/send_email">
|
||||
**설명:** Gmail에서 이메일을 보냅니다.
|
||||
|
||||
**파라미터:**
|
||||
- `toRecipients` (array, 필수): 받는 사람 - 하나의 문자열 또는 JSON 배열로 받는 사람을 지정합니다.
|
||||
```json
|
||||
[
|
||||
"recipient1@domain.com",
|
||||
"recipient2@domain.com"
|
||||
]
|
||||
```
|
||||
- `from` (string, 필수): 보내는 사람 - 발신자의 이메일을 지정합니다.
|
||||
- `subject` (string, 필수): 제목 - 메시지의 제목을 지정합니다.
|
||||
- `messageContent` (string, 필수): 메시지 내용 - 이메일 메시지의 내용을 일반 텍스트 또는 HTML로 지정합니다.
|
||||
- `attachments` (string, 선택): 첨부파일 - 단일 파일 객체 또는 파일 객체의 JSON 배열을 허용합니다.
|
||||
- `additionalHeaders` (object, 선택): 추가 헤더 - 추가 헤더 필드를 지정할 수 있습니다.
|
||||
```json
|
||||
{
|
||||
"reply-to": "Sender Name <sender@domain.com>"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/get_email_by_id">
|
||||
**설명:** Gmail에서 ID로 이메일을 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `userId` (string, 필수): 사용자 ID - 사용자의 이메일 주소를 지정합니다. (예: "user@domain.com").
|
||||
- `messageId` (string, 필수): 메시지 ID - 조회할 메시지의 ID를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/fetch_emails">
|
||||
**설명:** 고급 필터를 사용하여 Gmail에서 이메일을 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `emailFilterFormula` (object, 선택): 불리언 식(OR로 연결된 AND 그룹의 단일 조건)으로 된 필터.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "from",
|
||||
"operator": "$stringContains",
|
||||
"value": "example@domain.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `from`, `to`, `date`, `label`, `subject`, `cc`, `bcc`, `category`, `deliveredto:`, `size`, `filename`, `older_than`, `newer_than`, `list`, `is:important`, `is:unread`, `is:snoozed`, `is:starred`, `is:read`, `has:drive`, `has:document`, `has:spreadsheet`, `has:presentation`, `has:attachment`, `has:youtube`, `has:userlabels`
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "page_cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/delete_email">
|
||||
**설명:** Gmail에서 이메일을 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `userId` (string, 필수): 사용자 ID - 사용자의 이메일 주소를 지정합니다. (예: "user@domain.com").
|
||||
- `messageId` (string, 필수): 메시지 ID - 휴지통으로 보낼 메시지의 ID를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/create_a_contact">
|
||||
**설명:** Gmail에서 연락처를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `givenName` (string, 필수): 이름 - 생성할 연락처의 이름을 지정합니다. (예: "John").
|
||||
- `familyName` (string, 필수): 성 - 생성할 연락처의 성을 지정합니다. (예: "Doe").
|
||||
- `email` (string, 필수): 이메일 - 생성할 연락처의 이메일 주소를 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드 - 기타 연락처 정보를 입력할 수 있습니다.
|
||||
```json
|
||||
{
|
||||
"addresses": [
|
||||
{
|
||||
"streetAddress": "1000 North St.",
|
||||
"city": "Los Angeles"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/get_contact_by_resource_name">
|
||||
**설명:** Gmail에서 리소스 이름으로 연락처를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `resourceName` (string, 필수): 리소스 이름 - 조회할 연락처의 리소스 이름을 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/search_for_contact">
|
||||
**설명:** Gmail에서 연락처를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `searchTerm` (string, 필수): 검색어 - 이름, 닉네임, 이메일 주소, 전화번호 또는 조직 연락처 속성에서 유사하거나 정확히 일치하는 항목을 검색할 검색어를 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/delete_contact">
|
||||
**설명:** Gmail에서 연락처를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `resourceName` (string, 필수): 리소스 이름 - 삭제할 연락처의 리소스 이름을 지정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="gmail/create_draft">
|
||||
**설명:** Gmail에서 임시 저장 메일을 만듭니다.
|
||||
|
||||
**파라미터:**
|
||||
- `toRecipients` (array, 선택): 받는 사람 - 하나의 문자열 또는 JSON 배열로 받는 사람을 지정합니다.
|
||||
```json
|
||||
[
|
||||
"recipient1@domain.com",
|
||||
"recipient2@domain.com"
|
||||
]
|
||||
```
|
||||
- `from` (string, 선택): 보내는 사람 - 발신자의 이메일을 지정합니다.
|
||||
- `subject` (string, 선택): 제목 - 메시지의 제목을 지정합니다.
|
||||
- `messageContent` (string, 선택): 메시지 내용 - 이메일 메시지의 내용을 일반 텍스트 또는 HTML로 지정합니다.
|
||||
- `attachments` (string, 선택): 첨부파일 - 단일 파일 객체 또는 파일 객체의 JSON 배열을 허용합니다.
|
||||
- `additionalHeaders` (object, 선택): 추가 헤더 - 추가 헤더 필드를 지정할 수 있습니다.
|
||||
```json
|
||||
{
|
||||
"reply-to": "Sender Name <sender@domain.com>"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Gmail 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Gmail capabilities
|
||||
gmail_agent = Agent(
|
||||
role="Email Manager",
|
||||
goal="Manage email communications and contacts efficiently",
|
||||
backstory="An AI assistant specialized in email management and communication.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# Task to send a follow-up email
|
||||
send_email_task = Task(
|
||||
description="Send a follow-up email to john@example.com about the project update meeting",
|
||||
agent=gmail_agent,
|
||||
expected_output="Email sent successfully with confirmation"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[gmail_agent],
|
||||
tasks=[send_email_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Gmail 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
email_coordinator = Agent(
|
||||
role="Email Coordinator",
|
||||
goal="Coordinate email communications and manage drafts",
|
||||
backstory="An AI assistant that focuses on email coordination and draft management.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# Task to prepare and send emails
|
||||
email_coordination = Task(
|
||||
description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders",
|
||||
agent=email_coordinator,
|
||||
expected_output="Summary email sent to stakeholders"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[email_coordinator],
|
||||
tasks=[email_coordination]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 연락처 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
contact_manager = Agent(
|
||||
role="Contact Manager",
|
||||
goal="Manage and organize email contacts efficiently",
|
||||
backstory="An experienced contact manager who maintains organized contact databases.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# Task to manage contacts
|
||||
contact_task = Task(
|
||||
description="""
|
||||
1. 'example.com' 도메인에서 연락처를 검색합니다.
|
||||
2. 연락처 목록에 없는 최근 이메일 발신자에 대해 새 연락처를 생성합니다.
|
||||
3. 최근 상호 작용 데이터를 반영하여 연락처 정보를 업데이트합니다.
|
||||
""",
|
||||
agent=contact_manager,
|
||||
expected_output="새 연락처와 최근 상호 작용으로 연락처 데이터베이스가 업데이트됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[contact_manager],
|
||||
tasks=[contact_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 이메일 검색 및 분석
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
email_analyst = Agent(
|
||||
role="Email Analyst",
|
||||
goal="Analyze email patterns and provide insights",
|
||||
backstory="An AI assistant that analyzes email data to provide actionable insights.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# Task to analyze email patterns
|
||||
analysis_task = Task(
|
||||
description="""
|
||||
Search for all unread emails from the last 7 days,
|
||||
categorize them by sender domain,
|
||||
and create a summary report of communication patterns
|
||||
""",
|
||||
agent=email_analyst,
|
||||
expected_output="Email analysis report with communication patterns and recommendations"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[email_analyst],
|
||||
tasks=[analysis_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 이메일 워크플로우
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
workflow_manager = Agent(
|
||||
role="Email Workflow Manager",
|
||||
goal="Automate email workflows and responses",
|
||||
backstory="An AI assistant that manages automated email workflows and responses.",
|
||||
apps=['gmail']
|
||||
)
|
||||
|
||||
# Complex task involving multiple Gmail operations
|
||||
workflow_task = Task(
|
||||
description="""
|
||||
1. 지난 24시간 동안 제목에 'urgent'가 포함된 이메일 검색
|
||||
2. 각 긴급 이메일에 대한 답장 초안 생성
|
||||
3. 발신자에게 자동 확인 이메일 전송
|
||||
4. 주의가 필요한 긴급 항목의 요약 보고서 작성
|
||||
""",
|
||||
agent=workflow_manager,
|
||||
expected_output="긴급 이메일이 자동 응답 및 요약 보고서와 함께 처리됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[workflow_manager],
|
||||
tasks=[workflow_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Gmail 통합 설정 또는 문제 해결에 대한 지원이 필요하시다면 저희 지원팀에 문의해
|
||||
주세요.
|
||||
</Card>
|
||||
403
docs/edge/ko/enterprise/integrations/google_calendar.mdx
Normal file
403
docs/edge/ko/enterprise/integrations/google_calendar.mdx
Normal file
@@ -0,0 +1,403 @@
|
||||
---
|
||||
title: Google 캘린더 연동
|
||||
description: "CrewAI를 위한 Google 캘린더 연동을 통한 이벤트 및 일정 관리."
|
||||
icon: "calendar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Google Calendar를 통해 캘린더 이벤트, 일정, 가용 시간을 관리할 수 있도록 지원합니다. 이벤트를 생성 및 업데이트하고 참석자를 관리하며, 가용성을 확인하고 AI 기반 자동화로 일정 관리 워크플로우를 효율적으로 운영하세요.
|
||||
|
||||
## 필수 조건
|
||||
|
||||
Google Calendar 통합을 사용하기 전에 다음을 준비해야 합니다:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Calendar에 접근 가능한 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정을 연결 완료
|
||||
|
||||
## Google Calendar 연동 설정
|
||||
|
||||
### 1. Google 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Google Calendar**를 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 과정을 완료합니다.
|
||||
4. 캘린더 및 연락처 접근 권한을 허용합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_calendar/create_event">
|
||||
**설명:** Google 캘린더에 이벤트를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `eventName` (string, 필수): 이벤트 이름.
|
||||
- `startTime` (string, 필수): 시작 시간 - Unix 타임스탬프 또는 ISO8601 날짜 형식 허용.
|
||||
- `endTime` (string, 선택): 종료 시간 - 비워두면 시작 시간 기준 1시간 후로 기본 설정됩니다.
|
||||
- `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다.
|
||||
- `attendees` (string, 선택): 참석자 - 이메일 주소 배열 또는 쉼표로 구분된 이메일 주소 허용.
|
||||
- `eventLocation` (string, 선택): 이벤트 위치.
|
||||
- `eventDescription` (string, 선택): 이벤트 설명.
|
||||
- `eventId` (string, 선택): 이벤트 ID - 이 이벤트와 연결할 애플리케이션의 ID입니다. 이후 이 ID를 사용하여 이벤트를 동기화할 수 있습니다.
|
||||
- `includeMeetLink` (boolean, 선택): Google Meet 링크 포함 여부? - 이 이벤트에 대해 Google Meet 컨퍼런스 링크를 자동으로 생성합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/update_event">
|
||||
**설명:** Google 캘린더에서 기존 이벤트를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `eventId` (string, 필수): 이벤트 ID - 업데이트할 이벤트의 ID입니다.
|
||||
- `eventName` (string, 선택): 이벤트 이름.
|
||||
- `startTime` (string, 선택): 시작 시간 - Unix 타임스탬프 또는 ISO8601 날짜 형식 허용.
|
||||
- `endTime` (string, 선택): 종료 시간 - 비워두면 시작 시간 기준 1시간 후로 기본 설정됩니다.
|
||||
- `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다.
|
||||
- `attendees` (string, 선택): 참석자 - 이메일 주소 배열 또는 쉼표로 구분된 이메일 주소 허용.
|
||||
- `eventLocation` (string, 선택): 이벤트 위치.
|
||||
- `eventDescription` (string, 선택): 이벤트 설명.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/view_events">
|
||||
**설명:** Google 캘린더에서 이벤트 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다.
|
||||
- `after` (string, 선택): 이후 - 제공된 날짜 이후에 시작하는 이벤트를 필터링합니다 (밀리초 단위의 Unix 또는 ISO 타임스탬프). (예시: "2025-04-12T10:00:00Z 또는 1712908800000").
|
||||
- `before` (string, 선택): 이전 - 제공된 날짜 이전에 종료되는 이벤트를 필터링합니다 (밀리초 단위의 Unix 또는 ISO 타임스탬프). (예시: "2025-04-12T10:00:00Z 또는 1712908800000").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/get_event_by_id">
|
||||
**설명:** Google 캘린더에서 ID로 특정 이벤트를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `eventId` (string, 필수): 이벤트 ID.
|
||||
- `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/delete_event">
|
||||
**설명:** Google 캘린더에서 이벤트를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `eventId` (string, 필수): 이벤트 ID - 삭제할 캘린더 이벤트의 ID입니다.
|
||||
- `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/get_contacts">
|
||||
**설명:** Google 캘린더에서 연락처를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "page_cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/search_contacts">
|
||||
**설명:** Google 캘린더에서 연락처를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `query` (string, 선택): 연락처를 검색할 검색 쿼리.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/list_directory_people">
|
||||
**설명:** 디렉토리 구성원 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "page_cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/search_directory_people">
|
||||
**설명:** 디렉토리 구성원을 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `query` (string, 필수): 연락처를 검색할 검색 쿼리.
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "page_cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/list_other_contacts">
|
||||
**설명:** 기타 연락처 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "page_cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/search_other_contacts">
|
||||
**설명:** 기타 연락처를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `query` (string, 선택): 연락처를 검색할 검색 쿼리.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_calendar/get_availability">
|
||||
**설명:** 캘린더의 가용성 정보를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `timeMin` (string, 필수): 기간의 시작. ISO 형식.
|
||||
- `timeMax` (string, 필수): 기간의 끝. ISO 형식.
|
||||
- `timeZone` (string, 선택): 응답에 사용되는 시간대. 선택 사항입니다. 기본값은 UTC입니다.
|
||||
- `items` (array, 선택): 조회할 캘린더 및/또는 그룹 목록. 비워두면 사용자 기본 캘린더가 기본값입니다.
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "calendar_id_1"
|
||||
},
|
||||
{
|
||||
"id": "calendar_id_2"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 캘린더 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Google Calendar capabilities
|
||||
calendar_agent = Agent(
|
||||
role="Schedule Manager",
|
||||
goal="Manage calendar events and scheduling efficiently",
|
||||
backstory="An AI assistant specialized in calendar management and scheduling coordination.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# Task to create a meeting
|
||||
create_meeting_task = Task(
|
||||
description="Create a team standup meeting for tomorrow at 9 AM with the development team",
|
||||
agent=calendar_agent,
|
||||
expected_output="Meeting created successfully with Google Meet link"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[calendar_agent],
|
||||
tasks=[create_meeting_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 캘린더 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
meeting_coordinator = Agent(
|
||||
role="Meeting Coordinator",
|
||||
goal="Coordinate meetings and check availability",
|
||||
backstory="An AI assistant that focuses on meeting scheduling and availability management.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# Task to schedule a meeting with availability check
|
||||
schedule_meeting = Task(
|
||||
description="Check availability for next week and schedule a project review meeting with stakeholders",
|
||||
agent=meeting_coordinator,
|
||||
expected_output="Meeting scheduled after checking availability of all participants"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[meeting_coordinator],
|
||||
tasks=[schedule_meeting]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 이벤트 관리 및 업데이트
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
event_manager = Agent(
|
||||
role="Event Manager",
|
||||
goal="Manage and update calendar events efficiently",
|
||||
backstory="An experienced event manager who handles event logistics and updates.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# Task to manage event updates
|
||||
event_management = Task(
|
||||
description="""
|
||||
1. List all events for this week
|
||||
2. Update any events that need location changes to include video conference links
|
||||
3. Send calendar invitations to new team members for recurring meetings
|
||||
""",
|
||||
agent=event_manager,
|
||||
expected_output="Weekly events updated with proper locations and new attendees added"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[event_manager],
|
||||
tasks=[event_management]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 연락처 및 가용성 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
availability_coordinator = Agent(
|
||||
role="Availability Coordinator",
|
||||
goal="Coordinate availability and manage contacts for scheduling",
|
||||
backstory="An AI assistant that specializes in availability management and contact coordination.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# Task to coordinate availability
|
||||
availability_task = Task(
|
||||
description="""
|
||||
1. 엔지니어링 부서의 연락처를 검색합니다.
|
||||
2. 다음 주 금요일 오후에 모든 엔지니어의 가용성을 확인합니다.
|
||||
3. 가장 먼저 가능한 2시간 슬롯에 팀 미팅을 만듭니다.
|
||||
4. Google Meet 링크를 포함하고 초대장을 발송합니다.
|
||||
""",
|
||||
agent=availability_coordinator,
|
||||
expected_output="가용성에 따라 팀 미팅이 일정 예약되고 모든 엔지니어가 초대됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[availability_coordinator],
|
||||
tasks=[availability_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 일정 관리 워크플로우
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
scheduling_automator = Agent(
|
||||
role="Scheduling Automator",
|
||||
goal="Automate scheduling workflows and calendar management",
|
||||
backstory="An AI assistant that automates complex scheduling scenarios and calendar workflows.",
|
||||
apps=['google_calendar']
|
||||
)
|
||||
|
||||
# Complex scheduling automation task
|
||||
automation_task = Task(
|
||||
description="""
|
||||
1. 앞으로 2주간 예정된 모든 이벤트를 나열합니다.
|
||||
2. 일정 충돌 또는 연이어 배정된 미팅을 식별합니다.
|
||||
3. 가용 시간을 확인하여 최적의 미팅 시간을 제안합니다.
|
||||
4. 필요한 경우 미팅 사이에 버퍼 시간을 생성합니다.
|
||||
5. 아젠다 항목 및 미팅 링크가 포함된 이벤트 설명을 업데이트합니다.
|
||||
""",
|
||||
agent=scheduling_automator,
|
||||
expected_output="일정 충돌이 해결되고 버퍼 타임 및 미팅 세부 정보가 업데이트된 최적화된 캘린더"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[scheduling_automator],
|
||||
tasks=[automation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Google 계정에 캘린더 접근에 필요한 권한이 있는지 확인하세요
|
||||
- OAuth 연결에 Google Calendar API에 필요한 모든 범위가 포함되어 있는지 확인하세요
|
||||
- 캘린더 공유 설정이 필요한 접근 수준을 허용하는지 확인하세요
|
||||
|
||||
**이벤트 생성 문제**
|
||||
|
||||
- 시간 형식이 올바른지(ISO8601 또는 Unix 타임스탬프) 확인하세요
|
||||
- 참석자 이메일 주소가 올바르게 형식화되어 있는지 확인하세요
|
||||
- 대상 캘린더가 존재하며 접근 가능한지 확인하세요
|
||||
- 올바른 시간대가 지정되어 있는지 확인하세요
|
||||
|
||||
**가용성 및 시간 충돌**
|
||||
|
||||
- 가용성 확인 시 시간 범위에 올바른 ISO 형식을 사용하세요
|
||||
- 모든 작업에서 시간대가 일관성 있는지 확인하세요
|
||||
- 여러 캘린더를 확인할 때 캘린더 ID가 올바른지 확인하세요
|
||||
|
||||
**연락처 및 사용자 검색**
|
||||
|
||||
- 검색 쿼리가 올바르게 형식화되어 있는지 확인하세요
|
||||
- 디렉터리 접근 권한이 부여되었는지 확인하세요
|
||||
- 연락처 정보가 최신이며 접근 가능한지 확인하세요
|
||||
|
||||
**이벤트 업데이트 및 삭제**
|
||||
|
||||
- 이벤트 ID가 올바르며 이벤트가 존재하는지 확인하세요
|
||||
- 이벤트를 편집할 수 있는 권한이 있는지 확인하세요
|
||||
- 캘린더 소유권이 수정 작업을 허용하는지 확인하세요
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Calendar 연동 설정 또는 문제 해결에 대한 지원이 필요하면 저희 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
278
docs/edge/ko/enterprise/integrations/google_contacts.mdx
Normal file
278
docs/edge/ko/enterprise/integrations/google_contacts.mdx
Normal file
@@ -0,0 +1,278 @@
|
||||
---
|
||||
title: Google Contacts 통합
|
||||
description: "CrewAI를 위한 Google Contacts 통합으로 연락처 및 디렉토리 관리."
|
||||
icon: "address-book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Google Contacts를 통해 연락처와 디렉토리 정보를 관리할 수 있도록 합니다. 개인 연락처에 액세스하고, 디렉토리 사람들을 검색하고, 연락처 정보를 생성 및 업데이트하고, AI 기반 자동화로 연락처 그룹을 관리합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Google Contacts 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Contacts 액세스 권한이 있는 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결
|
||||
|
||||
## Google Contacts 통합 설정
|
||||
|
||||
### 1. Google 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Google Contacts** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 연락처 및 디렉토리 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_contacts/get_contacts">
|
||||
**설명:** Google Contacts에서 사용자의 연락처를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `pageSize` (integer, 선택사항): 반환할 연락처 수 (최대 1000). 최소: 1, 최대: 1000
|
||||
- `pageToken` (string, 선택사항): 검색할 페이지의 토큰.
|
||||
- `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers
|
||||
- `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false
|
||||
- `sortOrder` (string, 선택사항): 연결을 정렬할 순서. 옵션: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_contacts">
|
||||
**설명:** 쿼리 문자열을 사용하여 연락처를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `query` (string, 필수): 검색 쿼리 문자열
|
||||
- `readMask` (string, 필수): 읽을 필드 (예: 'names,emailAddresses,phoneNumbers')
|
||||
- `pageSize` (integer, 선택사항): 반환할 결과 수. 최소: 1, 최대: 30
|
||||
- `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
|
||||
- `sources` (array, 선택사항): 검색할 소스. 옵션: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. 기본값: READ_SOURCE_TYPE_CONTACT
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_directory_people">
|
||||
**설명:** 인증된 사용자의 디렉토리에 있는 사람들을 나열합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `sources` (array, 필수): 검색할 디렉토리 소스. 옵션: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. 기본값: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
|
||||
- `pageSize` (integer, 선택사항): 반환할 사람 수. 최소: 1, 최대: 1000
|
||||
- `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
|
||||
- `readMask` (string, 선택사항): 읽을 필드 (예: 'names,emailAddresses')
|
||||
- `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false
|
||||
- `mergeSources` (array, 선택사항): 디렉토리 사람 응답에 병합할 추가 데이터. 옵션: CONTACT
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_directory_people">
|
||||
**설명:** 디렉토리에서 사람을 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `query` (string, 필수): 검색 쿼리
|
||||
- `sources` (string, 필수): 디렉토리 소스 ('DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE' 사용)
|
||||
- `pageSize` (integer, 선택사항): 반환할 결과 수
|
||||
- `readMask` (string, 선택사항): 읽을 필드
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_other_contacts">
|
||||
**설명:** 기타 연락처를 나열합니다 (사용자의 개인 연락처에 없는).
|
||||
|
||||
**매개변수:**
|
||||
- `pageSize` (integer, 선택사항): 반환할 연락처 수. 최소: 1, 최대: 1000
|
||||
- `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
|
||||
- `readMask` (string, 선택사항): 읽을 필드
|
||||
- `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/search_other_contacts">
|
||||
**설명:** 기타 연락처를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `query` (string, 필수): 검색 쿼리
|
||||
- `readMask` (string, 필수): 읽을 필드 (예: 'names,emailAddresses')
|
||||
- `pageSize` (integer, 선택사항): 결과 수
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/get_person">
|
||||
**설명:** 리소스 이름으로 한 사람의 연락처 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 가져올 사람의 리소스 이름 (예: 'people/c123456789')
|
||||
- `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/create_contact">
|
||||
**설명:** 사용자의 주소록에 새 연락처를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `names` (array, 선택사항): 사람의 이름들. 각 항목은 `givenName` (string), `familyName` (string), `displayName` (string)이 있는 객체.
|
||||
- `emailAddresses` (array, 선택사항): 이메일 주소들. 각 항목은 `value` (string, 이메일 주소)와 `type` (string, 'home', 'work', 'other', 기본값 'other')이 있는 객체.
|
||||
- `phoneNumbers` (array, 선택사항): 전화번호들. 각 항목은 `value` (string, 전화번호)와 `type` (string, 'home', 'work', 'mobile', 'other', 기본값 'other')이 있는 객체.
|
||||
- `addresses` (array, 선택사항): 우편 주소들. 각 항목은 `formattedValue` (string, 형식화된 주소)와 `type` (string, 'home', 'work', 'other', 기본값 'other')이 있는 객체.
|
||||
- `organizations` (array, 선택사항): 조직/회사들. 각 항목은 `name` (string, 조직 이름), `title` (string, 직책), `type` (string, 'work', 'other', 기본값 'work')이 있는 객체.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/update_contact">
|
||||
**설명:** 기존 연락처의 정보를 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 업데이트할 사람의 리소스 이름 (예: 'people/c123456789').
|
||||
- `updatePersonFields` (string, 필수): 업데이트할 필드 (예: 'names,emailAddresses,phoneNumbers').
|
||||
- `names` (array, 선택사항): 사람의 이름들. 각 항목은 `givenName` (string), `familyName` (string), `displayName` (string)이 있는 객체.
|
||||
- `emailAddresses` (array, 선택사항): 이메일 주소들. 각 항목은 `value` (string, 이메일 주소)와 `type` (string, 'home', 'work', 'other')이 있는 객체.
|
||||
- `phoneNumbers` (array, 선택사항): 전화번호들. 각 항목은 `value` (string, 전화번호)와 `type` (string, 'home', 'work', 'mobile', 'other')이 있는 객체.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/delete_contact">
|
||||
**설명:** 사용자의 주소록에서 연락처를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 삭제할 사람의 리소스 이름 (예: 'people/c123456789').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/batch_get_people">
|
||||
**설명:** 한 번의 요청으로 여러 사람에 대한 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceNames` (array, 필수): 가져올 사람들의 리소스 이름 (최대 200개 항목).
|
||||
- `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/list_contact_groups">
|
||||
**설명:** 사용자의 연락처 그룹(라벨)을 나열합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `pageSize` (integer, 선택사항): 반환할 연락처 그룹 수. 최소: 1, 최대: 1000
|
||||
- `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰.
|
||||
- `groupFields` (string, 선택사항): 포함할 필드 (예: 'name,memberCount,clientData'). 기본값: name,memberCount
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/get_contact_group">
|
||||
**설명:** 리소스 이름으로 특정 연락처 그룹을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup').
|
||||
- `maxMembers` (integer, 선택사항): 포함할 최대 멤버 수. 최소: 0, 최대: 20000
|
||||
- `groupFields` (string, 선택사항): 포함할 필드 (예: 'name,memberCount,clientData'). 기본값: name,memberCount
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/create_contact_group">
|
||||
**설명:** 새 연락처 그룹(라벨)을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `name` (string, 필수): 연락처 그룹의 이름.
|
||||
- `clientData` (array, 선택사항): 클라이언트별 데이터. 각 항목은 `key` (string)와 `value` (string)가 있는 객체.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/update_contact_group">
|
||||
**설명:** 연락처 그룹의 정보를 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup').
|
||||
- `name` (string, 필수): 연락처 그룹의 이름.
|
||||
- `clientData` (array, 선택사항): 클라이언트별 데이터. 각 항목은 `key` (string)와 `value` (string)가 있는 객체.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_contacts/delete_contact_group">
|
||||
**설명:** 연락처 그룹을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `resourceName` (string, 필수): 삭제할 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup').
|
||||
- `deleteContacts` (boolean, 선택사항): 그룹 내 연락처도 삭제할지 여부. 기본값: false
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Google Contacts 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Google Contacts 기능을 가진 에이전트 생성
|
||||
contacts_agent = Agent(
|
||||
role="연락처 관리자",
|
||||
goal="Google Contacts를 효율적으로 관리",
|
||||
backstory="연락처 관리 및 조직 전문 AI 어시스턴트.",
|
||||
apps=['google_contacts'] # 모든 Google Contacts 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 새 연락처 생성 작업
|
||||
create_contact_task = Task(
|
||||
description="'김철수'라는 이름으로 이메일 'kim.chulsoo@example.com'과 전화번호 '010-1234-5678'로 새 연락처를 만드세요",
|
||||
agent=contacts_agent,
|
||||
expected_output="새 연락처가 성공적으로 생성됨"
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[contacts_agent],
|
||||
tasks=[create_contact_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Google 계정이 연락처 및 디렉토리 액세스에 필요한 권한을 가지고 있는지 확인하세요.
|
||||
- OAuth 연결이 Google People API에 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**연락처 생성/업데이트 문제**
|
||||
|
||||
- 연락처 생성 시 `email`과 같은 필수 필드가 제공되는지 확인하세요.
|
||||
- 연락처를 업데이트하거나 삭제할 때 `resourceName`이 올바른지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Contacts 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
481
docs/edge/ko/enterprise/integrations/google_docs.mdx
Normal file
481
docs/edge/ko/enterprise/integrations/google_docs.mdx
Normal file
@@ -0,0 +1,481 @@
|
||||
---
|
||||
title: Google Docs 통합
|
||||
description: "CrewAI를 위한 Google Docs 통합으로 문서 생성 및 편집."
|
||||
icon: "file-lines"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 텍스트 조작 및 서식을 사용하여 Google Docs 문서를 생성, 편집 및 관리할 수 있도록 합니다. AI 기반 자동화로 문서 생성을 자동화하고, 텍스트를 삽입 및 교체하고, 콘텐츠 범위를 관리하며, 문서 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Google Docs 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Docs 액세스 권한이 있는 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결
|
||||
|
||||
## Google Docs 통합 설정
|
||||
|
||||
### 1. Google 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Google Docs** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 문서 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_docs/create_document">
|
||||
**설명:** 새 Google 문서를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `title` (string, 선택사항): 새 문서의 제목.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/get_document">
|
||||
**설명:** Google 문서의 내용과 메타데이터를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 검색할 문서의 ID.
|
||||
- `includeTabsContent` (boolean, 선택사항): 탭 내용을 포함할지 여부. 기본값: false
|
||||
- `suggestionsViewMode` (string, 선택사항): 문서에 적용할 제안 보기 모드. 옵션: DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_SUGGESTIONS_ACCEPTED, PREVIEW_WITHOUT_SUGGESTIONS. 기본값: DEFAULT_FOR_CURRENT_ACCESS
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/batch_update">
|
||||
**설명:** Google 문서에 하나 이상의 업데이트를 적용합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `requests` (array, 필수): 문서에 적용할 업데이트 목록. 각 항목은 요청을 나타내는 객체.
|
||||
- `writeControl` (object, 선택사항): 쓰기 요청이 실행되는 방식을 제어합니다. `requiredRevisionId` (string)와 `targetRevisionId` (string)를 포함.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_text">
|
||||
**설명:** Google 문서의 특정 위치에 텍스트를 삽입합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `text` (string, 필수): 삽입할 텍스트.
|
||||
- `index` (integer, 선택사항): 텍스트를 삽입할 0 기반 인덱스. 기본값: 1
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/replace_text">
|
||||
**설명:** Google 문서에서 텍스트의 모든 인스턴스를 교체합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `containsText` (string, 필수): 찾아서 교체할 텍스트.
|
||||
- `replaceText` (string, 필수): 교체할 텍스트.
|
||||
- `matchCase` (boolean, 선택사항): 검색이 대소문자를 구분할지 여부. 기본값: false
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_content_range">
|
||||
**설명:** Google 문서의 특정 범위에서 내용을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `startIndex` (integer, 필수): 삭제할 범위의 시작 인덱스.
|
||||
- `endIndex` (integer, 필수): 삭제할 범위의 끝 인덱스.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_page_break">
|
||||
**설명:** Google 문서의 특정 위치에 페이지 나누기를 삽입합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `index` (integer, 선택사항): 페이지 나누기를 삽입할 0 기반 인덱스. 기본값: 1
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_named_range">
|
||||
**설명:** Google 문서에 명명된 범위를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 업데이트할 문서의 ID.
|
||||
- `name` (string, 필수): 명명된 범위의 이름.
|
||||
- `startIndex` (integer, 필수): 범위의 시작 인덱스.
|
||||
- `endIndex` (integer, 필수): 범위의 끝 인덱스.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_document_with_content">
|
||||
**설명:** 내용이 포함된 새 Google 문서를 한 번에 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `title` (string, 필수): 새 문서의 제목. 문서 상단과 Google Drive에 표시됩니다.
|
||||
- `content` (string, 선택사항): 문서에 삽입할 텍스트 내용. 새 단락에는 `\n`을 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/append_text">
|
||||
**설명:** Google 문서의 끝에 텍스트를 추가합니다. 인덱스를 지정할 필요 없이 자동으로 문서 끝에 삽입됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): create_document 응답 또는 URL에서 가져온 문서 ID.
|
||||
- `text` (string, 필수): 문서 끝에 추가할 텍스트. 새 단락에는 `\n`을 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_bold">
|
||||
**설명:** Google 문서에서 텍스트를 굵게 만들거나 굵게 서식을 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `bold` (boolean, 필수): 굵게 만들려면 `true`, 굵게를 제거하려면 `false`로 설정.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_italic">
|
||||
**설명:** Google 문서에서 텍스트를 기울임꼴로 만들거나 기울임꼴 서식을 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `italic` (boolean, 필수): 기울임꼴로 만들려면 `true`, 기울임꼴을 제거하려면 `false`로 설정.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_underline">
|
||||
**설명:** Google 문서에서 텍스트에 밑줄 서식을 추가하거나 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `underline` (boolean, 필수): 밑줄을 추가하려면 `true`, 밑줄을 제거하려면 `false`로 설정.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_strikethrough">
|
||||
**설명:** Google 문서에서 텍스트에 취소선 서식을 추가하거나 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `strikethrough` (boolean, 필수): 취소선을 추가하려면 `true`, 제거하려면 `false`로 설정.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_font_size">
|
||||
**설명:** Google 문서에서 텍스트의 글꼴 크기를 변경합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `fontSize` (number, 필수): 포인트 단위의 글꼴 크기. 일반적인 크기: 10, 11, 12, 14, 16, 18, 24, 36.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_text_color">
|
||||
**설명:** Google 문서에서 RGB 값(0-1 스케일)을 사용하여 텍스트 색상을 변경합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적).
|
||||
- `red` (number, 필수): 빨강 구성 요소 (0-1). 예: `1`은 완전한 빨강.
|
||||
- `green` (number, 필수): 초록 구성 요소 (0-1). 예: `0.5`는 절반 초록.
|
||||
- `blue` (number, 필수): 파랑 구성 요소 (0-1). 예: `0`은 파랑 없음.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_hyperlink">
|
||||
**설명:** Google 문서에서 기존 텍스트를 클릭 가능한 하이퍼링크로 변환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 링크로 만들 텍스트의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 링크로 만들 텍스트의 끝 위치 (배타적).
|
||||
- `url` (string, 필수): 링크가 가리킬 URL. 예: `"https://example.com"`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/apply_heading_style">
|
||||
**설명:** Google 문서에서 텍스트 범위에 제목 또는 단락 스타일을 적용합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 스타일을 적용할 단락의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 스타일을 적용할 단락의 끝 위치.
|
||||
- `style` (string, 필수): 적용할 스타일. 옵션: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_paragraph_alignment">
|
||||
**설명:** Google 문서에서 단락의 텍스트 정렬을 설정합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 정렬할 단락의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 정렬할 단락의 끝 위치.
|
||||
- `alignment` (string, 필수): 텍스트 정렬. 옵션: `START` (왼쪽), `CENTER`, `END` (오른쪽), `JUSTIFIED`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/set_line_spacing">
|
||||
**설명:** Google 문서에서 단락의 줄 간격을 설정합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 단락의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 단락의 끝 위치.
|
||||
- `lineSpacing` (number, 필수): 백분율로 나타낸 줄 간격. `100` = 단일, `115` = 1.15배, `150` = 1.5배, `200` = 이중.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_paragraph_bullets">
|
||||
**설명:** Google 문서에서 단락을 글머리 기호 또는 번호 매기기 목록으로 변환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 목록으로 변환할 단락의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 목록으로 변환할 단락의 끝 위치.
|
||||
- `bulletPreset` (string, 필수): 글머리 기호/번호 매기기 스타일. 옵션: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_paragraph_bullets">
|
||||
**설명:** Google 문서에서 단락의 글머리 기호 또는 번호 매기기를 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `startIndex` (integer, 필수): 목록 단락의 시작 위치.
|
||||
- `endIndex` (integer, 필수): 목록 단락의 끝 위치.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_with_content">
|
||||
**설명:** Google 문서에 내용이 포함된 표를 한 번에 삽입합니다. 내용은 2D 배열로 제공하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `rows` (integer, 필수): 표의 행 수.
|
||||
- `columns` (integer, 필수): 표의 열 수.
|
||||
- `index` (integer, 선택사항): 표를 삽입할 위치. 제공하지 않으면 문서 끝에 삽입됩니다.
|
||||
- `content` (array, 필수): 2D 배열로 된 표 내용. 각 내부 배열은 행입니다. 예: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_row">
|
||||
**설명:** 기존 표의 참조 셀 위 또는 아래에 새 행을 삽입합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스. get_document에서 가져오세요.
|
||||
- `rowIndex` (integer, 필수): 참조 셀의 행 인덱스 (0 기반).
|
||||
- `columnIndex` (integer, 선택사항): 참조 셀의 열 인덱스 (0 기반). 기본값: `0`.
|
||||
- `insertBelow` (boolean, 선택사항): `true`이면 참조 행 아래에, `false`이면 위에 삽입. 기본값: `true`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_table_column">
|
||||
**설명:** 기존 표의 참조 셀 왼쪽 또는 오른쪽에 새 열을 삽입합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스.
|
||||
- `rowIndex` (integer, 선택사항): 참조 셀의 행 인덱스 (0 기반). 기본값: `0`.
|
||||
- `columnIndex` (integer, 필수): 참조 셀의 열 인덱스 (0 기반).
|
||||
- `insertRight` (boolean, 선택사항): `true`이면 오른쪽에, `false`이면 왼쪽에 삽입. 기본값: `true`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_table_row">
|
||||
**설명:** Google 문서의 기존 표에서 행을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스.
|
||||
- `rowIndex` (integer, 필수): 삭제할 행 인덱스 (0 기반).
|
||||
- `columnIndex` (integer, 선택사항): 행의 아무 셀의 열 인덱스 (0 기반). 기본값: `0`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_table_column">
|
||||
**설명:** Google 문서의 기존 표에서 열을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스.
|
||||
- `rowIndex` (integer, 선택사항): 열의 아무 셀의 행 인덱스 (0 기반). 기본값: `0`.
|
||||
- `columnIndex` (integer, 필수): 삭제할 열 인덱스 (0 기반).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/merge_table_cells">
|
||||
**설명:** 표 셀 범위를 단일 셀로 병합합니다. 모든 셀의 내용이 보존됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스.
|
||||
- `rowIndex` (integer, 필수): 병합의 시작 행 인덱스 (0 기반).
|
||||
- `columnIndex` (integer, 필수): 병합의 시작 열 인덱스 (0 기반).
|
||||
- `rowSpan` (integer, 필수): 병합할 행 수.
|
||||
- `columnSpan` (integer, 필수): 병합할 열 수.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/unmerge_table_cells">
|
||||
**설명:** 이전에 병합된 표 셀을 개별 셀로 분리합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `tableStartIndex` (integer, 필수): 표의 시작 인덱스.
|
||||
- `rowIndex` (integer, 필수): 병합된 셀의 행 인덱스 (0 기반).
|
||||
- `columnIndex` (integer, 필수): 병합된 셀의 열 인덱스 (0 기반).
|
||||
- `rowSpan` (integer, 필수): 병합된 셀이 차지하는 행 수.
|
||||
- `columnSpan` (integer, 필수): 병합된 셀이 차지하는 열 수.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_inline_image">
|
||||
**설명:** 공개 URL에서 Google 문서에 이미지를 삽입합니다. 이미지는 공개적으로 접근 가능해야 하고, 50MB 미만이며, PNG/JPEG/GIF 형식이어야 합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `uri` (string, 필수): 이미지의 공개 URL. 인증 없이 접근 가능해야 합니다.
|
||||
- `index` (integer, 선택사항): 이미지를 삽입할 위치. 제공하지 않으면 문서 끝에 삽입됩니다. 기본값: `1`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/insert_section_break">
|
||||
**설명:** 서로 다른 서식을 가진 문서 섹션을 만들기 위해 섹션 나누기를 삽입합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `index` (integer, 필수): 섹션 나누기를 삽입할 위치.
|
||||
- `sectionType` (string, 필수): 섹션 나누기의 유형. 옵션: `CONTINUOUS` (같은 페이지에 유지), `NEXT_PAGE` (새 페이지 시작).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_header">
|
||||
**설명:** 문서의 머리글을 만듭니다. insert_text를 사용하여 머리글 내용을 추가할 수 있는 headerId를 반환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `type` (string, 선택사항): 머리글 유형. 옵션: `DEFAULT`. 기본값: `DEFAULT`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/create_footer">
|
||||
**설명:** 문서의 바닥글을 만듭니다. insert_text를 사용하여 바닥글 내용을 추가할 수 있는 footerId를 반환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `type` (string, 선택사항): 바닥글 유형. 옵션: `DEFAULT`. 기본값: `DEFAULT`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_header">
|
||||
**설명:** 문서에서 머리글을 삭제합니다. headerId를 찾으려면 get_document를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `headerId` (string, 필수): 삭제할 머리글 ID. get_document 응답에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_docs/delete_footer">
|
||||
**설명:** 문서에서 바닥글을 삭제합니다. footerId를 찾으려면 get_document를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `documentId` (string, 필수): 문서 ID.
|
||||
- `footerId` (string, 필수): 삭제할 바닥글 ID. get_document 응답에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Google Docs 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Google Docs 기능을 가진 에이전트 생성
|
||||
docs_agent = Agent(
|
||||
role="문서 작성자",
|
||||
goal="Google Docs 문서를 효율적으로 생성하고 관리",
|
||||
backstory="Google Docs 문서 생성 및 편집 전문 AI 어시스턴트.",
|
||||
apps=['google_docs'] # 모든 Google Docs 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 새 문서 생성 작업
|
||||
create_doc_task = Task(
|
||||
description="'프로젝트 상태 보고서'라는 제목으로 새 Google 문서를 만드세요",
|
||||
agent=docs_agent,
|
||||
expected_output="새 Google 문서 '프로젝트 상태 보고서'가 성공적으로 생성됨"
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[docs_agent],
|
||||
tasks=[create_doc_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Google 계정이 Google Docs 액세스에 필요한 권한을 가지고 있는지 확인하세요.
|
||||
- OAuth 연결이 필요한 모든 범위(`https://www.googleapis.com/auth/documents`)를 포함하는지 확인하세요.
|
||||
|
||||
**문서 ID 문제**
|
||||
|
||||
- 문서 ID가 올바른지 다시 확인하세요.
|
||||
- 문서가 존재하고 계정에서 액세스할 수 있는지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Docs 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
68
docs/edge/ko/enterprise/integrations/google_drive.mdx
Normal file
68
docs/edge/ko/enterprise/integrations/google_drive.mdx
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Google Drive 통합
|
||||
description: "CrewAI를 위한 Google Drive 통합으로 파일 및 폴더 관리."
|
||||
icon: "google"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Google Drive의 파일과 폴더에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 파일을 업로드, 다운로드, 콘텐츠 구성, 공유 링크 생성 및 클라우드 스토리지 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Google Drive 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Drive 액세스 권한이 있는 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결
|
||||
|
||||
## Google Drive 통합 설정
|
||||
|
||||
### 1. Google 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Google Drive**를 찾습니다.
|
||||
3. **연결**을 클릭하고 OAuth 과정을 완료합니다.
|
||||
4. 파일 및 폴더 관리에 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
자세한 매개변수 및 사용법은 [영어 문서](../../../en/enterprise/integrations/google_drive)를 참조하세요.
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Drive 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
325
docs/edge/ko/enterprise/integrations/google_sheets.mdx
Normal file
325
docs/edge/ko/enterprise/integrations/google_sheets.mdx
Normal file
@@ -0,0 +1,325 @@
|
||||
---
|
||||
title: Google Sheets 연동
|
||||
description: "CrewAI를 위한 Google Sheets 연동을 통해 스프레드시트 데이터 동기화."
|
||||
icon: "google"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Google Sheets를 통해 스프레드시트 데이터를 관리할 수 있도록 합니다. 행을 읽고, 새 항목을 생성하며, 기존 데이터를 업데이트하고, AI 기반 자동화를 통해 데이터 관리 워크플로우를 간소화하세요. 데이터 추적, 보고, 협업 데이터 관리에 최적화되어 있습니다.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
Google Sheets 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 되어 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Sheets에 액세스할 수 있는 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결
|
||||
- 데이터 작업을 위한 올바른 열 헤더가 있는 스프레드시트
|
||||
|
||||
## Google Sheets 통합 설정
|
||||
|
||||
### 1. Google 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **Google Sheets**를 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다.
|
||||
4. 스프레드시트 접근에 필요한 권한을 허용합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_sheets/get_values">
|
||||
**설명:** Google Sheets 스프레드시트에서 행을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다.
|
||||
- `limit` (string, 선택): 행 제한 - 반환할 최대 행 수를 제한합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_sheets/append_values">
|
||||
**설명:** Google Sheets 스프레드시트에 새로운 행을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다.
|
||||
- `worksheet` (string, 필수): 워크시트 - 워크시트에는 반드시 열 헤더가 있어야 합니다.
|
||||
- `additionalFields` (object, 필수): 필드 - 추가할 행의 필드를 열 이름을 key로 하는 객체로 포함합니다. Connect Portal Workflow Settings를 사용하여 사용자가 열 매핑을 선택할 수 있도록 합니다.
|
||||
```json
|
||||
{
|
||||
"columnName1": "columnValue1",
|
||||
"columnName2": "columnValue2",
|
||||
"columnName3": "columnValue3",
|
||||
"columnName4": "columnValue4"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_sheets/update_values">
|
||||
**설명:** Google Sheets 스프레드시트의 기존 행을 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다.
|
||||
- `worksheet` (string, 필수): 워크시트 - 워크시트에는 반드시 열 헤더가 있어야 합니다.
|
||||
- `filterFormula` (object, 선택): 필터 - 업데이트할 행을 식별하기 위한 단일 조건의 AND 그룹으로 이루어진 OR의 형태(분리 정규형)로 작성합니다.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "status",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "pending"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 연산자: `$stringContains`, `$stringDoesNotContain`, `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$numberGreaterThan`, `$numberLessThan`, `$numberEquals`, `$numberDoesNotEqual`, `$dateTimeAfter`, `$dateTimeBefore`, `$dateTimeEquals`, `$booleanTrue`, `$booleanFalse`, `$exists`, `$doesNotExist`
|
||||
- `additionalFields` (object, 필수): 필드 - 업데이트할 필드를 열 이름을 key로 하는 객체로 포함합니다. Connect Portal Workflow Settings를 사용하여 사용자가 열 매핑을 선택할 수 있도록 합니다.
|
||||
```json
|
||||
{
|
||||
"columnName1": "newValue1",
|
||||
"columnName2": "newValue2",
|
||||
"columnName3": "newValue3",
|
||||
"columnName4": "newValue4"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Google Sheets 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Google Sheets capabilities
|
||||
sheets_agent = Agent(
|
||||
role="Data Manager",
|
||||
goal="Manage spreadsheet data and track information efficiently",
|
||||
backstory="An AI assistant specialized in data management and spreadsheet operations.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# Task to add new data to a spreadsheet
|
||||
data_entry_task = Task(
|
||||
description="Add a new customer record to the customer database spreadsheet with name, email, and signup date",
|
||||
agent=sheets_agent,
|
||||
expected_output="New customer record added successfully to the spreadsheet"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[sheets_agent],
|
||||
tasks=[data_entry_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Google Sheets 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
data_collector = Agent(
|
||||
role="Data Collector",
|
||||
goal="Collect and organize data in spreadsheets",
|
||||
backstory="An AI assistant that focuses on data collection and organization.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# Task to collect and organize data
|
||||
data_collection = Task(
|
||||
description="Retrieve current inventory data and add new product entries to the inventory spreadsheet",
|
||||
agent=data_collector,
|
||||
expected_output="Inventory data retrieved and new products added successfully"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[data_collector],
|
||||
tasks=[data_collection]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 데이터 분석 및 보고
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
data_analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze spreadsheet data and generate insights",
|
||||
backstory="An experienced data analyst who extracts insights from spreadsheet data.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# Task to analyze data and create reports
|
||||
analysis_task = Task(
|
||||
description="""
|
||||
1. Retrieve all sales data from the current month's spreadsheet
|
||||
2. Analyze the data for trends and patterns
|
||||
3. Create a summary report in a new row with key metrics
|
||||
""",
|
||||
agent=data_analyst,
|
||||
expected_output="Sales data analyzed and summary report created with key insights"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[data_analyst],
|
||||
tasks=[analysis_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 데이터 업데이트
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
data_updater = Agent(
|
||||
role="Data Updater",
|
||||
goal="Automatically update and maintain spreadsheet data",
|
||||
backstory="An AI assistant that maintains data accuracy and updates records automatically.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# Task to update data based on conditions
|
||||
update_task = Task(
|
||||
description="""
|
||||
1. 주문 스프레드시트에서 모든 보류 중인 주문을 찾으세요
|
||||
2. 해당 주문의 상태를 'processing'으로 업데이트하세요
|
||||
3. 상태가 업데이트된 시점의 타임스탬프를 추가하세요
|
||||
4. 변경 사항을 별도의 추적 시트에 기록하세요
|
||||
""",
|
||||
agent=data_updater,
|
||||
expected_output="모든 보류 중인 주문이 processing 상태로 업데이트되고, 타임스탬프가 기록됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[data_updater],
|
||||
tasks=[update_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 복잡한 데이터 관리 워크플로우
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
workflow_manager = Agent(
|
||||
role="Data Workflow Manager",
|
||||
goal="Manage complex data workflows across multiple spreadsheets",
|
||||
backstory="An AI assistant that orchestrates complex data operations across multiple spreadsheets.",
|
||||
apps=['google_sheets']
|
||||
)
|
||||
|
||||
# Complex workflow task
|
||||
workflow_task = Task(
|
||||
description="""
|
||||
1. 메인 고객 스프레드시트에서 모든 고객 데이터를 가져옵니다
|
||||
2. 활성 고객에 대한 월별 요약 항목을 생성합니다
|
||||
3. 최근 30일간의 활동을 기반으로 고객 상태를 업데이트합니다
|
||||
4. 고객 지표가 포함된 월간 보고서를 생성합니다
|
||||
5. 비활성 고객 기록을 별도의 시트로 보관합니다
|
||||
""",
|
||||
agent=workflow_manager,
|
||||
expected_output="월간 고객 워크플로우가 완료되어 상태가 업데이트되고 보고서가 생성됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[workflow_manager],
|
||||
tasks=[workflow_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**권한 오류**
|
||||
|
||||
- Google 계정이 대상 스프레드시트에 대해 편집 권한이 있는지 확인하세요
|
||||
- OAuth 연결에 Google Sheets API에 필요한 scope가 포함되어 있는지 검증하세요
|
||||
- 스프레드시트가 인증된 계정과 공유되어 있는지 확인하세요
|
||||
|
||||
**스프레드시트 구조 문제**
|
||||
|
||||
- 행을 생성하거나 업데이트하기 전에 워크시트에 올바른 열 헤더가 있는지 확인하세요
|
||||
- `additionalFields`의 열 이름이 실제 열 헤더와 일치하는지 검증하세요
|
||||
- 지정된 워크시트가 스프레드시트에 존재하는지 확인하세요
|
||||
|
||||
**데이터 유형 및 형식 문제**
|
||||
|
||||
- 데이터 값이 각 열에 대해 예상되는 형식과 일치하는지 확인하세요
|
||||
- 날짜 열에는 올바른 날짜 형식(ISO 형식 권장)을 사용하세요
|
||||
- 숫자 열에 입력되는 값이 적절한 형식인지 검증하세요
|
||||
|
||||
**필터 수식 문제**
|
||||
|
||||
- 필터 수식이 부정 정규형(disjunctive normal form)의 올바른 JSON 구조를 따르는지 확인하세요
|
||||
- 실제 열 헤더와 일치하는 유효한 필드명을 사용하세요
|
||||
- 복잡한 다중 조건 쿼리를 작성하기 전에 간단한 필터로 테스트하세요
|
||||
- 연산자 유형이 열의 데이터 유형과 일치하는지 검증하세요
|
||||
|
||||
**행 제한 및 성능**
|
||||
|
||||
- `GOOGLE_SHEETS_GET_ROW`를 사용할 때 행 제한에 유의하세요
|
||||
- 대용량 데이터셋의 경우 페이지네이션을 고려하세요
|
||||
- 처리되는 데이터의 양을 줄이기 위해 구체적인 필터를 사용하세요
|
||||
|
||||
**업데이트 작업**
|
||||
|
||||
- 필터 조건이 업데이트하려는 행을 정확하게 식별하는지 확인하세요
|
||||
- 대규모 업데이트 전에 작은 데이터셋으로 필터 조건을 테스트하세요
|
||||
- 모든 필수 필드가 업데이트 작업에 포함되어 있는지 검증하세요
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Sheets 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 저희
|
||||
지원팀으로 문의해 주세요.
|
||||
</Card>
|
||||
340
docs/edge/ko/enterprise/integrations/google_slides.mdx
Normal file
340
docs/edge/ko/enterprise/integrations/google_slides.mdx
Normal file
@@ -0,0 +1,340 @@
|
||||
---
|
||||
title: Google Slides 통합
|
||||
description: "CrewAI를 위한 Google Slides 통합으로 프레젠테이션 생성 및 관리."
|
||||
icon: "chart-bar"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Google Slides 프레젠테이션을 생성, 편집 및 관리할 수 있도록 합니다. AI 기반 자동화로 프레젠테이션 생성을 자동화하고, 콘텐츠를 업데이트하고, Google Sheets에서 데이터를 가져오며, 프레젠테이션 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Google Slides 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Google Slides 액세스 권한이 있는 Google 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결
|
||||
|
||||
## Google Slides 통합 설정
|
||||
|
||||
### 1. Google 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Google Slides** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 프레젠테이션, 스프레드시트 및 드라이브 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="google_slides/create_blank_presentation">
|
||||
**설명:** 내용이 없는 빈 프레젠테이션을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `title` (string, 필수): 프레젠테이션의 제목.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation_metadata">
|
||||
**설명:** 프레젠테이션에 대한 가벼운 메타데이터(제목, 슬라이드 수, 슬라이드 ID)를 가져옵니다. 전체 콘텐츠를 가져오기 전에 먼저 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 검색할 프레젠테이션의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation_text">
|
||||
**설명:** 프레젠테이션에서 모든 텍스트 콘텐츠를 추출합니다. 슬라이드 ID와 도형 및 테이블의 텍스트만 반환합니다 (포맷팅 없음).
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_presentation">
|
||||
**설명:** ID로 프레젠테이션을 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 검색할 프레젠테이션의 ID.
|
||||
- `fields` (string, 선택사항): 응답에 포함할 필드. 성능 향상을 위해 필요한 데이터만 반환하는 데 사용.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/batch_update_presentation">
|
||||
**설명:** 프레젠테이션에 업데이트를 적용하거나 콘텐츠를 추가하거나 제거합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 업데이트할 프레젠테이션의 ID.
|
||||
- `requests` (array, 필수): 프레젠테이션에 적용할 업데이트 목록. 각 항목은 요청을 나타내는 객체.
|
||||
- `writeControl` (object, 선택사항): 쓰기 요청이 실행되는 방식을 제어합니다. `requiredRevisionId` (string)를 포함.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_slide_text">
|
||||
**설명:** 단일 슬라이드에서 텍스트 콘텐츠를 추출합니다. 도형 및 테이블의 텍스트만 반환합니다 (포맷팅 또는 스타일 없음).
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `pageObjectId` (string, 필수): 텍스트를 가져올 슬라이드/페이지의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_page">
|
||||
**설명:** ID로 특정 페이지를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `pageObjectId` (string, 필수): 검색할 페이지의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_thumbnail">
|
||||
**설명:** 페이지 썸네일을 생성합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `pageObjectId` (string, 필수): 썸네일 생성을 위한 페이지의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_slide">
|
||||
**설명:** 프레젠테이션에 추가 빈 슬라이드를 추가합니다. 새 프레젠테이션에는 이미 빈 슬라이드가 하나 있습니다. 먼저 get_presentation_metadata를 확인하세요. 제목/본문 영역이 있는 슬라이드는 create_slide_with_layout을 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `insertionIndex` (integer, 선택사항): 슬라이드를 삽입할 위치 (0 기반). 생략하면 맨 끝에 추가됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_slide_with_layout">
|
||||
**설명:** 제목, 본문 등의 플레이스홀더 영역이 있는 미리 정의된 레이아웃으로 슬라이드를 만듭니다. 구조화된 콘텐츠에는 create_slide보다 적합합니다. 생성 후 get_page로 플레이스홀더 ID를 찾고, 그 안에 텍스트를 삽입하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `layout` (string, 필수): 레이아웃 유형. 옵션: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. 제목+설명은 TITLE_AND_BODY, 제목만은 TITLE, 섹션 구분은 SECTION_HEADER가 적합합니다.
|
||||
- `insertionIndex` (integer, 선택사항): 삽입할 위치 (0 기반). 생략하면 맨 끝에 추가됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_text_box">
|
||||
**설명:** 콘텐츠가 있는 텍스트 상자를 슬라이드에 만듭니다. 제목, 설명, 단락에 사용합니다. 테이블에는 사용하지 마세요. 선택적으로 EMU 단위로 위치(x, y)와 크기(width, height)를 지정할 수 있습니다 (914400 EMU = 1 인치).
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 텍스트 상자를 추가할 슬라이드의 ID.
|
||||
- `text` (string, 필수): 텍스트 상자의 텍스트 내용.
|
||||
- `x` (integer, 선택사항): EMU 단위 X 위치 (914400 = 1 인치). 기본값: 914400 (왼쪽에서 1 인치).
|
||||
- `y` (integer, 선택사항): EMU 단위 Y 위치 (914400 = 1 인치). 기본값: 914400 (위에서 1 인치).
|
||||
- `width` (integer, 선택사항): EMU 단위 너비. 기본값: 7315200 (약 8 인치).
|
||||
- `height` (integer, 선택사항): EMU 단위 높이. 기본값: 914400 (약 1 인치).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/delete_slide">
|
||||
**설명:** 프레젠테이션에서 슬라이드를 제거합니다. 슬라이드 ID를 찾으려면 먼저 get_presentation을 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 삭제할 슬라이드의 객체 ID. get_presentation에서 가져옵니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/duplicate_slide">
|
||||
**설명:** 기존 슬라이드의 복사본을 만듭니다. 복사본은 원본 바로 다음에 삽입됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 복제할 슬라이드의 객체 ID. get_presentation에서 가져옵니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/move_slides">
|
||||
**설명:** 슬라이드를 새 위치로 이동하여 순서를 변경합니다. 슬라이드 ID는 현재 프레젠테이션 순서대로 있어야 합니다 (중복 없음).
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideIds` (string 배열, 필수): 이동할 슬라이드 ID 배열. 현재 프레젠테이션 순서대로 있어야 합니다.
|
||||
- `insertionIndex` (integer, 필수): 대상 위치 (0 기반). 0 = 맨 앞, 슬라이드 수 = 맨 끝.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/insert_youtube_video">
|
||||
**설명:** 슬라이드에 YouTube 동영상을 삽입합니다. 동영상 ID는 YouTube URL의 "v=" 다음 값입니다 (예: youtube.com/watch?v=abc123의 경우 "abc123" 사용).
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 동영상을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다.
|
||||
- `videoId` (string, 필수): YouTube 동영상 ID (URL의 v= 다음 값).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/insert_drive_video">
|
||||
**설명:** 슬라이드에 Google Drive의 동영상을 삽입합니다. 파일 ID는 Drive 파일 URL에서 찾을 수 있습니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 동영상을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다.
|
||||
- `fileId` (string, 필수): 동영상의 Google Drive 파일 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/set_slide_background_image">
|
||||
**설명:** 슬라이드의 배경 이미지를 설정합니다. 이미지 URL은 공개적으로 액세스 가능해야 합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 배경을 설정할 슬라이드의 ID. get_presentation에서 가져옵니다.
|
||||
- `imageUrl` (string, 필수): 배경으로 사용할 이미지의 공개적으로 액세스 가능한 URL.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_table">
|
||||
**설명:** 슬라이드에 빈 테이블을 만듭니다. 콘텐츠가 있는 테이블을 만들려면 create_table_with_content를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 테이블을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다.
|
||||
- `rows` (integer, 필수): 테이블의 행 수.
|
||||
- `columns` (integer, 필수): 테이블의 열 수.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/create_table_with_content">
|
||||
**설명:** 한 번의 작업으로 콘텐츠가 있는 테이블을 만듭니다. 콘텐츠는 2D 배열로 제공하며, 각 내부 배열은 행을 나타냅니다. 예: [["Header1", "Header2"], ["Row1Col1", "Row1Col2"]].
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `slideId` (string, 필수): 테이블을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다.
|
||||
- `rows` (integer, 필수): 테이블의 행 수.
|
||||
- `columns` (integer, 필수): 테이블의 열 수.
|
||||
- `content` (array, 필수): 2D 배열 형태의 테이블 콘텐츠. 각 내부 배열은 행입니다. 예: [["Year", "Revenue"], ["2023", "$10M"]].
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/import_data_from_sheet">
|
||||
**설명:** Google 시트에서 프레젠테이션으로 데이터를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `sheetId` (string, 필수): 가져올 Google 시트의 ID.
|
||||
- `dataRange` (string, 필수): 시트에서 가져올 데이터 범위.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/upload_file_to_drive">
|
||||
**설명:** 프레젠테이션과 연결된 Google 드라이브에 파일을 업로드합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file` (string, 필수): 업로드할 파일 데이터.
|
||||
- `presentationId` (string, 필수): 업로드된 파일을 연결할 프레젠테이션의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/link_file_to_presentation">
|
||||
**설명:** Google 드라이브의 파일을 프레젠테이션에 연결합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 프레젠테이션의 ID.
|
||||
- `fileId` (string, 필수): 연결할 파일의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/get_all_presentations">
|
||||
**설명:** 사용자가 액세스할 수 있는 모든 프레젠테이션을 나열합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `pageSize` (integer, 선택사항): 페이지당 반환할 프레젠테이션 수.
|
||||
- `pageToken` (string, 선택사항): 페이지네이션을 위한 토큰.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="google_slides/delete_presentation">
|
||||
**설명:** ID로 프레젠테이션을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `presentationId` (string, 필수): 삭제할 프레젠테이션의 ID.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Google Slides 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Google Slides 기능을 가진 에이전트 생성
|
||||
slides_agent = Agent(
|
||||
role="프레젠테이션 작성자",
|
||||
goal="Google Slides 프레젠테이션을 효율적으로 생성하고 관리",
|
||||
backstory="프레젠테이션 디자인 및 콘텐츠 관리 전문 AI 어시스턴트.",
|
||||
apps=['google_slides'] # 모든 Google Slides 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 새 프레젠테이션 생성 작업
|
||||
create_presentation_task = Task(
|
||||
description="'분기별 매출 보고서'라는 제목으로 새 빈 프레젠테이션을 만드세요",
|
||||
agent=slides_agent,
|
||||
expected_output="새 프레젠테이션 '분기별 매출 보고서'가 성공적으로 생성됨"
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[slides_agent],
|
||||
tasks=[create_presentation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Google 계정이 Google Slides 및 Google Drive 액세스에 필요한 권한을 가지고 있는지 확인하세요.
|
||||
- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**프레젠테이션/페이지 ID 문제**
|
||||
|
||||
- 프레젠테이션 ID와 페이지 객체 ID가 올바른지 다시 확인하세요.
|
||||
- 프레젠테이션이나 페이지가 존재하고 액세스할 수 있는지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Google Slides 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
619
docs/edge/ko/enterprise/integrations/hubspot.mdx
Normal file
619
docs/edge/ko/enterprise/integrations/hubspot.mdx
Normal file
@@ -0,0 +1,619 @@
|
||||
---
|
||||
title: "HubSpot 연동"
|
||||
description: "CrewAI로 HubSpot에서 회사 및 연락처를 관리하세요."
|
||||
icon: "briefcase"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 HubSpot 내에서 회사 및 연락처를 관리할 수 있도록 지원합니다. 새로운 레코드를 생성하고 AI 기반 자동화로 CRM 프로세스를 효율화하세요.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
HubSpot 통합을 사용하기 전에 다음을 확인하세요.
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 권한이 있는 HubSpot 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 HubSpot 계정이 연결되어 있음
|
||||
|
||||
## HubSpot 통합 설정
|
||||
|
||||
### 1. HubSpot 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합 섹션에서 **HubSpot**을 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다.
|
||||
4. 회사 및 연락처 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 액션
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="hubspot/create_company">
|
||||
**설명:** HubSpot에서 새로운 회사 레코드를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `name` (string, 필수): 회사명.
|
||||
- `domain` (string, 선택): 회사 도메인명.
|
||||
- `industry` (string, 선택): 산업군. HubSpot에서 미리 정의된 값 중 하나여야 합니다.
|
||||
- `phone` (string, 선택): 전화번호.
|
||||
- `hubspot_owner_id` (string, 선택): 회사 소유자 ID.
|
||||
- `type` (string, 선택): 회사 유형. 사용 가능한 값: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`.
|
||||
- `city` (string, 선택): 도시.
|
||||
- `state` (string, 선택): 주/지역.
|
||||
- `zip` (string, 선택): 우편번호.
|
||||
- `numberofemployees` (number, 선택): 직원 수.
|
||||
- `annualrevenue` (number, 선택): 연간 매출.
|
||||
- `timezone` (string, 선택): 시간대.
|
||||
- `description` (string, 선택): 설명.
|
||||
- `linkedin_company_page` (string, 선택): LinkedIn 회사 페이지 URL.
|
||||
- `company_email` (string, 선택): 회사 이메일.
|
||||
- `first_name` (string, 선택): 회사 연락처의 이름.
|
||||
- `last_name` (string, 선택): 회사 연락처의 성.
|
||||
- `about_us` (string, 선택): 회사 소개.
|
||||
- `hs_csm_sentiment` (string, 선택): CSM 만족도. 사용 가능한 값: `at_risk`, `neutral`, `healthy`.
|
||||
- `closedate` (string, 선택): 마감일.
|
||||
- `hs_keywords` (string, 선택): 회사 키워드. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `country` (string, 선택): 국가/지역.
|
||||
- `hs_country_code` (string, 선택): 국가/지역 코드.
|
||||
- `hs_employee_range` (string, 선택): 직원 범위.
|
||||
- `facebook_company_page` (string, 선택): Facebook 회사 페이지 URL.
|
||||
- `facebookfans` (number, 선택): Facebook 팬 수.
|
||||
- `hs_gps_coordinates` (string, 선택): GPS 좌표.
|
||||
- `hs_gps_error` (string, 선택): GPS 오류.
|
||||
- `googleplus_page` (string, 선택): Google Plus 페이지 URL.
|
||||
- `owneremail` (string, 선택): HubSpot 소유자 이메일.
|
||||
- `ownername` (string, 선택): HubSpot 소유자 이름.
|
||||
- `hs_ideal_customer_profile` (string, 선택): 이상적인 고객 프로필 티어. 사용 가능한 값: `tier_1`, `tier_2`, `tier_3`.
|
||||
- `hs_industry_group` (string, 선택): 산업 그룹.
|
||||
- `is_public` (boolean, 선택): 공개 여부.
|
||||
- `hs_last_metered_enrichment_timestamp` (string, 선택): 마지막 enrichment 타임스탬프.
|
||||
- `hs_lead_status` (string, 선택): 리드 상태. 사용 가능한 값: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`.
|
||||
- `lifecyclestage` (string, 선택): 라이프사이클 단계. 사용 가능한 값: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`.
|
||||
- `linkedinbio` (string, 선택): LinkedIn 바이오.
|
||||
- `hs_linkedin_handle` (string, 선택): LinkedIn 핸들.
|
||||
- `hs_live_enrichment_deadline` (string, 선택): 라이브 enrichment 기한.
|
||||
- `hs_logo_url` (string, 선택): 로고 URL.
|
||||
- `hs_analytics_source` (string, 선택): 원래 유입 경로.
|
||||
- `hs_pinned_engagement_id` (number, 선택): 고정된 참여 ID.
|
||||
- `hs_quick_context` (string, 선택): 간략한 컨텍스트.
|
||||
- `hs_revenue_range` (string, 선택): 매출 범위.
|
||||
- `hs_state_code` (string, 선택): 주/지역 코드.
|
||||
- `address` (string, 선택): 거리 주소.
|
||||
- `address2` (string, 선택): 거리 주소 2.
|
||||
- `hs_is_target_account` (boolean, 선택): 타깃 계정 여부.
|
||||
- `hs_target_account` (string, 선택): 타깃 계정 티어. 사용 가능한 값: `tier_1`, `tier_2`, `tier_3`.
|
||||
- `hs_target_account_recommendation_snooze_time` (string, 선택): 타깃 계정 추천 일시중지 시간.
|
||||
- `hs_target_account_recommendation_state` (string, 선택): 타깃 계정 추천 상태. 사용 가능한 값: `DISMISSED`, `NONE`, `SNOOZED`.
|
||||
- `total_money_raised` (string, 선택): 총 조달 금액.
|
||||
- `twitterbio` (string, 선택): 트위터 바이오.
|
||||
- `twitterfollowers` (number, 선택): 트위터 팔로워 수.
|
||||
- `twitterhandle` (string, 선택): 트위터 핸들.
|
||||
- `web_technologies` (string, 선택): 사용한 웹 기술. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `website` (string, 선택): 웹사이트 URL.
|
||||
- `founded_year` (string, 선택): 설립 연도.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/create_contact">
|
||||
**설명:** HubSpot에서 새로운 연락처 레코드를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `email` (string, 필수): 연락처 이메일 주소.
|
||||
- `firstname` (string, 선택): 이름.
|
||||
- `lastname` (string, 선택): 성.
|
||||
- `phone` (string, 선택): 전화번호.
|
||||
- `hubspot_owner_id` (string, 선택): 연락처 소유자.
|
||||
- `lifecyclestage` (string, 선택): 라이프사이클 단계. 사용 가능한 값: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`.
|
||||
- `hs_lead_status` (string, 선택): 리드 상태. 사용 가능한 값: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`.
|
||||
- `annualrevenue` (string, 선택): 연간 매출.
|
||||
- `hs_buying_role` (string, 선택): 구매 역할.
|
||||
- `cc_emails` (string, 선택): 참조(CC) 이메일.
|
||||
- `ch_customer_id` (string, 선택): Chargify 고객 ID.
|
||||
- `ch_customer_reference` (string, 선택): Chargify 고객 참조.
|
||||
- `chargify_sites` (string, 선택): Chargify 사이트(들).
|
||||
- `city` (string, 선택): 도시.
|
||||
- `hs_facebook_ad_clicked` (boolean, 선택): Facebook 광고 클릭 여부.
|
||||
- `hs_linkedin_ad_clicked` (string, 선택): LinkedIn 광고 클릭 여부.
|
||||
- `hs_clicked_linkedin_ad` (string, 선택): LinkedIn 광고 클릭 여부.
|
||||
- `closedate` (string, 선택): 마감일.
|
||||
- `company` (string, 선택): 회사명.
|
||||
- `company_size` (string, 선택): 회사 규모.
|
||||
- `country` (string, 선택): 국가/지역.
|
||||
- `hs_country_region_code` (string, 선택): 국가/지역 코드.
|
||||
- `date_of_birth` (string, 선택): 생년월일.
|
||||
- `degree` (string, 선택): 학위.
|
||||
- `hs_email_customer_quarantined_reason` (string, 선택): 이메일 주소 격리 사유.
|
||||
- `hs_role` (string, 선택): 고용 역할. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `hs_seniority` (string, 선택): 고용 직급. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `hs_sub_role` (string, 선택): 고용 하위 역할. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `hs_employment_change_detected_date` (string, 선택): 고용 변경 감지 날짜.
|
||||
- `hs_enriched_email_bounce_detected` (boolean, 선택): 향상된 이메일 바운스 감지됨.
|
||||
- `hs_facebookid` (string, 선택): Facebook ID.
|
||||
- `hs_facebook_click_id` (string, 선택): Facebook 클릭 ID.
|
||||
- `fax` (string, 선택): 팩스번호.
|
||||
- `field_of_study` (string, 선택): 전공.
|
||||
- `followercount` (number, 선택): 팔로워 수.
|
||||
- `gender` (string, 선택): 성별.
|
||||
- `hs_google_click_id` (string, 선택): Google 광고 클릭 ID.
|
||||
- `graduation_date` (string, 선택): 졸업 날짜.
|
||||
- `owneremail` (string, 선택): HubSpot 소유자 이메일(레거시).
|
||||
- `ownername` (string, 선택): HubSpot 소유자 이름(레거시).
|
||||
- `industry` (string, 선택): 산업군.
|
||||
- `hs_inferred_language_codes` (string, 선택): 추정 언어 코드. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `jobtitle` (string, 선택): 직책.
|
||||
- `hs_job_change_detected_date` (string, 선택): 직장 변경 감지 날짜.
|
||||
- `job_function` (string, 선택): 직무.
|
||||
- `hs_journey_stage` (string, 선택): 여정 단계. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `kloutscoregeneral` (number, 선택): Klout 점수.
|
||||
- `hs_last_metered_enrichment_timestamp` (string, 선택): 마지막 enrichment 타임스탬프.
|
||||
- `hs_latest_source` (string, 선택): 최신 유입 경로.
|
||||
- `hs_latest_source_timestamp` (string, 선택): 최신 유입 경로 날짜.
|
||||
- `hs_legal_basis` (string, 선택): 연락처 데이터 처리를 위한 법적 근거.
|
||||
- `linkedinbio` (string, 선택): LinkedIn 바이오.
|
||||
- `linkedinconnections` (number, 선택): LinkedIn 연결 수.
|
||||
- `hs_linkedin_url` (string, 선택): LinkedIn URL.
|
||||
- `hs_linkedinid` (string, 선택): LinkedIn ID.
|
||||
- `hs_live_enrichment_deadline` (string, 선택): 라이브 enrichment 기한.
|
||||
- `marital_status` (string, 선택): 결혼 상태.
|
||||
- `hs_content_membership_email` (string, 선택): 멤버 이메일.
|
||||
- `hs_content_membership_notes` (string, 선택): 멤버십 노트.
|
||||
- `message` (string, 선택): 메시지.
|
||||
- `military_status` (string, 선택): 군복무 상태.
|
||||
- `mobilephone` (string, 선택): 휴대전화 번호.
|
||||
- `numemployees` (string, 선택): 직원 수.
|
||||
- `hs_analytics_source` (string, 선택): 원래 유입 경로.
|
||||
- `photo` (string, 선택): 사진.
|
||||
- `hs_pinned_engagement_id` (number, 선택): 고정된 참여 ID.
|
||||
- `zip` (string, 선택): 우편번호.
|
||||
- `hs_language` (string, 선택): 선호 언어. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `associatedcompanyid` (number, 선택): 기본 연결된 회사 ID.
|
||||
- `hs_email_optout_survey_reason` (string, 선택): 이메일 수신 거부 사유.
|
||||
- `relationship_status` (string, 선택): 관계 상태.
|
||||
- `hs_returning_to_office_detected_date` (string, 선택): 사무실 복귀 감지 날짜.
|
||||
- `salutation` (string, 선택): 호칭.
|
||||
- `school` (string, 선택): 학교.
|
||||
- `seniority` (string, 선택): 직급.
|
||||
- `hs_feedback_show_nps_web_survey` (boolean, 선택): NPS 웹 설문조사를 표시할지 여부.
|
||||
- `start_date` (string, 선택): 시작일.
|
||||
- `state` (string, 선택): 주/지역.
|
||||
- `hs_state_code` (string, 선택): 주/지역 코드.
|
||||
- `hs_content_membership_status` (string, 선택): 상태.
|
||||
- `address` (string, 선택): 거리 주소.
|
||||
- `tax_exempt` (string, 선택): 세금 면제.
|
||||
- `hs_timezone` (string, 선택): 시간대. 미리 정의된 값 중 하나여야 합니다.
|
||||
- `twitterbio` (string, 선택): 트위터 바이오.
|
||||
- `hs_twitterid` (string, 선택): 트위터 ID.
|
||||
- `twitterprofilephoto` (string, 선택): 트위터 프로필 사진.
|
||||
- `twitterhandle` (string, 선택): 트위터 사용자명.
|
||||
- `vat_number` (string, 선택): 부가가치세 번호.
|
||||
- `ch_verified` (string, 선택): ACH/eCheck 결제 인증됨.
|
||||
- `website` (string, 선택): 웹사이트 URL.
|
||||
- `hs_whatsapp_phone_number` (string, 선택): WhatsApp 전화번호.
|
||||
- `work_email` (string, 선택): 업무용 이메일.
|
||||
- `hs_googleplusid` (string, 선택): googleplus ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/create_deal">
|
||||
**설명:** HubSpot에서 새로운 거래(deal) 레코드를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `dealname` (string, 필수): 거래 이름.
|
||||
- `amount` (number, 선택): 거래 금액.
|
||||
- `dealstage` (string, 선택): 거래의 파이프라인 단계.
|
||||
- `pipeline` (string, 선택): 거래가 속한 파이프라인.
|
||||
- `closedate` (string, 선택): 예상 마감일.
|
||||
- `hubspot_owner_id` (string, 선택): 거래 소유자.
|
||||
- `dealtype` (string, 선택): 거래 유형. 사용 가능한 값: `newbusiness`, `existingbusiness`.
|
||||
- `description` (string, 선택): 거래 설명.
|
||||
- `hs_priority` (string, 선택): 거래 우선순위. 사용 가능한 값: `low`, `medium`, `high`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/create_record_engagements">
|
||||
**설명:** HubSpot에서 새로운 참여(예: 노트, 이메일, 통화, 미팅, 작업)를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `engagementType` (string, 필수): 참여 유형. 사용 가능한 값: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`.
|
||||
- `hubspot_owner_id` (string, 선택): 이 활동이 할당된 사용자.
|
||||
- `hs_timestamp` (string, 선택): 활동 날짜 및 시간.
|
||||
- `hs_note_body` (string, 선택): 노트 본문. (`NOTE`에서 사용)
|
||||
- `hs_task_subject` (string, 선택): 작업 제목. (`TASK`에서 사용)
|
||||
- `hs_task_body` (string, 선택): 작업 노트. (`TASK`에서 사용)
|
||||
- `hs_task_status` (string, 선택): 작업 상태. (`TASK`에서 사용)
|
||||
- `hs_meeting_title` (string, 선택): 미팅 제목. (`MEETING`에서 사용)
|
||||
- `hs_meeting_body` (string, 선택): 미팅 설명. (`MEETING`에서 사용)
|
||||
- `hs_meeting_start_time` (string, 선택): 미팅 시작 시간. (`MEETING`에서 사용)
|
||||
- `hs_meeting_end_time` (string, 선택): 미팅 종료 시간. (`MEETING`에서 사용)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/update_company">
|
||||
**설명:** HubSpot에서 기존 회사 레코드를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 업데이트할 회사의 ID.
|
||||
- `name` (string, 선택): 회사명.
|
||||
- `domain` (string, 선택): 회사 도메인명.
|
||||
- `industry` (string, 선택): 산업군.
|
||||
- `phone` (string, 선택): 전화번호.
|
||||
- `city` (string, 선택): 도시.
|
||||
- `state` (string, 선택): 주/지역.
|
||||
- `zip` (string, 선택): 우편번호.
|
||||
- `numberofemployees` (number, 선택): 직원 수.
|
||||
- `annualrevenue` (number, 선택): 연간 매출.
|
||||
- `description` (string, 선택): 설명.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/create_record_any">
|
||||
**설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID.
|
||||
- 추가 파라미터는 커스텀 오브젝트의 스키마에 따라 다릅니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/update_contact">
|
||||
**설명:** HubSpot에서 기존 연락처 레코드를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 업데이트할 연락처의 ID.
|
||||
- `firstname` (string, 선택): 이름.
|
||||
- `lastname` (string, 선택): 성.
|
||||
- `email` (string, 선택): 이메일 주소.
|
||||
- `phone` (string, 선택): 전화번호.
|
||||
- `company` (string, 선택): 회사명.
|
||||
- `jobtitle` (string, 선택): 직책.
|
||||
- `lifecyclestage` (string, 선택): 라이프사이클 단계.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/update_deal">
|
||||
**설명:** HubSpot에서 기존 거래 레코드를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 업데이트할 거래의 ID.
|
||||
- `dealname` (string, 선택): 거래 이름.
|
||||
- `amount` (number, 선택): 거래 금액.
|
||||
- `dealstage` (string, 선택): 거래의 파이프라인 단계.
|
||||
- `pipeline` (string, 선택): 거래가 속한 파이프라인.
|
||||
- `closedate` (string, 선택): 예상 마감일.
|
||||
- `dealtype` (string, 선택): 거래 유형.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/update_record_engagements">
|
||||
**설명:** HubSpot에서 기존 참여(engagement)를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 업데이트할 참여의 ID.
|
||||
- `hs_note_body` (string, 선택): 노트 본문.
|
||||
- `hs_task_subject` (string, 선택): 작업 제목.
|
||||
- `hs_task_body` (string, 선택): 작업 노트.
|
||||
- `hs_task_status` (string, 선택): 작업 상태.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/update_record_any">
|
||||
**설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 업데이트할 레코드의 ID.
|
||||
- `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID.
|
||||
- 추가 파라미터는 커스텀 오브젝트의 스키마에 따라 다릅니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/list_companies">
|
||||
**설명:** HubSpot에서 회사 레코드 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/list_contacts">
|
||||
**설명:** HubSpot에서 연락처 레코드 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/list_deals">
|
||||
**설명:** HubSpot에서 거래 레코드 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_records_engagements">
|
||||
**설명:** HubSpot에서 참여(engagement) 레코드 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `objectName` (string, 필수): 가져올 참여 유형(예: "notes").
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_records_any">
|
||||
**설명:** HubSpot에서 지정된 오브젝트 타입의 레코드 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_company">
|
||||
**설명:** ID로 단일 회사 레코드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 가져올 회사의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_contact">
|
||||
**설명:** ID로 단일 연락처 레코드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 가져올 연락처의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_deal">
|
||||
**설명:** ID로 단일 거래 레코드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 가져올 거래의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_record_by_id_engagements">
|
||||
**설명:** ID로 단일 참여(engagement) 레코드를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 가져올 참여의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_record_by_id_any">
|
||||
**설명:** 지정된 오브젝트 타입의 단일 레코드를 ID로 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID.
|
||||
- `recordId` (string, 필수): 가져올 레코드의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/search_companies">
|
||||
**설명:** 필터 수식을 사용해 HubSpot에서 회사 레코드를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/search_contacts">
|
||||
**설명:** 필터 수식을 사용해 HubSpot에서 연락처 레코드를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/search_deals">
|
||||
**설명:** 필터 수식을 사용해 HubSpot에서 거래 레코드를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/search_records_engagements">
|
||||
**설명:** 필터 수식을 사용해 HubSpot에서 참여(engagement) 레코드를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `engagementFilterFormula` (object, 선택): 참여 필터.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/search_records_any">
|
||||
**설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 검색할 오브젝트 타입 ID.
|
||||
- `filterFormula` (string, 선택): 적용할 필터 수식.
|
||||
- `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/delete_record_companies">
|
||||
**설명:** ID로 회사 레코드를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 삭제할 회사의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/delete_record_contacts">
|
||||
**설명:** ID로 연락처 레코드를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 삭제할 연락처의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/delete_record_deals">
|
||||
**설명:** ID로 거래 레코드를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 삭제할 거래의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/delete_record_engagements">
|
||||
**설명:** ID로 참여(engagement) 레코드를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordId` (string, 필수): 삭제할 참여의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/delete_record_any">
|
||||
**설명:** 지정된 오브젝트 타입의 레코드를 ID로 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID.
|
||||
- `recordId` (string, 필수): 삭제할 레코드의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/get_contacts_by_list_id">
|
||||
**설명:** 지정된 리스트 ID로부터 연락처 목록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `listId` (string, 필수): 연락처를 가져올 리스트의 ID.
|
||||
- `paginationParameters` (object, 선택): 이후 페이지를 위해 `pageCursor` 사용.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="hubspot/describe_action_schema">
|
||||
**설명:** 특정 오브젝트 타입 및 작업에 대한 예상 스키마를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `recordType` (string, 필수): 오브젝트 타입 ID(예: 'companies').
|
||||
- `operation` (string, 필수): 작업 유형(예: 'CREATE_RECORD').
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 HubSpot 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with HubSpot capabilities
|
||||
hubspot_agent = Agent(
|
||||
role="CRM Manager",
|
||||
goal="Manage company and contact records in HubSpot",
|
||||
backstory="An AI assistant specialized in CRM management.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# Task to create a new company
|
||||
create_company_task = Task(
|
||||
description="Create a new company in HubSpot with name 'Innovate Corp' and domain 'innovatecorp.com'.",
|
||||
agent=hubspot_agent,
|
||||
expected_output="Company created successfully with confirmation"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[hubspot_agent],
|
||||
tasks=[create_company_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 HubSpot 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
# Get only the tool to create contacts
|
||||
actions_list=["hubspot/create_contact"]
|
||||
)
|
||||
|
||||
contact_creator = Agent(
|
||||
role="Contact Creator",
|
||||
goal="Create new contacts in HubSpot",
|
||||
backstory="An AI assistant that focuses on creating new contact entries in the CRM.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# Task to create a contact
|
||||
create_contact = Task(
|
||||
description="Create a new contact for 'John Doe' with email 'john.doe@example.com'.",
|
||||
agent=contact_creator,
|
||||
expected_output="Contact created successfully in HubSpot."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[contact_creator],
|
||||
tasks=[create_contact]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 연락처 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
crm_manager = Agent(
|
||||
role="CRM Manager",
|
||||
goal="Manage and organize HubSpot contacts efficiently.",
|
||||
backstory="An experienced CRM manager who maintains an organized contact database.",
|
||||
apps=['hubspot']
|
||||
)
|
||||
|
||||
# Task to manage contacts
|
||||
contact_task = Task(
|
||||
description="Create a new contact for 'Jane Smith' at 'Global Tech Inc.' with email 'jane.smith@globaltech.com'.",
|
||||
agent=crm_manager,
|
||||
expected_output="Contact database updated with the new contact."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[crm_manager],
|
||||
tasks=[contact_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
HubSpot 연동 설정 또는 문제 해결에 도움이 필요하시면 지원팀에 문의해 주세요.
|
||||
</Card>
|
||||
407
docs/edge/ko/enterprise/integrations/jira.mdx
Normal file
407
docs/edge/ko/enterprise/integrations/jira.mdx
Normal file
@@ -0,0 +1,407 @@
|
||||
---
|
||||
title: Jira 연동
|
||||
description: "CrewAI를 위한 Jira 연동을 통한 이슈 추적 및 프로젝트 관리."
|
||||
icon: "bug"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Jira를 통해 이슈, 프로젝트, 워크플로우를 관리할 수 있도록 합니다. 이슈를 생성 및 업데이트하고, 프로젝트 진행 상황을 추적하며, 할당 작업을 관리하고, AI 기반 자동화로 프로젝트 관리를 효율화하세요.
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
Jira 통합을 사용하기 전에 다음을 준비하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 프로젝트 권한이 있는 Jira 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Jira 계정 연결
|
||||
|
||||
## Jira 연동 설정
|
||||
|
||||
### 1. Jira 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. **Jira**를 인증 통합 섹션에서 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 절차를 완료합니다.
|
||||
4. 이슈 및 프로젝트 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="jira/create_issue">
|
||||
**설명:** Jira에서 이슈를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `summary` (string, 필수): 요약 - 이슈에 대한 간단한 한 줄 요약입니다. (예시: "프린터가 작동을 멈췄습니다").
|
||||
- `project` (string, 선택): 프로젝트 - 이슈가 속한 프로젝트입니다. 제공되지 않으면 사용자의 첫 번째 프로젝트로 기본 설정됩니다. 사용자가 프로젝트를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요.
|
||||
- `issueType` (string, 선택): 이슈 유형 - 제공되지 않으면 기본값은 Task입니다.
|
||||
- `jiraIssueStatus` (string, 선택): 상태 - 제공되지 않으면 프로젝트의 첫 번째 상태가 기본입니다.
|
||||
- `assignee` (string, 선택): 담당자 - 제공되지 않으면 인증된 사용자로 기본 설정됩니다.
|
||||
- `descriptionType` (string, 선택): 설명 유형 - 설명 유형을 선택하세요.
|
||||
- 옵션: `description`, `descriptionJSON`
|
||||
- `description` (string, 선택): 설명 - 이슈에 대한 자세한 설명입니다. 이 필드는 'descriptionType'이 'description'일 때만 나타납니다.
|
||||
- `additionalFields` (string, 선택): 추가 필드 - 포함해야 하는 다른 필드를 JSON 형식으로 지정하세요. 사용자가 업데이트할 이슈 필드를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요.
|
||||
```json
|
||||
{
|
||||
"customfield_10001": "value"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/update_issue">
|
||||
**설명:** Jira에서 이슈를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueKey` (string, 필수): 이슈 키 (예시: "TEST-1234").
|
||||
- `summary` (string, 선택): 요약 - 이슈에 대한 간단한 한 줄 요약입니다. (예시: "프린터가 작동을 멈췄습니다").
|
||||
- `issueType` (string, 선택): 이슈 유형 - 사용자가 이슈 유형을 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요.
|
||||
- `jiraIssueStatus` (string, 선택): 상태 - 사용자가 상태를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요.
|
||||
- `assignee` (string, 선택): 담당자 - 사용자가 담당자를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요.
|
||||
- `descriptionType` (string, 선택): 설명 유형 - 설명 유형을 선택하세요.
|
||||
- 옵션: `description`, `descriptionJSON`
|
||||
- `description` (string, 선택): 설명 - 이슈에 대한 자세한 설명입니다. 이 필드는 'descriptionType'이 'description'일 때만 나타납니다.
|
||||
- `additionalFields` (string, 선택): 추가 필드 - 포함해야 하는 다른 필드를 JSON 형식으로 지정하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_issue_by_key">
|
||||
**설명:** Jira에서 키로 이슈를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueKey` (string, 필수): 이슈 키 (예시: "TEST-1234").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/filter_issues">
|
||||
**설명:** 필터를 사용하여 Jira에서 이슈를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `jqlQuery` (object, 선택): 불리언 합정규형(OR의 AND 그룹)으로 구성된 필터.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "status",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "Open"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 연산자: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`
|
||||
- `limit` (string, 선택): 결과 제한 - 반환되는 최대 이슈 수를 제한합니다. 입력하지 않으면 기본값은 10입니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/search_by_jql">
|
||||
**설명:** Jira에서 JQL로 이슈를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `jqlQuery` (string, 필수): JQL 쿼리 (예시: "project = PROJECT").
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 결과를 위한 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/update_issue_any">
|
||||
**설명:** Jira에서 임의의 이슈를 업데이트합니다. 이 기능의 속성 스키마를 얻으려면 DESCRIBE_ACTION_SCHEMA를 사용하세요.
|
||||
|
||||
**파라미터:** 특정 파라미터 없음 - 예상 스키마를 먼저 확인하려면 JIRA_DESCRIBE_ACTION_SCHEMA를 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/describe_action_schema">
|
||||
**설명:** 이슈 유형에 대한 예상 스키마를 가져옵니다. 사용하려는 이슈 유형과 일치하는 다른 기능이 없을 경우 먼저 이 기능을 사용하세요.
|
||||
|
||||
**파라미터:**
|
||||
- `issueTypeId` (string, 필수): 이슈 유형 ID.
|
||||
- `projectKey` (string, 필수): 프로젝트 키.
|
||||
- `operation` (string, 필수): 작업 유형 값(예: CREATE_ISSUE 또는 UPDATE_ISSUE).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_projects">
|
||||
**설명:** Jira에서 프로젝트를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `paginationParameters` (object, 선택): 페이지네이션 파라미터.
|
||||
```json
|
||||
{
|
||||
"pageCursor": "cursor_string"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_issue_types_by_project">
|
||||
**설명:** Jira에서 프로젝트별 이슈 유형을 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `project` (string, 필수): 프로젝트 키.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_issue_types">
|
||||
**설명:** Jira에서 모든 이슈 유형을 조회합니다.
|
||||
|
||||
**파라미터:** 필요 없음.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_issue_status_by_project">
|
||||
**설명:** 주어진 프로젝트의 이슈 상태를 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `project` (string, 필수): 프로젝트 키.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="jira/get_all_assignees_by_project">
|
||||
**설명:** 주어진 프로젝트의 담당자 목록을 조회합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `project` (string, 필수): 프로젝트 키.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Jira 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Jira capabilities
|
||||
jira_agent = Agent(
|
||||
role="Issue Manager",
|
||||
goal="Manage Jira issues and track project progress efficiently",
|
||||
backstory="An AI assistant specialized in issue tracking and project management.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# Task to create a bug report
|
||||
create_bug_task = Task(
|
||||
description="Create a bug report for the login functionality with high priority and assign it to the development team",
|
||||
agent=jira_agent,
|
||||
expected_output="Bug report created successfully with issue key"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[jira_agent],
|
||||
tasks=[create_bug_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Jira 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
issue_coordinator = Agent(
|
||||
role="Issue Coordinator",
|
||||
goal="Create and manage Jira issues efficiently",
|
||||
backstory="An AI assistant that focuses on issue creation and management.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# Task to manage issue workflow
|
||||
issue_workflow = Task(
|
||||
description="Create a feature request issue and update the status of related issues",
|
||||
agent=issue_coordinator,
|
||||
expected_output="Feature request created and related issues updated"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[issue_coordinator],
|
||||
tasks=[issue_workflow]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 프로젝트 분석 및 보고
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
project_analyst = Agent(
|
||||
role="Project Analyst",
|
||||
goal="Analyze project data and generate insights from Jira",
|
||||
backstory="An experienced project analyst who extracts insights from project management data.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# Task to analyze project status
|
||||
analysis_task = Task(
|
||||
description="""
|
||||
1. Get all projects and their issue types
|
||||
2. Search for all open issues across projects
|
||||
3. Analyze issue distribution by status and assignee
|
||||
4. Create a summary report issue with findings
|
||||
""",
|
||||
agent=project_analyst,
|
||||
expected_output="Project analysis completed with summary report created"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[project_analyst],
|
||||
tasks=[analysis_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 이슈 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
automation_manager = Agent(
|
||||
role="Automation Manager",
|
||||
goal="Automate issue management and workflow processes",
|
||||
backstory="An AI assistant that automates repetitive issue management tasks.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# Task to automate issue management
|
||||
automation_task = Task(
|
||||
description="""
|
||||
1. Search for all unassigned issues using JQL
|
||||
2. Get available assignees for each project
|
||||
3. Automatically assign issues based on workload and expertise
|
||||
4. Update issue priorities based on age and type
|
||||
5. Create weekly sprint planning issues
|
||||
""",
|
||||
agent=automation_manager,
|
||||
expected_output="Issues automatically assigned and sprint planning issues created"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[automation_manager],
|
||||
tasks=[automation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 고급 스키마 기반 작업
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
schema_specialist = Agent(
|
||||
role="Schema Specialist",
|
||||
goal="Handle complex Jira operations using dynamic schemas",
|
||||
backstory="An AI assistant that can work with dynamic Jira schemas and custom issue types.",
|
||||
apps=['jira']
|
||||
)
|
||||
|
||||
# Task using schema-based operations
|
||||
schema_task = Task(
|
||||
description="""
|
||||
1. 모든 프로젝트와 해당 커스텀 이슈 유형을 가져옵니다
|
||||
2. 각 커스텀 이슈 유형에 대해, 액션 스키마를 설명합니다
|
||||
3. 복잡한 커스텀 필드를 위한 동적 스키마를 사용해 이슈를 생성합니다
|
||||
4. 비즈니스 규칙에 따라 커스텀 필드 값을 사용해 이슈를 업데이트합니다
|
||||
""",
|
||||
agent=schema_specialist,
|
||||
expected_output="동적 스키마를 사용하여 커스텀 이슈가 생성되고 업데이트됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[schema_specialist],
|
||||
tasks=[schema_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**권한 오류**
|
||||
|
||||
- Jira 계정이 대상 프로젝트에 필요한 권한을 가지고 있는지 확인하세요
|
||||
- OAuth 연결에 Jira API에 필요한 범위가 포함되어 있는지 확인하세요
|
||||
- 지정된 프로젝트에서 이슈 생성/편집 권한이 있는지 확인하세요
|
||||
|
||||
**잘못된 프로젝트 또는 이슈 키**
|
||||
|
||||
- 프로젝트 키와 이슈 키가 올바른 형식(예: "PROJ-123")인지 다시 확인하세요
|
||||
- 프로젝트가 존재하며 계정으로 접근 가능한지 확인하세요
|
||||
- 이슈 키가 실제로 존재하는 이슈를 참조하는지 확인하세요
|
||||
|
||||
**이슈 유형 및 상태 관련 문제**
|
||||
|
||||
- 프로젝트에 대한 유효한 이슈 유형을 얻으려면 JIRA_GET_ISSUE_TYPES_BY_PROJECT를 사용하세요
|
||||
- 유효한 상태를 얻으려면 JIRA_GET_ISSUE_STATUS_BY_PROJECT를 사용하세요
|
||||
- 이슈 유형과 상태가 대상 프로젝트에 제공되는지 확인하세요
|
||||
|
||||
**JQL 쿼리 문제**
|
||||
|
||||
- API 호출에 사용하기 전에 Jira의 이슈 검색에서 JQL 쿼리를 테스트하세요
|
||||
- JQL에 사용된 필드명이 정확하게 철자되어 있고, Jira 인스턴스에 존재하는지 확인하세요
|
||||
- 복잡한 쿼리에는 올바른 JQL 문법을 사용하세요
|
||||
|
||||
**커스텀 필드 및 스키마 문제**
|
||||
|
||||
- 복잡한 이슈 유형에 대해 올바른 스키마를 얻으려면 JIRA_DESCRIBE_ACTION_SCHEMA를 사용하세요
|
||||
- 커스텀 필드 ID가 정확한지 확인하세요 (예: "customfield_10001")
|
||||
- 커스텀 필드가 대상 프로젝트와 이슈 유형에서 사용 가능한지 확인하세요
|
||||
|
||||
**필터 공식 문제**
|
||||
|
||||
- 필터 공식이 올바른 JSON 구조(불리언 합의 정규형)를 따르는지 확인하세요
|
||||
- Jira 구성에 존재하는 유효한 필드명을 사용하세요
|
||||
- 복잡한 다중 조건 쿼리를 만들기 전에 간단한 필터를 테스트하세요
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Jira 연동 설정 또는 문제 해결에 대한 지원이 필요하시면 저희 지원팀에
|
||||
문의하십시오.
|
||||
</Card>
|
||||
467
docs/edge/ko/enterprise/integrations/linear.mdx
Normal file
467
docs/edge/ko/enterprise/integrations/linear.mdx
Normal file
@@ -0,0 +1,467 @@
|
||||
---
|
||||
title: Linear 연동
|
||||
description: "CrewAI를 위한 Linear 연동을 통한 소프트웨어 프로젝트 및 버그 추적."
|
||||
icon: "list-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Linear를 통해 이슈, 프로젝트, 개발 워크플로우를 관리할 수 있도록 지원합니다. 이슈를 생성 및 업데이트하고, 프로젝트 타임라인을 관리하며, 팀을 조직하고, AI 기반 자동화로 소프트웨어 개발 프로세스를 간소화할 수 있습니다.
|
||||
|
||||
## 필수 조건
|
||||
|
||||
Linear 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 워크스페이스 권한이 있는 Linear 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)에서 Linear 계정 연결
|
||||
|
||||
## 리니어 통합 설정
|
||||
|
||||
### 1. Linear 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합( Authentication Integrations ) 섹션에서 **Linear**를 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 절차를 완료합니다.
|
||||
4. 이슈 및 프로젝트 관리를 위한 필수 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="linear/create_issue">
|
||||
**설명:** Linear에서 새로운 이슈를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `teamId` (string, 필수): 팀 ID - 이 새로운 이슈의 상위 팀 ID를 지정합니다. Connect Portal Workflow Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요. (예: "a70bdf0f-530a-4887-857d-46151b52b47c").
|
||||
- `title` (string, 필수): 제목 - 이 이슈의 제목을 지정합니다.
|
||||
- `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다.
|
||||
- `statusId` (string, 선택): 상태 - 이 이슈의 상태를 지정합니다.
|
||||
- `priority` (string, 선택): 우선순위 - 이 이슈의 우선순위를 정수로 지정합니다.
|
||||
- `dueDate` (string, 선택): 마감일 - 이 이슈의 마감일을 ISO 8601 형식으로 지정합니다.
|
||||
- `cycleId` (string, 선택): 사이클 ID - 이 이슈가 속한 사이클을 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드.
|
||||
```json
|
||||
{
|
||||
"assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c",
|
||||
"labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"]
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/update_issue">
|
||||
**설명:** Linear에서 이슈를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueId` (string, 필수): 이슈 ID - 업데이트할 이슈의 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
|
||||
- `title` (string, 선택): 제목 - 이 이슈의 제목을 지정합니다.
|
||||
- `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다.
|
||||
- `statusId` (string, 선택): 상태 - 이 이슈의 상태를 지정합니다.
|
||||
- `priority` (string, 선택): 우선순위 - 이 이슈의 우선순위를 정수로 지정합니다.
|
||||
- `dueDate` (string, 선택): 마감일 - 이 이슈의 마감일을 ISO 8601 형식으로 지정합니다.
|
||||
- `cycleId` (string, 선택): 사이클 ID - 이 이슈가 속한 사이클을 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드.
|
||||
```json
|
||||
{
|
||||
"assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c",
|
||||
"labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"]
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/get_issue_by_id">
|
||||
**설명:** Linear에서 ID로 이슈를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueId` (string, 필수): 이슈 ID - 가져올 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/get_issue_by_issue_identifier">
|
||||
**설명:** Linear에서 이슈 식별자로 이슈를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `externalId` (string, 필수): 외부 ID - 가져올 이슈의 사람이 읽을 수 있는 이슈 식별자를 지정합니다. (예: "ABC-1").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/search_issue">
|
||||
**설명:** Linear에서 이슈를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `queryTerm` (string, 필수): 검색어 - 찾을 검색어입니다.
|
||||
- `issueFilterFormula` (object, 선택): 부정합적 정규형(DNF)의 필터 - 단일 조건의 AND 그룹들에 대한 OR.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "title",
|
||||
"operator": "$stringContains",
|
||||
"value": "bug"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `title`, `number`, `project`, `createdAt`
|
||||
사용 가능한 연산자: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`, `$numberGreaterThanOrEqualTo`, `$numberLessThanOrEqualTo`, `$numberGreaterThan`, `$numberLessThan`, `$dateTimeAfter`, `$dateTimeBefore`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/delete_issue">
|
||||
**설명:** Linear에서 이슈를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueId` (string, 필수): 이슈 ID - 삭제할 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/archive_issue">
|
||||
**설명:** Linear에서 이슈를 아카이브합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `issueId` (string, 필수): 이슈 ID - 아카이브할 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/create_sub_issue">
|
||||
**설명:** Linear에서 하위 이슈를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `parentId` (string, 필수): 상위 ID - 이 새로운 이슈의 상위 이슈 ID를 지정합니다.
|
||||
- `teamId` (string, 필수): 팀 ID - 이 새로운 하위 이슈의 상위 팀 ID를 지정합니다. Connect Portal Workflow Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요. (예: "a70bdf0f-530a-4887-857d-46151b52b47c").
|
||||
- `title` (string, 필수): 제목 - 이 이슈의 제목을 지정합니다.
|
||||
- `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드.
|
||||
```json
|
||||
{
|
||||
"lead": "linear_user_id"
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/create_project">
|
||||
**설명:** Linear에서 새로운 프로젝트를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `teamIds` (object, 필수): 팀 ID - 이 프로젝트와 연관된 팀 ID 혹은 팀 ID의 JSON 배열을 문자열로 지정합니다. Connect Portal User Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요.
|
||||
```json
|
||||
[
|
||||
"a70bdf0f-530a-4887-857d-46151b52b47c",
|
||||
"4ac7..."
|
||||
]
|
||||
```
|
||||
- `projectName` (string, 필수): 프로젝트 이름 - 프로젝트의 이름을 지정합니다. (예: "My Linear Project").
|
||||
- `description` (string, 선택): 프로젝트 설명 - 프로젝트에 대한 설명을 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드.
|
||||
```json
|
||||
{
|
||||
"state": "planned",
|
||||
"description": ""
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/update_project">
|
||||
**설명:** Linear에서 프로젝트를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `projectId` (string, 필수): 프로젝트 ID - 업데이트할 프로젝트의 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b").
|
||||
- `projectName` (string, 선택): 프로젝트 이름 - 업데이트할 프로젝트의 이름을 지정합니다. (예: "My Linear Project").
|
||||
- `description` (string, 선택): 프로젝트 설명 - 프로젝트에 대한 설명을 지정합니다.
|
||||
- `additionalFields` (object, 선택): 추가 필드.
|
||||
```json
|
||||
{
|
||||
"state": "planned",
|
||||
"description": ""
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/get_project_by_id">
|
||||
**설명:** Linear에서 ID로 프로젝트를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `projectId` (string, 필수): 프로젝트 ID - 가져올 프로젝트의 프로젝트 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/delete_project">
|
||||
**설명:** Linear에서 프로젝트를 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `projectId` (string, 필수): 프로젝트 ID - 삭제할 프로젝트의 프로젝트 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="linear/search_teams">
|
||||
**설명:** Linear에서 팀을 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `teamFilterFormula` (object, 선택): 부정합적 정규형(DNF)의 필터 - 단일 조건의 AND 그룹들에 대한 OR.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "name",
|
||||
"operator": "$stringContains",
|
||||
"value": "Engineering"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `id`, `name`
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Linear 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Linear capabilities
|
||||
linear_agent = Agent(
|
||||
role="Development Manager",
|
||||
goal="Manage Linear issues and track development progress efficiently",
|
||||
backstory="An AI assistant specialized in software development project management.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# Task to create a bug report
|
||||
create_bug_task = Task(
|
||||
description="Create a high-priority bug report for the authentication system and assign it to the backend team",
|
||||
agent=linear_agent,
|
||||
expected_output="Bug report created successfully with issue ID"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[linear_agent],
|
||||
tasks=[create_bug_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Linear 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
issue_manager = Agent(
|
||||
role="Issue Manager",
|
||||
goal="Create and manage Linear issues efficiently",
|
||||
backstory="An AI assistant that focuses on issue creation and lifecycle management.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# Task to manage issue workflow
|
||||
issue_workflow = Task(
|
||||
description="Create a feature request issue and update the status of related issues to reflect current progress",
|
||||
agent=issue_manager,
|
||||
expected_output="Feature request created and related issues updated"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[issue_manager],
|
||||
tasks=[issue_workflow]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 프로젝트 및 팀 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
project_coordinator = Agent(
|
||||
role="Project Coordinator",
|
||||
goal="Coordinate projects and teams in Linear efficiently",
|
||||
backstory="An experienced project coordinator who manages development cycles and team workflows.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# Task to coordinate project setup
|
||||
project_coordination = Task(
|
||||
description="""
|
||||
1. Search for engineering teams in Linear
|
||||
2. Create a new project for Q2 feature development
|
||||
3. Associate the project with relevant teams
|
||||
4. Create initial project milestones as issues
|
||||
""",
|
||||
agent=project_coordinator,
|
||||
expected_output="Q2 project created with teams assigned and initial milestones established"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[project_coordinator],
|
||||
tasks=[project_coordination]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 이슈 계층 구조 및 하위 작업 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
task_organizer = Agent(
|
||||
role="Task Organizer",
|
||||
goal="Organize complex issues into manageable sub-tasks",
|
||||
backstory="An AI assistant that breaks down complex development work into organized sub-tasks.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# Task to create issue hierarchy
|
||||
hierarchy_task = Task(
|
||||
description="""
|
||||
1. 세분화가 필요한 대형 기능 이슈를 검색합니다
|
||||
2. 각 복잡한 이슈에 대해 다양한 컴포넌트별로 하위 이슈를 생성합니다
|
||||
3. 부모 이슈를 적절한 설명과 하위 이슈에 대한 링크로 업데이트합니다
|
||||
4. 전문성에 따라 적합한 팀원에게 하위 이슈를 할당합니다
|
||||
""",
|
||||
agent=task_organizer,
|
||||
expected_output="복잡한 이슈가 적절히 할당된 관리 가능한 하위 작업 단위로 분해됨"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[task_organizer],
|
||||
tasks=[hierarchy_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 개발 워크플로우
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
workflow_automator = Agent(
|
||||
role="Workflow Automator",
|
||||
goal="Automate development workflow processes in Linear",
|
||||
backstory="An AI assistant that automates repetitive development workflow tasks.",
|
||||
apps=['linear']
|
||||
)
|
||||
|
||||
# Complex workflow automation task
|
||||
automation_task = Task(
|
||||
description="""
|
||||
1. 7일 이상 진행 중인 이슈를 검색합니다
|
||||
2. 마감일과 프로젝트 중요도에 따라 우선순위를 업데이트합니다
|
||||
3. 각 팀을 위한 주간 스프린트 계획 이슈를 생성합니다
|
||||
4. 이전 사이클에서 완료된 이슈를 보관합니다
|
||||
5. 프로젝트 상태 보고서를 새로운 이슈로 생성합니다
|
||||
""",
|
||||
agent=workflow_automator,
|
||||
expected_output="우선순위, 스프린트 계획, 상태 보고서가 업데이트된 자동화된 개발 워크플로우"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[workflow_automator],
|
||||
tasks=[automation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**권한 오류**
|
||||
|
||||
- Linear 계정이 대상 워크스페이스에 필요한 권한을 가지고 있는지 확인하세요
|
||||
- OAuth 연결에 Linear API에 필요한 스코프가 포함되어 있는지 확인하세요
|
||||
- 워크스페이스에서 이슈 및 프로젝트를 생성/편집할 권한이 있는지 확인하세요
|
||||
|
||||
**잘못된 ID 및 참조**
|
||||
|
||||
- 팀 ID, 이슈 ID, 프로젝트 ID가 올바른 UUID 형식인지 다시 한번 확인하세요
|
||||
- 참조된 엔티티(팀, 프로젝트, 사이클)가 존재하며 접근 가능한지 확인하세요
|
||||
- 이슈 식별자가 올바른 형식(예: "ABC-1")을 따르는지 검증하세요
|
||||
|
||||
**팀 및 프로젝트 연관 문제**
|
||||
|
||||
- 이슈나 프로젝트를 생성하기 전에 LINEAR_SEARCH_TEAMS를 사용하여 유효한 팀 ID를 조회하세요
|
||||
- 워크스페이스 내에 팀이 존재하고 활성화되어 있는지 확인하세요
|
||||
- 팀 ID가 올바르게 UUID 형식으로 구성되어 있는지 검증하세요
|
||||
|
||||
**이슈 상태 및 우선순위 문제**
|
||||
|
||||
- 상태 ID가 팀의 유효한 워크플로우 상태를 참조하는지 확인하세요
|
||||
- 우선순위 값이 Linear 구성에서 허용된 범위 내에 있는지 확인하세요
|
||||
- 참조하기 전에 사용자 지정 필드와 라벨이 존재하는지 검증하세요
|
||||
|
||||
**날짜 및 시간 형식 문제**
|
||||
|
||||
- 마감일 및 타임스탬프에 ISO 8601 형식을 사용하세요
|
||||
- 마감일 계산 시 타임존을 올바로 처리하는지 확인하세요
|
||||
- 마감일의 날짜 값이 유효하며 미래인지 검증하세요
|
||||
|
||||
**검색 및 필터 문제**
|
||||
|
||||
- 검색 쿼리가 올바르게 형식화되어 있으며 비어 있지 않은지 확인하세요
|
||||
- 필터 공식에서 유효한 필드 이름을 사용하세요: `title`, `number`, `project`, `createdAt`
|
||||
- 복잡한 다중 조건 쿼리를 만들기 전에 단순한 필터를 먼저 테스트해 보세요
|
||||
- 연산자 타입이 필터링 대상 필드의 데이터 타입과 일치하는지 확인하세요
|
||||
|
||||
**서브이슈 생성 문제**
|
||||
|
||||
- 상위 이슈 ID가 유효하고 접근 가능한지 확인하세요
|
||||
- 서브이슈의 팀 ID가 상위 이슈 팀과 일치하거나 호환되는지 검증하세요
|
||||
- 상위 이슈가 이미 보관/삭제되지 않았는지 확인하세요
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Linear 연동 설정 또는 문제 해결에 대해 지원팀에 문의하세요.
|
||||
</Card>
|
||||
293
docs/edge/ko/enterprise/integrations/microsoft_excel.mdx
Normal file
293
docs/edge/ko/enterprise/integrations/microsoft_excel.mdx
Normal file
@@ -0,0 +1,293 @@
|
||||
---
|
||||
title: Microsoft Excel 통합
|
||||
description: "CrewAI를 위한 Microsoft Excel 통합으로 통합 문서 및 데이터 관리."
|
||||
icon: "table"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 OneDrive 또는 SharePoint에서 Excel 통합 문서, 워크시트, 테이블 및 차트를 생성하고 관리할 수 있도록 합니다. AI 기반 자동화로 데이터 범위를 조작하고, 시각화를 생성하고, 테이블을 관리하며, 스프레드시트 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft Excel 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Excel 및 OneDrive/SharePoint 액세스 권한이 있는 Microsoft 365 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft Excel 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft Excel** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 파일 및 Excel 통합 문서 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_excel/create_workbook">
|
||||
**설명:** OneDrive 또는 SharePoint에 새 Excel 통합 문서를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_path` (string, 필수): 통합 문서를 만들 경로 (예: 'MyWorkbook.xlsx')
|
||||
- `worksheets` (array, 선택사항): 만들 초기 워크시트들. 각 항목은 `name` (string, 워크시트 이름)이 있는 객체.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_workbooks">
|
||||
**설명:** OneDrive 또는 SharePoint에서 모든 Excel 통합 문서를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택.
|
||||
- `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링.
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장.
|
||||
- `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999).
|
||||
- `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_worksheets">
|
||||
**설명:** Excel 통합 문서의 모든 워크시트를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'id,name,position').
|
||||
- `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링.
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장.
|
||||
- `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999).
|
||||
- `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/create_worksheet">
|
||||
**설명:** Excel 통합 문서에 새 워크시트를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `name` (string, 필수): 새 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_range_data">
|
||||
**설명:** Excel 워크시트의 특정 범위에서 데이터를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `range` (string, 필수): 범위 주소 (예: 'A1:C10').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/update_range_data">
|
||||
**설명:** Excel 워크시트의 특정 범위에서 데이터를 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `range` (string, 필수): 범위 주소 (예: 'A1:C10').
|
||||
- `values` (array, 필수): 범위에 설정할 값들의 2D 배열. 각 내부 배열은 행을 나타내며, 요소는 string, number 또는 integer일 수 있음.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/add_table">
|
||||
**설명:** Excel 워크시트에 테이블을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `range` (string, 필수): 테이블의 범위 (예: 'A1:D10').
|
||||
- `has_headers` (boolean, 선택사항): 첫 번째 행이 헤더를 포함하는지 여부. 기본값: true.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_tables">
|
||||
**설명:** Excel 워크시트의 모든 테이블을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/add_table_row">
|
||||
**설명:** Excel 테이블에 새 행을 추가합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `table_name` (string, 필수): 테이블의 이름.
|
||||
- `values` (array, 필수): 새 행의 값들 배열. 요소는 string, number 또는 integer일 수 있음.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_table_data">
|
||||
**설명:** Excel 워크시트의 특정 테이블에서 데이터를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `table_name` (string, 필수): 테이블의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/create_chart">
|
||||
**설명:** Excel 워크시트에 차트를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `chart_type` (string, 필수): 차트 유형 (예: 'ColumnClustered', 'Line', 'Pie').
|
||||
- `source_data` (string, 필수): 차트의 데이터 범위 (예: 'A1:B10').
|
||||
- `series_by` (string, 선택사항): 데이터 해석 방법 ('Auto', 'Columns' 또는 'Rows'). 기본값: 'Auto'.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_cell">
|
||||
**설명:** Excel 워크시트의 단일 셀 값을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `row` (integer, 필수): 행 번호 (0 기반).
|
||||
- `column` (integer, 필수): 열 번호 (0 기반).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_used_range">
|
||||
**설명:** Excel 워크시트의 사용된 범위를 가져옵니다 (모든 데이터를 포함).
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/get_used_range_metadata">
|
||||
**설명:** Excel 워크시트의 사용된 범위 메타데이터(크기만, 데이터 없음)를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/list_charts">
|
||||
**설명:** Excel 워크시트의 모든 차트를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/delete_worksheet">
|
||||
**설명:** Excel 통합 문서에서 워크시트를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 삭제할 워크시트의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/delete_table">
|
||||
**설명:** Excel 워크시트에서 테이블을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
- `worksheet_name` (string, 필수): 워크시트의 이름.
|
||||
- `table_name` (string, 필수): 삭제할 테이블의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_excel/list_names">
|
||||
**설명:** Excel 통합 문서의 모든 명명된 범위를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): Excel 파일의 ID.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft Excel 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft Excel 기능을 가진 에이전트 생성
|
||||
excel_agent = Agent(
|
||||
role="Excel 데이터 관리자",
|
||||
goal="Excel 통합 문서와 데이터를 효율적으로 관리",
|
||||
backstory="Microsoft Excel 작업 및 데이터 조작 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_excel'] # 모든 Excel 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 새 통합 문서 생성 작업
|
||||
create_workbook_task = Task(
|
||||
description="'월간보고서.xlsx'라는 이름으로 새 Excel 통합 문서를 만들고 '매출데이터'라는 초기 워크시트를 포함하세요.",
|
||||
agent=excel_agent,
|
||||
expected_output="새 통합 문서 '월간보고서.xlsx'가 '매출데이터' 워크시트와 함께 생성됨."
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[excel_agent],
|
||||
tasks=[create_workbook_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read.All`, `Files.ReadWrite.All`).
|
||||
- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**파일 생성 문제**
|
||||
|
||||
- 통합 문서를 만들 때 `file_path`가 `.xlsx` 확장자로 끝나는지 확인하세요.
|
||||
- 대상 위치(OneDrive/SharePoint)에 쓰기 권한이 있는지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft Excel 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
332
docs/edge/ko/enterprise/integrations/microsoft_onedrive.mdx
Normal file
332
docs/edge/ko/enterprise/integrations/microsoft_onedrive.mdx
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
title: Microsoft OneDrive 통합
|
||||
description: "CrewAI를 위한 Microsoft OneDrive 통합으로 파일 및 폴더 관리."
|
||||
icon: "cloud"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Microsoft OneDrive에서 파일과 폴더를 업로드, 다운로드 및 관리할 수 있도록 합니다. AI 기반 자동화로 파일 작업을 자동화하고, 콘텐츠를 구성하고, 공유 링크를 생성하며, 클라우드 스토리지 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft OneDrive 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- OneDrive 액세스 권한이 있는 Microsoft 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft OneDrive 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft OneDrive** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 파일 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_onedrive/list_files">
|
||||
**설명:** OneDrive의 파일과 폴더를 나열합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 항목 수 (최대 1000). 기본값: 50.
|
||||
- `orderby` (string, 선택사항): 필드별 정렬 (예: "name asc", "lastModifiedDateTime desc"). 기본값: "name asc".
|
||||
- `filter` (string, 선택사항): OData 필터 표현식.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_file_info">
|
||||
**설명:** 특정 파일 또는 폴더에 대한 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 파일 또는 폴더의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/download_file">
|
||||
**설명:** OneDrive에서 파일을 다운로드합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 다운로드할 파일의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/upload_file">
|
||||
**설명:** OneDrive에 파일을 업로드합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_name` (string, 필수): 업로드할 파일의 이름.
|
||||
- `content` (string, 필수): Base64로 인코딩된 파일 내용.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/create_folder">
|
||||
**설명:** OneDrive에 새 폴더를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `folder_name` (string, 필수): 만들 폴더의 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/delete_item">
|
||||
**설명:** OneDrive에서 파일 또는 폴더를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 삭제할 파일 또는 폴더의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/copy_item">
|
||||
**설명:** OneDrive에서 파일 또는 폴더를 복사합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 복사할 파일 또는 폴더의 ID.
|
||||
- `parent_id` (string, 선택사항): 대상 폴더의 ID (선택사항, 기본값은 루트).
|
||||
- `new_name` (string, 선택사항): 복사된 항목의 새 이름 (선택사항).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/move_item">
|
||||
**설명:** OneDrive에서 파일 또는 폴더를 이동합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 이동할 파일 또는 폴더의 ID.
|
||||
- `parent_id` (string, 필수): 대상 폴더의 ID.
|
||||
- `new_name` (string, 선택사항): 항목의 새 이름 (선택사항).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/search_files">
|
||||
**설명:** OneDrive에서 파일과 폴더를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `query` (string, 필수): 검색 쿼리 문자열.
|
||||
- `top` (integer, 선택사항): 반환할 결과 수 (최대 1000). 기본값: 50.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/share_item">
|
||||
**설명:** 파일 또는 폴더의 공유 링크를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 공유할 파일 또는 폴더의 ID.
|
||||
- `type` (string, 선택사항): 공유 링크 유형. 옵션: view, edit, embed. 기본값: view.
|
||||
- `scope` (string, 선택사항): 공유 링크 범위. 옵션: anonymous, organization. 기본값: anonymous.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_thumbnails">
|
||||
**설명:** 파일의 썸네일을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `item_id` (string, 필수): 파일의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/list_files_by_path">
|
||||
**설명:** 특정 OneDrive 경로의 파일과 폴더를 나열합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `folder_path` (string, 필수): 폴더 경로 (예: 'Documents/Reports').
|
||||
- `top` (integer, 선택사항): 검색할 항목 수 (최대 1000). 기본값: 50.
|
||||
- `orderby` (string, 선택사항): 필드별 정렬 (예: "name asc", "lastModifiedDateTime desc"). 기본값: "name asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_recent_files">
|
||||
**설명:** OneDrive에서 최근에 액세스한 파일을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 항목 수 (최대 200). 기본값: 25.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_shared_with_me">
|
||||
**설명:** 사용자와 공유된 파일과 폴더를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 항목 수 (최대 200). 기본값: 50.
|
||||
- `orderby` (string, 선택사항): 필드별 정렬. 기본값: "name asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/get_file_by_path">
|
||||
**설명:** 경로로 특정 파일 또는 폴더에 대한 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_path` (string, 필수): 파일 또는 폴더 경로 (예: 'Documents/report.docx').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_onedrive/download_file_by_path">
|
||||
**설명:** 경로로 OneDrive에서 파일을 다운로드합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_path` (string, 필수): 파일 경로 (예: 'Documents/report.docx').
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft OneDrive 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft OneDrive 기능을 가진 에이전트 생성
|
||||
onedrive_agent = Agent(
|
||||
role="파일 관리자",
|
||||
goal="OneDrive에서 파일과 폴더를 효율적으로 관리",
|
||||
backstory="Microsoft OneDrive 파일 작업 및 구성 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_onedrive'] # 모든 OneDrive 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 파일 나열 및 폴더 생성 작업
|
||||
organize_files_task = Task(
|
||||
description="OneDrive 루트 디렉토리의 모든 파일을 나열하고 '프로젝트 문서'라는 새 폴더를 만드세요.",
|
||||
agent=onedrive_agent,
|
||||
expected_output="파일 목록이 표시되고 새 폴더 '프로젝트 문서'가 생성됨."
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[onedrive_agent],
|
||||
tasks=[organize_files_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 파일 업로드 및 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 파일 작업에 특화된 에이전트 생성
|
||||
file_operator = Agent(
|
||||
role="파일 운영자",
|
||||
goal="파일을 정확하게 업로드, 다운로드 및 관리",
|
||||
backstory="파일 처리 및 콘텐츠 관리에 능숙한 AI 어시스턴트.",
|
||||
apps=['microsoft_onedrive/upload_file', 'microsoft_onedrive/download_file', 'microsoft_onedrive/get_file_info']
|
||||
)
|
||||
|
||||
# 파일 업로드 및 관리 작업
|
||||
file_management_task = Task(
|
||||
description="'report.txt'라는 이름의 텍스트 파일을 'This is a sample report for the project.' 내용으로 업로드한 다음 업로드된 파일에 대한 정보를 가져오세요.",
|
||||
agent=file_operator,
|
||||
expected_output="파일이 성공적으로 업로드되고 파일 정보가 검색됨."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[file_operator],
|
||||
tasks=[file_management_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 파일 정리 및 공유
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 파일 정리 및 공유를 위한 에이전트 생성
|
||||
file_organizer = Agent(
|
||||
role="파일 정리자",
|
||||
goal="파일을 정리하고 협업을 위한 공유 링크 생성",
|
||||
backstory="파일 정리 및 공유 권한 관리에 뛰어난 AI 어시스턴트.",
|
||||
apps=['microsoft_onedrive/search_files', 'microsoft_onedrive/move_item', 'microsoft_onedrive/share_item', 'microsoft_onedrive/create_folder']
|
||||
)
|
||||
|
||||
# 파일 정리 및 공유 작업
|
||||
organize_share_task = Task(
|
||||
description="이름에 'presentation'이 포함된 파일을 검색하고, '프레젠테이션'이라는 폴더를 만든 다음, 찾은 파일을 이 폴더로 이동하고 폴더에 대한 읽기 전용 공유 링크를 생성하세요.",
|
||||
agent=file_organizer,
|
||||
expected_output="파일이 '프레젠테이션' 폴더로 정리되고 공유 링크가 생성됨."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[file_organizer],
|
||||
tasks=[organize_share_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read`, `Files.ReadWrite`).
|
||||
- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**파일 업로드 문제**
|
||||
|
||||
- 파일 업로드 시 `file_name`과 `content`가 제공되는지 확인하세요.
|
||||
- 바이너리 파일의 경우 내용이 Base64로 인코딩되어야 합니다.
|
||||
- OneDrive에 대한 쓰기 권한이 있는지 확인하세요.
|
||||
|
||||
**파일/폴더 ID 문제**
|
||||
|
||||
- 특정 파일 또는 폴더에 액세스할 때 항목 ID가 올바른지 다시 확인하세요.
|
||||
- 항목 ID는 `list_files` 또는 `search_files`와 같은 다른 작업에서 반환됩니다.
|
||||
- 참조하는 항목이 존재하고 액세스 가능한지 확인하세요.
|
||||
|
||||
**검색 및 필터 작업**
|
||||
|
||||
- `search_files` 작업에 적절한 검색어를 사용하세요.
|
||||
- `filter` 매개변수의 경우 올바른 OData 문법을 사용하세요.
|
||||
|
||||
**파일 작업 (복사/이동)**
|
||||
|
||||
- `move_item`의 경우 `item_id`와 `parent_id`가 모두 제공되는지 확인하세요.
|
||||
- `copy_item`의 경우 `item_id`만 필요합니다. `parent_id`는 지정하지 않으면 루트로 기본 설정됩니다.
|
||||
- 대상 폴더가 존재하고 액세스 가능한지 확인하세요.
|
||||
|
||||
**공유 링크 생성**
|
||||
|
||||
- 공유 링크를 만들기 전에 항목이 존재하는지 확인하세요.
|
||||
- 공유 요구 사항에 따라 적절한 `type`과 `scope`를 선택하세요.
|
||||
- `anonymous` 범위는 로그인 없이 액세스를 허용합니다. `organization`은 조직 계정이 필요합니다.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft OneDrive 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
333
docs/edge/ko/enterprise/integrations/microsoft_outlook.mdx
Normal file
333
docs/edge/ko/enterprise/integrations/microsoft_outlook.mdx
Normal file
@@ -0,0 +1,333 @@
|
||||
---
|
||||
title: Microsoft Outlook 통합
|
||||
description: "CrewAI를 위한 Microsoft Outlook 통합으로 이메일, 캘린더 및 연락처 관리."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Outlook 이메일, 캘린더 이벤트 및 연락처에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 이메일을 보내고, 메시지를 검색하고, 캘린더 이벤트를 관리하며, 연락처를 구성합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft Outlook 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Outlook 액세스 권한이 있는 Microsoft 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft Outlook 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft Outlook** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 이메일, 캘린더 및 연락처 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_outlook/get_messages">
|
||||
**설명:** 사용자의 사서함에서 이메일 메시지를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 메시지 수 (최대 1000). 기본값: 10.
|
||||
- `filter` (string, 선택사항): OData 필터 표현식 (예: "isRead eq false").
|
||||
- `search` (string, 선택사항): 검색 쿼리 문자열.
|
||||
- `orderby` (string, 선택사항): 필드별 정렬 (예: "receivedDateTime desc"). 기본값: "receivedDateTime desc".
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택.
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/send_email">
|
||||
**설명:** 이메일 메시지를 보냅니다.
|
||||
|
||||
**매개변수:**
|
||||
- `to_recipients` (array, 필수): 받는 사람의 이메일 주소 배열.
|
||||
- `cc_recipients` (array, 선택사항): 참조 받는 사람의 이메일 주소 배열.
|
||||
- `bcc_recipients` (array, 선택사항): 숨은 참조 받는 사람의 이메일 주소 배열.
|
||||
- `subject` (string, 필수): 이메일 제목.
|
||||
- `body` (string, 필수): 이메일 본문 내용.
|
||||
- `body_type` (string, 선택사항): 본문 내용 유형. 옵션: Text, HTML. 기본값: HTML.
|
||||
- `importance` (string, 선택사항): 메시지 중요도 수준. 옵션: low, normal, high. 기본값: normal.
|
||||
- `reply_to` (array, 선택사항): 회신용 이메일 주소 배열.
|
||||
- `save_to_sent_items` (boolean, 선택사항): 보낸 편지함 폴더에 메시지를 저장할지 여부. 기본값: true.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_calendar_events">
|
||||
**설명:** 사용자의 캘린더에서 캘린더 이벤트를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 이벤트 수 (최대 1000). 기본값: 10.
|
||||
- `skip` (integer, 선택사항): 건너뛸 이벤트 수. 기본값: 0.
|
||||
- `filter` (string, 선택사항): OData 필터 표현식 (예: "start/dateTime ge '2024-01-01T00:00:00Z'").
|
||||
- `orderby` (string, 선택사항): 필드별 정렬 (예: "start/dateTime asc"). 기본값: "start/dateTime asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/create_calendar_event">
|
||||
**설명:** 새 캘린더 이벤트를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `subject` (string, 필수): 이벤트 제목/제목.
|
||||
- `body` (string, 선택사항): 이벤트 본문/설명.
|
||||
- `start_datetime` (string, 필수): ISO 8601 형식의 시작 날짜 및 시간 (예: '2024-01-20T10:00:00').
|
||||
- `end_datetime` (string, 필수): ISO 8601 형식의 종료 날짜 및 시간.
|
||||
- `timezone` (string, 선택사항): 시간대 (예: 'Pacific Standard Time'). 기본값: UTC.
|
||||
- `location` (string, 선택사항): 이벤트 위치.
|
||||
- `attendees` (array, 선택사항): 참석자의 이메일 주소 배열.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_contacts">
|
||||
**설명:** 사용자의 주소록에서 연락처를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `top` (integer, 선택사항): 검색할 연락처 수 (최대 1000). 기본값: 10.
|
||||
- `skip` (integer, 선택사항): 건너뛸 연락처 수. 기본값: 0.
|
||||
- `filter` (string, 선택사항): OData 필터 표현식.
|
||||
- `orderby` (string, 선택사항): 필드별 정렬 (예: "displayName asc"). 기본값: "displayName asc".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/create_contact">
|
||||
**설명:** 사용자의 주소록에 새 연락처를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `displayName` (string, 필수): 연락처의 표시 이름.
|
||||
- `givenName` (string, 선택사항): 연락처의 이름.
|
||||
- `surname` (string, 선택사항): 연락처의 성.
|
||||
- `emailAddresses` (array, 선택사항): 이메일 주소 배열. 각 항목은 `address` (string)와 `name` (string)이 있는 객체.
|
||||
- `businessPhones` (array, 선택사항): 사업용 전화번호 배열.
|
||||
- `homePhones` (array, 선택사항): 집 전화번호 배열.
|
||||
- `jobTitle` (string, 선택사항): 연락처의 직책.
|
||||
- `companyName` (string, 선택사항): 연락처의 회사 이름.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/get_message">
|
||||
**설명:** ID로 특정 이메일 메시지를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `message_id` (string, 필수): 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록. 예: "id,subject,body,from,receivedDateTime". 기본값: "id,subject,body,from,toRecipients,receivedDateTime".
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/reply_to_email">
|
||||
**설명:** 이메일 메시지에 회신합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `message_id` (string, 필수): 회신할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `comment` (string, 필수): 회신 메시지 내용. 일반 텍스트 또는 HTML 가능. 원본 메시지가 이 내용 아래에 인용됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/forward_email">
|
||||
**설명:** 이메일 메시지를 전달합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `message_id` (string, 필수): 전달할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `to_recipients` (array, 필수): 전달할 받는 사람의 이메일 주소 배열. 예: ["john@example.com", "jane@example.com"].
|
||||
- `comment` (string, 선택사항): 전달된 콘텐츠 위에 포함할 선택적 메시지. 일반 텍스트 또는 HTML 가능.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/mark_message_read">
|
||||
**설명:** 메시지를 읽음 또는 읽지 않음으로 표시합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `message_id` (string, 필수): 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `is_read` (boolean, 필수): 읽음으로 표시하려면 true, 읽지 않음으로 표시하려면 false로 설정합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/delete_message">
|
||||
**설명:** 이메일 메시지를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `message_id` (string, 필수): 삭제할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/update_event">
|
||||
**설명:** 기존 캘린더 이벤트를 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `event_id` (string, 필수): 이벤트의 고유 식별자. get_calendar_events 작업에서 얻을 수 있습니다.
|
||||
- `subject` (string, 선택사항): 이벤트의 새 제목/제목.
|
||||
- `start_time` (string, 선택사항): ISO 8601 형식의 새 시작 시간 (예: "2024-01-20T10:00:00"). 필수: 이 필드 사용 시 start_timezone도 제공해야 합니다.
|
||||
- `start_timezone` (string, 선택사항): 시작 시간의 시간대. start_time 업데이트 시 필수. 예: "Pacific Standard Time", "Eastern Standard Time", "UTC".
|
||||
- `end_time` (string, 선택사항): ISO 8601 형식의 새 종료 시간. 필수: 이 필드 사용 시 end_timezone도 제공해야 합니다.
|
||||
- `end_timezone` (string, 선택사항): 종료 시간의 시간대. end_time 업데이트 시 필수. 예: "Pacific Standard Time", "Eastern Standard Time", "UTC".
|
||||
- `location` (string, 선택사항): 이벤트의 새 위치.
|
||||
- `body` (string, 선택사항): 이벤트의 새 본문/설명. HTML 형식 지원.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_outlook/delete_event">
|
||||
**설명:** 캘린더 이벤트를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `event_id` (string, 필수): 삭제할 이벤트의 고유 식별자. get_calendar_events 작업에서 얻을 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft Outlook 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft Outlook 기능을 가진 에이전트 생성
|
||||
outlook_agent = Agent(
|
||||
role="이메일 어시스턴트",
|
||||
goal="이메일, 캘린더 이벤트 및 연락처를 효율적으로 관리",
|
||||
backstory="Microsoft Outlook 작업 및 커뮤니케이션 관리 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_outlook'] # 모든 Outlook 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 이메일 보내기 작업
|
||||
send_email_task = Task(
|
||||
description="'colleague@example.com'에게 제목 '프로젝트 업데이트'와 본문 '안녕하세요, 프로젝트의 최신 업데이트입니다. 감사합니다.'로 이메일을 보내세요",
|
||||
agent=outlook_agent,
|
||||
expected_output="colleague@example.com에게 이메일이 성공적으로 전송됨"
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[outlook_agent],
|
||||
tasks=[send_email_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 이메일 관리 및 검색
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 이메일 관리에 특화된 에이전트 생성
|
||||
email_manager = Agent(
|
||||
role="이메일 관리자",
|
||||
goal="이메일 메시지를 검색하고 가져와 정리",
|
||||
backstory="이메일 정리 및 관리에 능숙한 AI 어시스턴트.",
|
||||
apps=['microsoft_outlook/get_messages']
|
||||
)
|
||||
|
||||
# 이메일 검색 및 가져오기 작업
|
||||
search_emails_task = Task(
|
||||
description="최신 읽지 않은 이메일 20건을 가져와 가장 중요한 것들의 요약을 제공하세요.",
|
||||
agent=email_manager,
|
||||
expected_output="주요 읽지 않은 이메일의 요약과 핵심 세부 정보."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[email_manager],
|
||||
tasks=[search_emails_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 캘린더 및 연락처 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 캘린더 및 연락처 관리를 위한 에이전트 생성
|
||||
scheduler = Agent(
|
||||
role="캘린더 및 연락처 관리자",
|
||||
goal="캘린더 이벤트를 관리하고 연락처 정보를 유지",
|
||||
backstory="일정 관리 및 연락처 정리를 담당하는 AI 어시스턴트.",
|
||||
apps=['microsoft_outlook/create_calendar_event', 'microsoft_outlook/get_calendar_events', 'microsoft_outlook/create_contact']
|
||||
)
|
||||
|
||||
# 회의 생성 및 연락처 추가 작업
|
||||
schedule_task = Task(
|
||||
description="내일 오후 2시 '팀 회의' 제목으로 '회의실 A' 장소의 캘린더 이벤트를 만들고, 'john.smith@example.com' 이메일과 '프로젝트 매니저' 직책으로 'John Smith'의 새 연락처를 추가하세요.",
|
||||
agent=scheduler,
|
||||
expected_output="캘린더 이벤트가 생성되고 새 연락처가 추가됨."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[scheduler],
|
||||
tasks=[schedule_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 이메일, 캘린더 및 연락처 액세스에 필요한 권한을 가지고 있는지 확인하세요.
|
||||
- 필요한 범위: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`.
|
||||
- OAuth 연결에 필요한 모든 범위가 포함되어 있는지 확인하세요.
|
||||
|
||||
**이메일 보내기 문제**
|
||||
|
||||
- `send_email`에 `to_recipients`, `subject`, `body`가 제공되는지 확인하세요.
|
||||
- 이메일 주소가 올바르게 형식화되어 있는지 확인하세요.
|
||||
- 계정에 `Mail.Send` 권한이 있는지 확인하세요.
|
||||
|
||||
**캘린더 이벤트 생성**
|
||||
|
||||
- `subject`, `start_datetime`, `end_datetime`이 제공되는지 확인하세요.
|
||||
- 날짜/시간 필드에 적절한 ISO 8601 형식을 사용하세요 (예: '2024-01-20T10:00:00').
|
||||
- 이벤트가 잘못된 시간에 표시되는 경우 시간대 설정을 확인하세요.
|
||||
|
||||
**연락처 관리**
|
||||
|
||||
- `create_contact`의 경우 필수인 `displayName`이 제공되는지 확인하세요.
|
||||
- `emailAddresses`를 제공할 때 `address`와 `name` 속성이 있는 올바른 객체 형식을 사용하세요.
|
||||
|
||||
**검색 및 필터 문제**
|
||||
|
||||
- `filter` 매개변수에 올바른 OData 문법을 사용하세요.
|
||||
- 날짜 필터의 경우 ISO 8601 형식을 사용하세요 (예: "receivedDateTime ge '2024-01-01T00:00:00Z'").
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft Outlook 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
528
docs/edge/ko/enterprise/integrations/microsoft_sharepoint.mdx
Normal file
528
docs/edge/ko/enterprise/integrations/microsoft_sharepoint.mdx
Normal file
@@ -0,0 +1,528 @@
|
||||
---
|
||||
title: Microsoft SharePoint 통합
|
||||
description: "CrewAI를 위한 Microsoft SharePoint 통합으로 사이트, 목록 및 문서 관리."
|
||||
icon: "folder-tree"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 SharePoint 사이트, 목록 및 문서 라이브러리에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 사이트 정보를 검색하고, 목록 항목을 관리하고, 파일을 업로드 및 구성하며, SharePoint 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft SharePoint 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- SharePoint 액세스 권한이 있는 Microsoft 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft SharePoint 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft SharePoint** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. SharePoint 사이트 및 파일 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_sharepoint/get_sites">
|
||||
**설명:** 사용자가 액세스할 수 있는 모든 SharePoint 사이트를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `search` (string, 선택사항): 사이트를 필터링하기 위한 검색 쿼리.
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'displayName,id,webUrl').
|
||||
- `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링.
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장.
|
||||
- `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999).
|
||||
- `skip` (integer, 선택사항): 건너뛸 항목 수 (최소 0).
|
||||
- `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬 (예: 'displayName desc').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_site">
|
||||
**설명:** 특정 SharePoint 사이트에 대한 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'displayName,id,webUrl,drives').
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장 (예: 'drives,lists').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_drives">
|
||||
**설명:** SharePoint 사이트의 모든 문서 라이브러리(드라이브)를 나열합니다. 파일 작업을 사용하기 전에 사용 가능한 라이브러리를 찾으려면 이 작업을 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `top` (integer, 선택사항): 페이지당 반환할 최대 드라이브 수 (1-999). 기본값: 100
|
||||
- `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,webUrl,driveType').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_site_lists">
|
||||
**설명:** SharePoint 사이트의 모든 목록을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_list">
|
||||
**설명:** 특정 목록에 대한 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `list_id` (string, 필수): 목록의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_list_items">
|
||||
**설명:** SharePoint 목록에서 항목을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `list_id` (string, 필수): 목록의 ID.
|
||||
- `expand` (string, 선택사항): 관련 데이터 확장 (예: 'fields').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_list_item">
|
||||
**설명:** SharePoint 목록에 새 항목을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `list_id` (string, 필수): 목록의 ID.
|
||||
- `fields` (object, 필수): 새 항목의 필드 값.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/update_list_item">
|
||||
**설명:** SharePoint 목록의 항목을 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `list_id` (string, 필수): 목록의 ID.
|
||||
- `item_id` (string, 필수): 업데이트할 항목의 ID.
|
||||
- `fields` (object, 필수): 업데이트할 필드 값.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_list_item">
|
||||
**설명:** SharePoint 목록에서 항목을 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `list_id` (string, 필수): 목록의 ID.
|
||||
- `item_id` (string, 필수): 삭제할 항목의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/upload_file_to_library">
|
||||
**설명:** SharePoint 문서 라이브러리에 파일을 업로드합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): SharePoint 사이트의 ID.
|
||||
- `file_path` (string, 필수): 파일을 업로드할 경로 (예: 'folder/fileName.txt').
|
||||
- `content` (string, 필수): 업로드할 파일의 내용.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_files">
|
||||
**설명:** SharePoint 문서 라이브러리에서 파일과 폴더를 가져옵니다. 기본적으로 루트 폴더를 나열하지만 folder_id를 제공하여 하위 폴더로 이동할 수 있습니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `folder_id` (string, 선택사항): 내용을 나열할 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 이전 list_files 호출에서 가져온 폴더 ID를 제공하세요. 기본값: 'root'
|
||||
- `top` (integer, 선택사항): 페이지당 반환할 최대 항목 수 (1-1000). 기본값: 50
|
||||
- `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰.
|
||||
- `orderby` (string, 선택사항): 결과 정렬 순서 (예: 'name asc', 'size desc', 'lastModifiedDateTime desc'). 기본값: 'name asc'
|
||||
- `filter` (string, 선택사항): 결과를 좁히기 위한 OData 필터 (예: 'file ne null'은 파일만, 'folder ne null'은 폴더만).
|
||||
- `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_file">
|
||||
**설명:** SharePoint 문서 라이브러리에서 파일 또는 폴더를 삭제합니다. 폴더의 경우 모든 내용이 재귀적으로 삭제됩니다. 항목은 사이트 휴지통으로 이동됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): 삭제할 파일 또는 폴더의 고유 식별자. list_files에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_files_by_path">
|
||||
**설명:** 경로로 SharePoint 문서 라이브러리 폴더의 파일과 폴더를 나열합니다. 깊은 탐색을 위해 여러 list_files 호출보다 더 효율적입니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `folder_path` (string, 필수): 앞뒤 슬래시 없이 폴더의 전체 경로 (예: 'Documents', 'Reports/2024/Q1').
|
||||
- `top` (integer, 선택사항): 페이지당 반환할 최대 항목 수 (1-1000). 기본값: 50
|
||||
- `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰.
|
||||
- `orderby` (string, 선택사항): 결과 정렬 순서 (예: 'name asc', 'size desc'). 기본값: 'name asc'
|
||||
- `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/download_file">
|
||||
**설명:** SharePoint 문서 라이브러리에서 원시 파일 내용을 다운로드합니다. 일반 텍스트 파일(.txt, .csv, .json)에만 사용하세요. Excel 파일의 경우 Excel 전용 작업을 사용하세요. Word 파일의 경우 get_word_document_content를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): 다운로드할 파일의 고유 식별자. list_files 또는 list_files_by_path에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_file_info">
|
||||
**설명:** SharePoint 문서 라이브러리의 특정 파일 또는 폴더에 대한 자세한 메타데이터를 가져옵니다. 이름, 크기, 생성/수정 날짜 및 작성자 정보가 포함됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): 파일 또는 폴더의 고유 식별자. list_files 또는 list_files_by_path에서 가져오세요.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_folder">
|
||||
**설명:** SharePoint 문서 라이브러리에 새 폴더를 만듭니다. 기본적으로 루트에 폴더를 만들며 하위 폴더를 만들려면 parent_id를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `folder_name` (string, 필수): 새 폴더의 이름. 사용할 수 없는 문자: \ / : * ? " < > |
|
||||
- `parent_id` (string, 선택사항): 상위 폴더의 ID. 문서 라이브러리 루트의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 제공하세요. 기본값: 'root'
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/search_files">
|
||||
**설명:** 키워드로 SharePoint 문서 라이브러리에서 파일과 폴더를 검색합니다. 파일 이름, 폴더 이름 및 Office 문서의 파일 내용을 검색합니다. 와일드카드나 특수 문자를 사용하지 마세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `query` (string, 필수): 검색 키워드 (예: 'report', 'budget 2024'). *.txt와 같은 와일드카드는 지원되지 않습니다.
|
||||
- `top` (integer, 선택사항): 페이지당 반환할 최대 결과 수 (1-1000). 기본값: 50
|
||||
- `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰.
|
||||
- `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/copy_file">
|
||||
**설명:** SharePoint 내에서 파일 또는 폴더를 새 위치로 복사합니다. 원본 항목은 변경되지 않습니다. 대용량 파일의 경우 복사 작업은 비동기적입니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): 복사할 파일 또는 폴더의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `destination_folder_id` (string, 필수): 대상 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 사용하세요.
|
||||
- `new_name` (string, 선택사항): 복사본의 새 이름. 제공하지 않으면 원래 이름이 사용됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/move_file">
|
||||
**설명:** SharePoint 내에서 파일 또는 폴더를 새 위치로 이동합니다. 항목은 원래 위치에서 제거됩니다. 폴더의 경우 모든 내용도 함께 이동됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): 이동할 파일 또는 폴더의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `destination_folder_id` (string, 필수): 대상 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 사용하세요.
|
||||
- `new_name` (string, 선택사항): 이동된 항목의 새 이름. 제공하지 않으면 원래 이름이 유지됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_worksheets">
|
||||
**설명:** SharePoint 문서 라이브러리에 저장된 Excel 통합 문서의 모든 워크시트(탭)를 나열합니다. 반환된 워크시트 이름을 다른 Excel 작업에 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,position,visibility').
|
||||
- `filter` (string, 선택사항): OData 필터 표현식 (예: "visibility eq 'Visible'"로 숨겨진 시트 제외).
|
||||
- `top` (integer, 선택사항): 반환할 최대 워크시트 수. 최소: 1, 최대: 999
|
||||
- `orderby` (string, 선택사항): 정렬 순서 (예: 'position asc'로 탭 순서대로 반환).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_excel_worksheet">
|
||||
**설명:** SharePoint 문서 라이브러리에 저장된 Excel 통합 문서에 새 워크시트(탭)를 만듭니다. 새 시트는 탭 목록의 끝에 추가됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `name` (string, 필수): 새 워크시트의 이름. 최대 31자. 사용할 수 없는 문자: \ / * ? : [ ]. 통합 문서 내에서 고유해야 합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_range_data">
|
||||
**설명:** SharePoint에 저장된 Excel 워크시트의 특정 범위에서 셀 값을 가져옵니다. 크기를 모르는 상태에서 모든 데이터를 읽으려면 대신 get_excel_used_range를 사용하세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `range` (string, 필수): A1 표기법의 셀 범위 (예: 'A1:C10', 'A:C', '1:5', 'A1').
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/update_excel_range_data">
|
||||
**설명:** SharePoint에 저장된 Excel 워크시트의 특정 범위에 값을 씁니다. 기존 셀 내용을 덮어씁니다. values 배열의 크기는 범위 크기와 정확히 일치해야 합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 업데이트할 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `range` (string, 필수): 값을 쓸 A1 표기법의 셀 범위 (예: 'A1:C3'은 3x3 블록).
|
||||
- `values` (array, 필수): 2D 값 배열 (셀을 포함하는 행). A1:B2의 예: [["Header1", "Header2"], ["Value1", "Value2"]]. 셀을 지우려면 null을 사용하세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_used_range_metadata">
|
||||
**설명:** 실제 셀 값 없이 워크시트에서 사용된 범위의 메타데이터(주소 및 크기)만 반환합니다. 대용량 파일에서 데이터를 청크로 읽기 전에 스프레드시트 크기를 파악하는 데 이상적입니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_used_range">
|
||||
**설명:** SharePoint에 저장된 워크시트에서 데이터가 포함된 모든 셀을 가져옵니다. 2MB보다 큰 파일에는 사용하지 마세요. 대용량 파일의 경우 먼저 get_excel_used_range_metadata를 사용한 다음 get_excel_range_data로 작은 청크로 읽으세요.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text,rowCount,columnCount').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_cell">
|
||||
**설명:** SharePoint의 Excel 파일에서 행과 열 인덱스로 단일 셀의 값을 가져옵니다. 인덱스는 0 기반입니다 (행 0 = Excel 행 1, 열 0 = 열 A).
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `row` (integer, 필수): 0 기반 행 인덱스 (행 0 = Excel 행 1). 유효 범위: 0-1048575
|
||||
- `column` (integer, 필수): 0 기반 열 인덱스 (열 0 = A, 열 1 = B). 유효 범위: 0-16383
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/add_excel_table">
|
||||
**설명:** 셀 범위를 필터링, 정렬 및 구조화된 데이터 기능이 있는 서식이 지정된 Excel 테이블로 변환합니다. 테이블을 만들면 add_excel_table_row로 데이터를 추가할 수 있습니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 데이터 범위가 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
- `range` (string, 필수): 헤더와 데이터를 포함하여 테이블로 변환할 셀 범위 (예: 'A1:D10'에서 A1:D1은 열 헤더).
|
||||
- `has_headers` (boolean, 선택사항): 첫 번째 행에 열 헤더가 포함되어 있으면 true로 설정. 기본값: true
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_tables">
|
||||
**설명:** SharePoint에 저장된 특정 Excel 워크시트의 모든 테이블을 나열합니다. id, name, showHeaders 및 showTotals를 포함한 테이블 속성을 반환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 테이블을 가져올 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/add_excel_table_row">
|
||||
**설명:** SharePoint 파일의 Excel 테이블 끝에 새 행을 추가합니다. values 배열은 테이블의 열 수와 같은 수의 요소를 가져야 합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
- `table_name` (string, 필수): 행을 추가할 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `values` (array, 필수): 새 행의 셀 값 배열로 테이블 순서대로 열당 하나씩 (예: ["John Doe", "john@example.com", 25]).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_excel_table_data">
|
||||
**설명:** SharePoint 파일의 Excel 테이블에서 모든 행을 데이터 범위로 가져옵니다. 정확한 범위를 알 필요가 없으므로 구조화된 테이블 작업 시 get_excel_range_data보다 쉽습니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
- `table_name` (string, 필수): 데이터를 가져올 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 대소문자를 구분합니다.
|
||||
- `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text').
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/create_excel_chart">
|
||||
**설명:** SharePoint에 저장된 Excel 워크시트에 데이터 범위에서 차트 시각화를 만듭니다. 차트는 워크시트에 포함됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 차트를 만들 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
- `chart_type` (string, 필수): 차트 유형 (예: 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut').
|
||||
- `source_data` (string, 필수): 헤더를 포함한 A1 표기법의 차트 데이터 범위 (예: 'A1:B10').
|
||||
- `series_by` (string, 선택사항): 데이터 계열 구성 방법: 'Auto', 'Columns' 또는 'Rows'. 기본값: 'Auto'
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_excel_charts">
|
||||
**설명:** SharePoint에 저장된 Excel 워크시트에 포함된 모든 차트를 나열합니다. id, name, chartType, height, width 및 position을 포함한 차트 속성을 반환합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 차트를 나열할 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_excel_worksheet">
|
||||
**설명:** SharePoint에 저장된 Excel 통합 문서에서 워크시트(탭)와 모든 내용을 영구적으로 제거합니다. 실행 취소할 수 없습니다. 통합 문서에는 최소 하나의 워크시트가 있어야 합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 삭제할 워크시트의 이름. 대소문자를 구분합니다. 이 시트의 모든 데이터, 테이블 및 차트가 영구적으로 제거됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/delete_excel_table">
|
||||
**설명:** SharePoint의 Excel 워크시트에서 테이블을 제거합니다. 테이블 구조(필터링, 서식, 테이블 기능)는 삭제되지만 기본 셀 데이터는 보존됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
- `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요.
|
||||
- `table_name` (string, 필수): 삭제할 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 테이블 삭제 후에도 셀의 데이터는 유지됩니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/list_excel_names">
|
||||
**설명:** SharePoint에 저장된 Excel 통합 문서에 정의된 모든 명명된 범위를 가져옵니다. 명명된 범위는 셀 범위에 대한 사용자 정의 레이블입니다 (예: 'SalesData'는 A1:D100을 가리킴).
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_sharepoint/get_word_document_content">
|
||||
**설명:** SharePoint 문서 라이브러리에 저장된 Word 문서(.docx)에서 텍스트 내용을 다운로드하고 추출합니다. SharePoint에서 Word 문서를 읽는 권장 방법입니다.
|
||||
|
||||
**매개변수:**
|
||||
- `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자.
|
||||
- `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요.
|
||||
- `item_id` (string, 필수): SharePoint에 있는 Word 문서(.docx)의 고유 식별자. list_files 또는 search_files에서 가져오세요.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft SharePoint 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft SharePoint 기능을 가진 에이전트 생성
|
||||
sharepoint_agent = Agent(
|
||||
role="SharePoint 관리자",
|
||||
goal="SharePoint 사이트, 목록 및 문서를 효율적으로 관리",
|
||||
backstory="Microsoft SharePoint 관리 및 콘텐츠 관리 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_sharepoint'] # 모든 SharePoint 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 모든 사이트 가져오기 작업
|
||||
get_sites_task = Task(
|
||||
description="액세스할 수 있는 모든 SharePoint 사이트를 나열하세요.",
|
||||
agent=sharepoint_agent,
|
||||
expected_output="표시 이름과 URL이 포함된 SharePoint 사이트 목록."
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[sharepoint_agent],
|
||||
tasks=[get_sites_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 SharePoint 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Sites.Read.All`, `Sites.ReadWrite.All`).
|
||||
- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**사이트/목록/항목 ID 문제**
|
||||
|
||||
- 사이트, 목록, 항목 ID가 올바른지 다시 확인하세요.
|
||||
- 참조된 리소스가 존재하고 액세스할 수 있는지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft SharePoint 통합 설정 또는 문제 해결에 대한 지원이 필요하시면
|
||||
지원팀에 문의하세요.
|
||||
</Card>
|
||||
326
docs/edge/ko/enterprise/integrations/microsoft_teams.mdx
Normal file
326
docs/edge/ko/enterprise/integrations/microsoft_teams.mdx
Normal file
@@ -0,0 +1,326 @@
|
||||
---
|
||||
title: Microsoft Teams 통합
|
||||
description: "CrewAI를 위한 Microsoft Teams 통합으로 팀 협업 및 커뮤니케이션."
|
||||
icon: "users"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Teams 데이터에 액세스하고, 메시지를 보내고, 회의를 만들고, 채널을 관리할 수 있도록 합니다. AI 기반 자동화로 팀 커뮤니케이션을 자동화하고, 회의를 예약하고, 메시지를 검색하며, 협업 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft Teams 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Teams 액세스 권한이 있는 Microsoft 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft Teams 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft Teams** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. Teams 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_teams/get_teams">
|
||||
**설명:** 사용자가 멤버인 모든 팀을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- 매개변수가 필요하지 않습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_channels">
|
||||
**설명:** 특정 팀의 채널을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/send_message">
|
||||
**설명:** Teams 채널에 메시지를 보냅니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 ID.
|
||||
- `channel_id` (string, 필수): 채널의 ID.
|
||||
- `message` (string, 필수): 메시지 내용.
|
||||
- `content_type` (string, 선택사항): 콘텐츠 유형 (html 또는 text). 옵션: html, text. 기본값: text.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_messages">
|
||||
**설명:** Teams 채널에서 메시지를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 ID.
|
||||
- `channel_id` (string, 필수): 채널의 ID.
|
||||
- `top` (integer, 선택사항): 검색할 메시지 수 (최대 50). 기본값: 20.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/create_meeting">
|
||||
**설명:** Teams 회의를 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `subject` (string, 필수): 회의 제목/제목.
|
||||
- `startDateTime` (string, 필수): 회의 시작 시간 (시간대가 포함된 ISO 8601 형식).
|
||||
- `endDateTime` (string, 필수): 회의 종료 시간 (시간대가 포함된 ISO 8601 형식).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/search_online_meetings_by_join_url">
|
||||
**설명:** 웹 참가 URL로 온라인 회의를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `join_web_url` (string, 필수): 검색할 회의의 웹 참가 URL.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/search_online_meetings_by_meeting_id">
|
||||
**설명:** 외부 Meeting ID로 온라인 회의를 검색합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `join_meeting_id` (string, 필수): 참석자가 참가할 때 사용하는 회의 ID(숫자 코드). 회의 초대에 표시되는 joinMeetingId이며, Graph API meeting id가 아닙니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_meeting">
|
||||
**설명:** 특정 온라인 회의의 세부 정보를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `meeting_id` (string, 필수): Graph API 회의 ID(긴 영숫자 문자열). create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다. 숫자 joinMeetingId와 다릅니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_team_members">
|
||||
**설명:** 특정 팀의 멤버를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다.
|
||||
- `top` (integer, 선택사항): 페이지당 검색할 멤버 수 (1-999). 기본값: 100.
|
||||
- `skip_token` (string, 선택사항): 이전 응답의 페이지네이션 토큰. 응답에 @odata.nextLink가 포함된 경우 $skiptoken 매개변수 값을 추출하여 여기에 전달하면 다음 페이지 결과를 가져올 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/create_channel">
|
||||
**설명:** 팀에 새 채널을 만듭니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다.
|
||||
- `display_name` (string, 필수): Teams에 표시되는 채널 이름. 팀 내에서 고유해야 합니다. 최대 50자.
|
||||
- `description` (string, 선택사항): 채널 목적을 설명하는 선택적 설명. 채널 세부 정보에 표시됩니다. 최대 1024자.
|
||||
- `membership_type` (string, 선택사항): 채널 가시성. 옵션: standard, private. "standard" = 모든 팀 멤버에게 표시, "private" = 명시적으로 추가된 멤버에게만 표시. 기본값: standard.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/get_message_replies">
|
||||
**설명:** 채널의 특정 메시지에 대한 회신을 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다.
|
||||
- `channel_id` (string, 필수): 채널의 고유 식별자. get_channels 작업에서 얻을 수 있습니다.
|
||||
- `message_id` (string, 필수): 상위 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `top` (integer, 선택사항): 페이지당 검색할 회신 수 (1-50). 기본값: 50.
|
||||
- `skip_token` (string, 선택사항): 이전 응답의 페이지네이션 토큰. 응답에 @odata.nextLink가 포함된 경우 $skiptoken 매개변수 값을 추출하여 여기에 전달하면 다음 페이지 결과를 가져올 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/reply_to_message">
|
||||
**설명:** Teams 채널의 메시지에 회신합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다.
|
||||
- `channel_id` (string, 필수): 채널의 고유 식별자. get_channels 작업에서 얻을 수 있습니다.
|
||||
- `message_id` (string, 필수): 회신할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다.
|
||||
- `message` (string, 필수): 회신 내용. HTML의 경우 서식 태그 포함. 텍스트의 경우 일반 텍스트만.
|
||||
- `content_type` (string, 선택사항): 콘텐츠 형식. 옵션: html, text. "text"는 일반 텍스트, "html"은 서식이 있는 리치 텍스트. 기본값: text.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/update_meeting">
|
||||
**설명:** 기존 온라인 회의를 업데이트합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `meeting_id` (string, 필수): 회의의 고유 식별자. create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다.
|
||||
- `subject` (string, 선택사항): 새 회의 제목.
|
||||
- `startDateTime` (string, 선택사항): 시간대가 포함된 ISO 8601 형식의 새 시작 시간. 예: "2024-01-20T10:00:00-08:00".
|
||||
- `endDateTime` (string, 선택사항): 시간대가 포함된 ISO 8601 형식의 새 종료 시간.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_teams/delete_meeting">
|
||||
**설명:** 온라인 회의를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `meeting_id` (string, 필수): 삭제할 회의의 고유 식별자. create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft Teams 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft Teams 기능을 가진 에이전트 생성
|
||||
teams_agent = Agent(
|
||||
role="Teams 코디네이터",
|
||||
goal="Teams 커뮤니케이션 및 회의를 효율적으로 관리",
|
||||
backstory="Microsoft Teams 작업 및 팀 협업 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_teams'] # 모든 Teams 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 팀 및 채널 탐색 작업
|
||||
explore_teams_task = Task(
|
||||
description="내가 멤버인 모든 팀을 나열한 다음 첫 번째 팀의 채널을 가져오세요.",
|
||||
agent=teams_agent,
|
||||
expected_output="팀 및 채널 목록이 표시됨."
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[teams_agent],
|
||||
tasks=[explore_teams_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 메시징 및 커뮤니케이션
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 메시징에 특화된 에이전트 생성
|
||||
messenger = Agent(
|
||||
role="Teams 메신저",
|
||||
goal="Teams 채널에서 메시지 전송 및 검색",
|
||||
backstory="팀 커뮤니케이션 및 메시지 관리에 능숙한 AI 어시스턴트.",
|
||||
apps=['microsoft_teams/send_message', 'microsoft_teams/get_messages']
|
||||
)
|
||||
|
||||
# 메시지 전송 및 최근 메시지 검색 작업
|
||||
messaging_task = Task(
|
||||
description="'your_team_id' 팀의 General 채널에 'Hello team! This is an automated update from our AI assistant.' 메시지를 보낸 다음 해당 채널의 최근 10개 메시지를 검색하세요.",
|
||||
agent=messenger,
|
||||
expected_output="메시지가 성공적으로 전송되고 최근 메시지가 검색됨."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[messenger],
|
||||
tasks=[messaging_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 회의 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# 회의 관리를 위한 에이전트 생성
|
||||
meeting_scheduler = Agent(
|
||||
role="회의 스케줄러",
|
||||
goal="Teams 회의 생성 및 관리",
|
||||
backstory="회의 일정 관리 및 정리를 담당하는 AI 어시스턴트.",
|
||||
apps=['microsoft_teams/create_meeting', 'microsoft_teams/search_online_meetings_by_join_url']
|
||||
)
|
||||
|
||||
# 회의 생성 작업
|
||||
schedule_meeting_task = Task(
|
||||
description="내일 오전 10시에 1시간 동안 진행되는 '주간 팀 동기화' 제목의 Teams 회의를 생성하세요 (시간대가 포함된 적절한 ISO 8601 형식 사용).",
|
||||
agent=meeting_scheduler,
|
||||
expected_output="회의 세부 정보와 함께 Teams 회의가 성공적으로 생성됨."
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[meeting_scheduler],
|
||||
tasks=[schedule_meeting_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 Teams 액세스에 필요한 권한을 가지고 있는지 확인하세요.
|
||||
- 필요한 범위: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`.
|
||||
- OAuth 연결에 필요한 모든 범위가 포함되어 있는지 확인하세요.
|
||||
|
||||
**팀 및 채널 액세스**
|
||||
|
||||
- 액세스하려는 팀의 멤버인지 확인하세요.
|
||||
- 팀 및 채널 ID가 올바른지 다시 확인하세요.
|
||||
- 팀 및 채널 ID는 `get_teams` 및 `get_channels` 작업을 사용하여 얻을 수 있습니다.
|
||||
|
||||
**메시지 전송 문제**
|
||||
|
||||
- `send_message`에 `team_id`, `channel_id`, `message`가 제공되는지 확인하세요.
|
||||
- 지정된 채널에 메시지를 보낼 권한이 있는지 확인하세요.
|
||||
- 메시지 형식에 따라 적절한 `content_type`(text 또는 html)을 선택하세요.
|
||||
|
||||
**회의 생성**
|
||||
|
||||
- `subject`, `startDateTime`, `endDateTime`이 제공되는지 확인하세요.
|
||||
- 날짜/시간 필드에 시간대가 포함된 적절한 ISO 8601 형식을 사용하세요 (예: '2024-01-20T10:00:00-08:00').
|
||||
- 회의 시간이 미래인지 확인하세요.
|
||||
|
||||
**메시지 검색 제한**
|
||||
|
||||
- `get_messages` 작업은 요청당 최대 50개 메시지만 검색할 수 있습니다.
|
||||
- 메시지는 역시간순(최신순)으로 반환됩니다.
|
||||
|
||||
**회의 검색**
|
||||
|
||||
- `search_online_meetings_by_join_url`의 경우 참가 URL이 정확하고 올바르게 형식화되어 있는지 확인하세요.
|
||||
- URL은 완전한 Teams 회의 참가 URL이어야 합니다.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft Teams 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
176
docs/edge/ko/enterprise/integrations/microsoft_word.mdx
Normal file
176
docs/edge/ko/enterprise/integrations/microsoft_word.mdx
Normal file
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: Microsoft Word 통합
|
||||
description: "CrewAI를 위한 Microsoft Word 통합으로 문서 생성 및 관리."
|
||||
icon: "file-word"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 OneDrive 또는 SharePoint에서 Word 문서와 텍스트 파일을 생성, 읽기 및 관리할 수 있도록 합니다. AI 기반 자동화로 문서 생성을 자동화하고, 콘텐츠를 검색하고, 문서 속성을 관리하며, 문서 워크플로를 간소화합니다.
|
||||
|
||||
## 전제 조건
|
||||
|
||||
Microsoft Word 통합을 사용하기 전에 다음 사항을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- Word 및 OneDrive/SharePoint 액세스 권한이 있는 Microsoft 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결
|
||||
|
||||
## Microsoft Word 통합 설정
|
||||
|
||||
### 1. Microsoft 계정 연결
|
||||
|
||||
1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동
|
||||
2. 인증 통합 섹션에서 **Microsoft Word** 찾기
|
||||
3. **연결**을 클릭하고 OAuth 플로우 완료
|
||||
4. 파일 액세스에 필요한 권한 부여
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사
|
||||
|
||||
### 2. 필요한 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 작업
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="microsoft_word/get_documents">
|
||||
**설명:** OneDrive 또는 SharePoint에서 모든 Word 문서를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `select` (string, 선택사항): 반환할 특정 속성 선택.
|
||||
- `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링.
|
||||
- `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장.
|
||||
- `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999).
|
||||
- `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/create_text_document">
|
||||
**설명:** 내용이 있는 텍스트 문서(.txt)를 만듭니다. 읽기 가능하고 편집 가능해야 하는 프로그래밍 방식 콘텐츠 생성에 권장됩니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_name` (string, 필수): 텍스트 문서의 이름 (.txt로 끝나야 함).
|
||||
- `content` (string, 선택사항): 문서의 텍스트 내용. 기본값: "API를 통해 생성된 새 텍스트 문서입니다."
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/get_document_content">
|
||||
**설명:** 문서의 내용을 가져옵니다 (텍스트 파일에서 가장 잘 작동).
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): 문서의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/get_document_properties">
|
||||
**설명:** 문서의 속성과 메타데이터를 가져옵니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): 문서의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/delete_document">
|
||||
**설명:** 문서를 삭제합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): 삭제할 문서의 ID.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/copy_document">
|
||||
**설명:** OneDrive의 새 위치에 문서를 복사합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): 복사할 문서의 ID.
|
||||
- `name` (string, 선택사항): 복사된 문서의 새 이름.
|
||||
- `parent_id` (string, 선택사항): 대상 폴더의 ID (기본값: 루트).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="microsoft_word/move_document">
|
||||
**설명:** OneDrive의 새 위치로 문서를 이동합니다.
|
||||
|
||||
**매개변수:**
|
||||
- `file_id` (string, 필수): 이동할 문서의 ID.
|
||||
- `parent_id` (string, 필수): 대상 폴더의 ID.
|
||||
- `name` (string, 선택사항): 이동된 문서의 새 이름.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예제
|
||||
|
||||
### 기본 Microsoft Word 에이전트 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Microsoft Word 기능을 가진 에이전트 생성
|
||||
word_agent = Agent(
|
||||
role="문서 관리자",
|
||||
goal="Word 문서와 텍스트 파일을 효율적으로 관리",
|
||||
backstory="Microsoft Word 문서 작업 및 콘텐츠 관리 전문 AI 어시스턴트.",
|
||||
apps=['microsoft_word'] # 모든 Word 작업을 사용할 수 있습니다
|
||||
)
|
||||
|
||||
# 새 텍스트 문서 생성 작업
|
||||
create_doc_task = Task(
|
||||
description="'회의노트.txt'라는 새 텍스트 문서를 만들고 내용은 '2024년 1월 회의 노트: 주요 토론 사항 및 실행 항목.'으로 하세요",
|
||||
agent=word_agent,
|
||||
expected_output="새 텍스트 문서 '회의노트.txt'가 성공적으로 생성됨."
|
||||
)
|
||||
|
||||
# 작업 실행
|
||||
crew = Crew(
|
||||
agents=[word_agent],
|
||||
tasks=[create_doc_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**인증 오류**
|
||||
|
||||
- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read.All`, `Files.ReadWrite.All`).
|
||||
- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요.
|
||||
|
||||
**파일 생성 문제**
|
||||
|
||||
- 텍스트 문서를 만들 때 `file_name`이 `.txt` 확장자로 끝나는지 확인하세요.
|
||||
- 대상 위치(OneDrive/SharePoint)에 쓰기 권한이 있는지 확인하세요.
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Microsoft Word 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에
|
||||
문의하세요.
|
||||
</Card>
|
||||
520
docs/edge/ko/enterprise/integrations/notion.mdx
Normal file
520
docs/edge/ko/enterprise/integrations/notion.mdx
Normal file
@@ -0,0 +1,520 @@
|
||||
---
|
||||
title: Notion 연동
|
||||
description: "CrewAI를 위한 Notion 연동을 통한 페이지 및 데이터베이스 관리."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
에이전트가 Notion을 통해 페이지, 데이터베이스, 콘텐츠를 관리할 수 있도록 지원합니다. 페이지 생성 및 업데이트, 콘텐츠 블록 관리, 지식 베이스 구성, AI 기반 자동화를 통해 문서화 작업 흐름을 효율화할 수 있습니다.
|
||||
|
||||
## 필수 조건
|
||||
|
||||
Notion 통합을 사용하기 전에 다음을 확인하세요:
|
||||
|
||||
- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
|
||||
- 적절한 워크스페이스 권한이 있는 Notion 계정
|
||||
- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Notion 계정을 연결함
|
||||
|
||||
## Notion 연동 설정
|
||||
|
||||
### 1. Notion 계정 연결하기
|
||||
|
||||
1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다.
|
||||
2. 인증 통합(Auhtentication Integrations) 섹션에서 **Notion**을(를) 찾습니다.
|
||||
3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다.
|
||||
4. 페이지 및 데이터베이스 관리를 위한 필요한 권한을 부여합니다.
|
||||
5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다.
|
||||
|
||||
### 2. 필수 패키지 설치
|
||||
|
||||
```bash
|
||||
uv add crewai-tools
|
||||
```
|
||||
|
||||
### 3. 환경 변수 설정
|
||||
|
||||
<Note>
|
||||
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
|
||||
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
|
||||
```
|
||||
|
||||
또는 `.env` 파일에 추가하세요:
|
||||
|
||||
```
|
||||
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
|
||||
```
|
||||
|
||||
## 사용 가능한 액션
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="notion/create_page">
|
||||
**설명:** Notion에서 페이지를 생성합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `parent` (object, 필수): 상위 - 새 페이지가 삽입될 상위 페이지 또는 데이터베이스를 나타내는 JSON 객체로, page_id 또는 database_id 키를 포함합니다.
|
||||
```json
|
||||
{
|
||||
"database_id": "DATABASE_ID"
|
||||
}
|
||||
```
|
||||
- `properties` (object, 필수): 속성 - 페이지 속성의 값입니다. 상위가 데이터베이스인 경우, 스키마는 상위 데이터베이스의 속성과 일치해야 합니다.
|
||||
```json
|
||||
{
|
||||
"title": [
|
||||
{
|
||||
"text": {
|
||||
"content": "My Page"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- `icon` (object, 필수): 아이콘 - 페이지 아이콘입니다.
|
||||
```json
|
||||
{
|
||||
"emoji": "🥬"
|
||||
}
|
||||
```
|
||||
- `children` (object, 선택): 자식 - 페이지에 추가할 콘텐츠 블록입니다.
|
||||
```json
|
||||
[
|
||||
{
|
||||
"object": "block",
|
||||
"type": "heading_2",
|
||||
"heading_2": {
|
||||
"rich_text": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": {
|
||||
"content": "Lacinato kale"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
- `cover` (object, 선택): 표지 - 페이지 표지 이미지입니다.
|
||||
```json
|
||||
{
|
||||
"external": {
|
||||
"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/update_page">
|
||||
**설명:** Notion에서 페이지를 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `pageId` (string, 필수): 페이지 ID - 업데이트할 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5").
|
||||
- `icon` (object, 필수): 아이콘 - 페이지 아이콘입니다.
|
||||
```json
|
||||
{
|
||||
"emoji": "🥬"
|
||||
}
|
||||
```
|
||||
- `archived` (boolean, 선택): 보관됨 - 페이지가 보관(삭제)되었는지 여부입니다. true로 설정하면 페이지를 보관합니다. false로 설정하면 보관 해제(복원)합니다.
|
||||
- `properties` (object, 선택): 속성 - 페이지에서 업데이트할 속성 값입니다.
|
||||
```json
|
||||
{
|
||||
"title": [
|
||||
{
|
||||
"text": {
|
||||
"content": "My Updated Page"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- `cover` (object, 선택): 표지 - 페이지 표지 이미지입니다.
|
||||
```json
|
||||
{
|
||||
"external": {
|
||||
"url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/get_page_by_id">
|
||||
**설명:** Notion에서 ID로 페이지를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `pageId` (string, 필수): 페이지 ID - 가져올 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/archive_page">
|
||||
**설명:** Notion에서 페이지를 보관합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `pageId` (string, 필수): 페이지 ID - 보관할 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/search_pages">
|
||||
**설명:** 필터를 사용하여 Notion에서 페이지를 검색합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `searchByTitleFilterSearch` (object, 선택): 불리언 정규형(OR 조건 그룹의 AND 그룹) 형태의 필터입니다.
|
||||
```json
|
||||
{
|
||||
"operator": "OR",
|
||||
"conditions": [
|
||||
{
|
||||
"operator": "AND",
|
||||
"conditions": [
|
||||
{
|
||||
"field": "query",
|
||||
"operator": "$stringExactlyMatches",
|
||||
"value": "meeting notes"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
사용 가능한 필드: `query`, `filter.value`, `direction`, `page_size`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/get_page_content">
|
||||
**설명:** Notion에서 페이지 콘텐츠(블록)를 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `blockId` (string, 필수): 페이지 ID - 해당 블록이나 페이지의 모든 자식 블록을 순서대로 가져오기 위해 Block 또는 Page ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/update_block">
|
||||
**설명:** Notion에서 블록을 업데이트합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `blockId` (string, 필수): 블록 ID - 업데이트할 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
|
||||
- `archived` (boolean, 선택): 보관됨 - true로 설정하면 블록을 보관(삭제)합니다. false로 설정하면 보관 해제(복원)합니다.
|
||||
- `paragraph` (object, 선택): 단락 콘텐츠.
|
||||
```json
|
||||
{
|
||||
"rich_text": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": {
|
||||
"content": "Lacinato kale",
|
||||
"link": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"color": "default"
|
||||
}
|
||||
```
|
||||
- `image` (object, 선택): 이미지 블록.
|
||||
```json
|
||||
{
|
||||
"type": "external",
|
||||
"external": {
|
||||
"url": "https://website.domain/images/image.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `bookmark` (object, 선택): 북마크 블록.
|
||||
```json
|
||||
{
|
||||
"caption": [],
|
||||
"url": "https://companywebsite.com"
|
||||
}
|
||||
```
|
||||
- `code` (object, 선택): 코드 블록.
|
||||
```json
|
||||
{
|
||||
"rich_text": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": {
|
||||
"content": "const a = 3"
|
||||
}
|
||||
}
|
||||
],
|
||||
"language": "javascript"
|
||||
}
|
||||
```
|
||||
- `pdf` (object, 선택): PDF 블록.
|
||||
```json
|
||||
{
|
||||
"type": "external",
|
||||
"external": {
|
||||
"url": "https://website.domain/files/doc.pdf"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `table` (object, 선택): 테이블 블록.
|
||||
```json
|
||||
{
|
||||
"table_width": 2,
|
||||
"has_column_header": false,
|
||||
"has_row_header": false
|
||||
}
|
||||
```
|
||||
- `tableOfContent` (object, 선택): 목차 블록.
|
||||
```json
|
||||
{
|
||||
"color": "default"
|
||||
}
|
||||
```
|
||||
- `additionalFields` (object, 선택): 추가 블록 유형.
|
||||
```json
|
||||
{
|
||||
"child_page": {
|
||||
"title": "Lacinato kale"
|
||||
},
|
||||
"child_database": {
|
||||
"title": "My database"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/get_block_by_id">
|
||||
**설명:** Notion에서 ID로 블록을 가져옵니다.
|
||||
|
||||
**파라미터:**
|
||||
- `blockId` (string, 필수): 블록 ID - 가져올 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="notion/delete_block">
|
||||
**설명:** Notion에서 블록을 삭제합니다.
|
||||
|
||||
**파라미터:**
|
||||
- `blockId` (string, 필수): 블록 ID - 삭제할 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6").
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 기본 Notion Agent 설정
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create an agent with Notion capabilities
|
||||
notion_agent = Agent(
|
||||
role="Documentation Manager",
|
||||
goal="Manage documentation and knowledge base in Notion efficiently",
|
||||
backstory="An AI assistant specialized in content management and documentation.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# Task to create a meeting notes page
|
||||
create_notes_task = Task(
|
||||
description="Create a new meeting notes page in the team database with today's date and agenda items",
|
||||
agent=notion_agent,
|
||||
expected_output="Meeting notes page created successfully with structured content"
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[notion_agent],
|
||||
tasks=[create_notes_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 특정 Notion 도구 필터링
|
||||
|
||||
```python
|
||||
|
||||
content_manager = Agent(
|
||||
role="Content Manager",
|
||||
goal="Create and manage content pages efficiently",
|
||||
backstory="An AI assistant that focuses on content creation and management.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# Task to manage content workflow
|
||||
content_workflow = Task(
|
||||
description="Create a new project documentation page and add structured content blocks for requirements and specifications",
|
||||
agent=content_manager,
|
||||
expected_output="Project documentation created with organized content sections"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[content_manager],
|
||||
tasks=[content_workflow]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 지식 베이스 관리
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
knowledge_curator = Agent(
|
||||
role="Knowledge Curator",
|
||||
goal="Curate and organize knowledge base content in Notion",
|
||||
backstory="An experienced knowledge manager who organizes and maintains comprehensive documentation.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# Task to curate knowledge base
|
||||
curation_task = Task(
|
||||
description="""
|
||||
1. 새로운 제품 기능과 관련된 기존 문서 페이지를 검색합니다.
|
||||
2. 적절한 구조로 포괄적인 기능 문서 페이지를 생성합니다.
|
||||
3. 코드 예제, 이미지 및 관련 리소스에 대한 링크를 추가합니다.
|
||||
4. 기존 페이지를 업데이트하여 새 문서에 대한 교차 참조를 추가합니다.
|
||||
""",
|
||||
agent=knowledge_curator,
|
||||
expected_output="Feature documentation created and integrated with existing knowledge base"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[knowledge_curator],
|
||||
tasks=[curation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 콘텐츠 구조 및 구성
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
content_organizer = Agent(
|
||||
role="Content Organizer",
|
||||
goal="Organize and structure content blocks for optimal readability",
|
||||
backstory="An AI assistant that specializes in content structure and user experience.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# Task to organize content structure
|
||||
organization_task = Task(
|
||||
description="""
|
||||
1. Get content from existing project pages
|
||||
2. Analyze the structure and identify improvement opportunities
|
||||
3. Update content blocks to use proper headings, tables, and formatting
|
||||
4. Add table of contents and improve navigation between related pages
|
||||
5. Create templates for future documentation consistency
|
||||
""",
|
||||
agent=content_organizer,
|
||||
expected_output="Content reorganized with improved structure and navigation"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[content_organizer],
|
||||
tasks=[organization_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
### 자동화된 문서화 워크플로우
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
doc_automator = Agent(
|
||||
role="Documentation Automator",
|
||||
goal="Automate documentation workflows and maintenance",
|
||||
backstory="An AI assistant that automates repetitive documentation tasks.",
|
||||
apps=['notion']
|
||||
)
|
||||
|
||||
# Complex documentation automation task
|
||||
automation_task = Task(
|
||||
description="""
|
||||
1. 최근 30일 이내에 업데이트되지 않은 페이지 검색
|
||||
2. 오래된 콘텐츠 블록 검토 및 업데이트
|
||||
3. 일관된 포맷으로 주간 팀 업데이트 페이지 생성
|
||||
4. 프로젝트 페이지에 상태 표시기 및 진행 상황 추적 추가
|
||||
5. 월간 문서 헬스 리포트 생성
|
||||
6. 완료된 프로젝트 페이지를 아카이브 섹션에 정리 및 보관
|
||||
""",
|
||||
agent=doc_automator,
|
||||
expected_output="업데이트된 콘텐츠, 주간 리포트, 정리된 아카이브로 문서화 자동화 완료"
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[doc_automator],
|
||||
tasks=[automation_task]
|
||||
)
|
||||
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
**권한 오류**
|
||||
|
||||
- Notion 계정이 대상 워크스페이스에 대한 편집 권한이 있는지 확인하세요
|
||||
- OAuth 연결에 Notion API에 필요한 범위가 포함되어 있는지 확인하세요
|
||||
- 페이지와 데이터베이스가 인증된 통합에 공유되어 있는지 확인하세요
|
||||
|
||||
**잘못된 페이지 및 블록 ID**
|
||||
|
||||
- 페이지 ID 및 블록 ID가 올바른 UUID 형식인지 다시 확인하세요
|
||||
- 참조되는 페이지와 블록이 존재하고 접근 가능한지 확인하세요
|
||||
- 새 페이지를 생성할 때 상위 페이지 또는 데이터베이스 ID가 유효한지 검증하세요
|
||||
|
||||
**속성 스키마 문제**
|
||||
|
||||
- 데이터베이스에 페이지를 생성할 때 페이지 속성이 데이터베이스 스키마와 일치하는지 확인하세요
|
||||
- 대상 데이터베이스에 대해 속성 이름과 타입이 올바른지 확인하세요
|
||||
- 페이지를 생성하거나 업데이트할 때 필수 속성이 포함되어 있는지 확인하세요
|
||||
|
||||
**콘텐츠 블록 구조**
|
||||
|
||||
- 블록 콘텐츠가 Notion의 리치 텍스트 형식 사양을 따르는지 확인하세요
|
||||
- 중첩된 블록 구조가 올바르게 포맷되어 있는지 확인하세요
|
||||
- 미디어 URL이 접근 가능하며 올바른 형식인지 확인하세요
|
||||
|
||||
**검색 및 필터 문제**
|
||||
|
||||
- 검색 쿼리가 올바르게 포맷되어 있고 비어 있지 않은지 확인하세요
|
||||
- 필터 공식에서 유효한 필드명을 사용하세요: `query`, `filter.value`, `direction`, `page_size`
|
||||
- 복잡한 필터 조건을 만들기 전에 간단한 검색을 테스트하세요
|
||||
|
||||
**상위-하위 관계**
|
||||
|
||||
- 하위 페이지를 생성하기 전에 상위 페이지 또는 데이터베이스가 존재하는지 확인하세요
|
||||
- 상위 컨테이너에 대한 적절한 권한이 있는지 확인하세요
|
||||
- 데이터베이스 스키마가 설정하려는 속성을 허용하는지 확인하세요
|
||||
|
||||
**리치 텍스트 및 미디어 콘텐츠**
|
||||
|
||||
- 외부 이미지, PDF, 북마크의 URL이 접근 가능한지 확인하세요
|
||||
- 리치 텍스트 포매팅이 Notion의 API 사양을 따르는지 확인하세요
|
||||
- 코드 블록의 언어 타입이 Notion에서 지원되는지 확인하세요
|
||||
|
||||
**아카이브 및 삭제 작업**
|
||||
|
||||
- 아카이브(복구 가능)와 삭제(영구적)의 차이를 이해하세요
|
||||
- 대상 콘텐츠를 아카이브 또는 삭제할 수 있는 권한이 있는지 확인하세요
|
||||
- 여러 페이지 또는 블록에 영향을 줄 수 있는 대량 작업은 신중히 진행하세요
|
||||
|
||||
### 도움 받기
|
||||
|
||||
<Card
|
||||
title="도움이 필요하신가요?"
|
||||
icon="headset"
|
||||
href="mailto:support@crewai.com"
|
||||
>
|
||||
Notion 연동 설정 또는 문제 해결에 대해 지원팀에 문의해 주세요.
|
||||
</Card>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user