mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-06 23:49:24 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
474
docs/edge/ko/guides/flows/conversational-flows.mdx
Normal file
474
docs/edge/ko/guides/flows/conversational-flows.mdx
Normal file
@@ -0,0 +1,474 @@
|
||||
---
|
||||
title: 대화형 Flow
|
||||
description: 턴마다 kickoff, 메시지 기록, 의도 라우팅, 트레이싱, WebSocket 브리지로 멀티턴 채팅 앱을 만듭니다.
|
||||
icon: comments
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
대화형 앱은 각 사용자 입력을 **동일한 세션 id**로 **새 flow 실행**으로 처리합니다. CrewAI는 메시지 기록, 선택적 의도 분류, 지연 트레이싱, UI 브리지, 그리고 대화형 flow용 로컬 `flow.chat()` REPL을 제공합니다.
|
||||
|
||||
| 개념 | 구현 |
|
||||
|------|------|
|
||||
| 세션 id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
|
||||
| 사용자 입력 | `handle_turn(message)`가 그래프 실행 전 `state.messages`에 추가 |
|
||||
| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `handle_turn`로 대화 계속 |
|
||||
| 세션 전체 트레이스 | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
|
||||
|
||||
## 턴 API
|
||||
|
||||
REST, WebSocket, 테스트, 커스텀 UI에서 오는 모든 사용자 메시지에는 **`flow.handle_turn(message, session_id=...)`**를 사용하세요. 대화형 `Flow`를 로컬 터미널 채팅 루프로 실행하고 싶을 때는 **`flow.chat()`**을 사용하세요.
|
||||
|
||||
`Flow.kickoff()`는 `user_message=` 또는 `session_id=` 키워드 인자를 받지 않습니다. 대화형 flow에서는 `handle_turn()`이 보류 중인 메시지를 저장하고 내부적으로 `kickoff(inputs={"id": session_id})`를 호출합니다.
|
||||
|
||||
| API | 용도 |
|
||||
|-----|------|
|
||||
| `handle_turn(message, session_id=...)` | 대화형 `Flow`용 한 턴 편의 래퍼 |
|
||||
| `chat()` | 대화형 `Flow`용 로컬 터미널 REPL |
|
||||
| `kickoff(inputs={...})` | 대화형 턴 처리 없이 flow를 직접 실행 |
|
||||
| `ask()` | 한 스텝 **내부** 블로킹 프롬프트 (마법사, 확인) |
|
||||
| `@human_feedback` | **스텝 출력** 승인/거부 — 다음 채팅 줄이 아님 |
|
||||
| `ChatSession.handle_turn(...)` | `handle_turn` 위의 전송 계층 (SSE / WebSocket) |
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
```python
|
||||
from uuid import uuid4
|
||||
|
||||
from crewai import Flow
|
||||
from crewai.flow import listen
|
||||
from crewai.experimental.conversational import (
|
||||
ConversationConfig,
|
||||
ConversationState,
|
||||
)
|
||||
|
||||
|
||||
@ConversationConfig(defer_trace_finalization=True)
|
||||
class SupportFlow(Flow[ConversationState]):
|
||||
conversational = True
|
||||
|
||||
def route_turn(self, context):
|
||||
message = self.state.current_user_message or ""
|
||||
if "주문" in message or "order" in message.lower():
|
||||
return "order"
|
||||
if "안녕" in message or "goodbye" in message.lower():
|
||||
return "goodbye"
|
||||
return "help"
|
||||
|
||||
@listen("order")
|
||||
def handle_order(self):
|
||||
reply = "주문이 배송 중입니다."
|
||||
self.append_assistant_message(reply)
|
||||
return reply
|
||||
|
||||
@listen("help")
|
||||
def handle_help(self):
|
||||
reply = "무엇을 도와드릴까요?"
|
||||
self.append_assistant_message(reply)
|
||||
return reply
|
||||
|
||||
@listen("goodbye")
|
||||
def handle_goodbye(self):
|
||||
reply = "안녕히 가세요!"
|
||||
self.append_assistant_message(reply)
|
||||
return reply
|
||||
|
||||
|
||||
session_id = str(uuid4())
|
||||
flow = SupportFlow()
|
||||
|
||||
try:
|
||||
flow.handle_turn("주문 어디까지 왔나요?", session_id=session_id)
|
||||
flow.handle_turn("반품은 어떻게 하나요?", session_id=session_id)
|
||||
finally:
|
||||
flow.finalize_session_traces() # 전체 대화에 대한 단일 trace 링크
|
||||
```
|
||||
|
||||
## 턴 생명주기
|
||||
|
||||
각 `handle_turn`은 다음 파이프라인을 실행합니다:
|
||||
|
||||
1. **`_configure_conversational_kickoff`** — `session_id` / `user_message`를 `inputs`에 병합, `ConversationalConfig` 적용, 설정 시 지연 트레이싱 활성화.
|
||||
2. **상태 복원** — `inputs["id"]`가 있고 `@persist`가 설정되면 최신 스냅샷 로드.
|
||||
3. **`FlowStarted`** — 지연 세션의 첫 턴에서만 발생.
|
||||
4. **`prepare_conversational_turn`** — 사용자 메시지를 `state.messages`에 추가, `last_user_message` 설정, `last_intent` 초기화, `intents` / `default_intents` + `intent_llm` 설정 시 분류.
|
||||
5. **그래프 실행** — `@start` → `@router` → `@listen` 핸들러.
|
||||
6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음.
|
||||
|
||||
핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.
|
||||
|
||||
## `ConversationalConfig` (클래스 수준 기본값)
|
||||
|
||||
`Flow` 서브클래스에 `conversational_config: ClassVar[ConversationalConfig | None]`로 설정합니다.
|
||||
|
||||
| 필드 | 기본값 | 목적 |
|
||||
|------|--------|------|
|
||||
| `default_intents` | `None` | kickoff 전 자동 분류용 outcome 라벨 |
|
||||
| `intent_llm` | `None` | 분류용 모델 (intent 사용 시 필수) |
|
||||
| `interactive_prompt` | `"You: "` | `kickoff(interactive=True)` 프롬프트 |
|
||||
| `interactive_timeout` | `None` | 대화형 모드 줄 단위 타임아웃 |
|
||||
| `exit_commands` | `exit`, `quit` | 대화형 모드 종료 단어 |
|
||||
| `defer_trace_finalization` | `True` | 턴 간 하나의 trace batch 유지 |
|
||||
|
||||
`intents=` 및 `intent_llm=` 키워드로 kickoff마다 재정의할 수 있습니다.
|
||||
|
||||
## `ChatState` (권장 persist 형태)
|
||||
|
||||
```python
|
||||
from crewai.flow import ChatState
|
||||
|
||||
|
||||
class MyChatState(ChatState):
|
||||
# 상속: id, messages, last_user_message, last_intent, session_ready
|
||||
research_turn_count: int = 0
|
||||
custom_flag: bool = False
|
||||
```
|
||||
|
||||
| 필드 | 역할 |
|
||||
|------|------|
|
||||
| `id` | 세션 UUID (`session_id` / `inputs["id"]`와 동일) |
|
||||
| `messages` | LLM 기록용 `{role, content}` 리스트 |
|
||||
| `last_user_message` | 이번 턴의 최신 사용자 입력 |
|
||||
| `last_intent` | 분류 후 라우트 라벨 (사용 시) |
|
||||
| `session_ready` | 일회성 bootstrap 플래그 |
|
||||
|
||||
`ConversationalInputs`는 `kickoff(inputs={...})`용 `TypedDict`: `id`, `user_message`, `last_intent`.
|
||||
|
||||
## `Flow` 대화 API
|
||||
|
||||
### `kickoff` / `kickoff_async` 파라미터
|
||||
|
||||
| 파라미터 | 목적 |
|
||||
|----------|------|
|
||||
| `user_message` | 이번 턴 텍스트 (또는 `{"role": "user", "content": "..."}`) |
|
||||
| `session_id` | 대화 UUID → `inputs["id"]` / `state.id` |
|
||||
| `intents` | kickoff 전 `classify_intent`용 outcome 라벨 |
|
||||
| `intent_llm` | 분류 LLM (`intents`와 함께 필수) |
|
||||
| `interactive` | `ask()` CLI 루프 (로컬 데모 전용) |
|
||||
| `interactive_prompt` | 대화형 모드 프롬프트 |
|
||||
| `interactive_timeout` | 줄 단위 `ask()` 타임아웃 |
|
||||
| `exit_commands` | 대화형 모드 종료 단어 |
|
||||
| `inputs` | 추가 상태 필드 |
|
||||
| `restore_from_state_id` | 다른 persist flow에서 fork 복원 |
|
||||
|
||||
### 인스턴스 속성
|
||||
|
||||
| 속성 | 목적 |
|
||||
|------|------|
|
||||
| `conversational_config` | 클래스 수준 `ConversationalConfig` |
|
||||
| `defer_trace_finalization` | 인스턴스 플래그; kickoff 시 config에서 자동 설정 |
|
||||
| `suppress_flow_events` | 콘솔 flow 패널 숨김; **트레이싱은 계속 기록** |
|
||||
| `stream` | 스트리밍; `ChatSession.handle_turn(..., stream=True)`와 함께 |
|
||||
|
||||
### 메서드 및 프로퍼티
|
||||
|
||||
| 이름 | 설명 |
|
||||
|------|------|
|
||||
| `append_message(role, content, **extra)` | `state.messages`에 추가 |
|
||||
| `conversation_messages` | LLM 호출용 읽기 전용 기록 |
|
||||
| `classify_intent(text, outcomes, *, llm, context=None)` | outcome 매핑 (`@human_feedback`와 동일 collapse) |
|
||||
| `receive_user_message(text, *, outcomes=None, llm=None)` | 사용자 메시지 추가; 선택적 `last_intent` |
|
||||
| `finalize_session_traces()` | 지연 `flow_finished` 발생 및 세션 trace batch 종료 |
|
||||
| `_should_defer_trace_finalization()` | 턴별 trace 종료 지연 여부 |
|
||||
| `input_history` | `ask()` 프롬프트/응답 감사 기록 |
|
||||
|
||||
### 모듈 헬퍼 (`crewai.flow.conversation`)
|
||||
|
||||
테스트 또는 커스텀 오케스트레이션용:
|
||||
|
||||
| 함수 | 설명 |
|
||||
|------|------|
|
||||
| `normalize_kickoff_inputs(...)` | 대화 kwargs를 `inputs`에 병합 |
|
||||
| `get_conversation_messages(flow)` | 상태 또는 내부 버퍼에서 메시지 읽기 |
|
||||
| `append_message(flow, ...)` | 인스턴스 메서드와 동일 |
|
||||
| `prepare_conversational_turn(flow, ...)` | 턴 수화 (보통 kickoff가 호출) |
|
||||
| `receive_user_message(flow, ...)` | 인스턴스 메서드와 동일 |
|
||||
| `set_state_field(flow, name, value)` | dict 또는 Pydantic 상태 필드 설정 |
|
||||
| `get_conversational_config(flow)` | 클래스 `conversational_config` 읽기 |
|
||||
| `input_history_to_messages(entries)` | `input_history`를 LLM 메시지 형식으로 |
|
||||
|
||||
## 의도 라우팅 패턴
|
||||
|
||||
### A. `ConversationalConfig`로 사전 분류 (가장 단순)
|
||||
|
||||
`default_intents`와 `intent_llm` 설정. 각 kickoff가 `@router` 전에 분류; `route()`에서 `self.state.last_intent` 읽기.
|
||||
|
||||
### B. `@router` 내부에서 분류 (풍부한 프롬프트)
|
||||
|
||||
`default_intents=None`으로 kickoff는 메시지만 추가. `route()`에서 커스텀 프롬프트로 `classify_intent` 호출:
|
||||
|
||||
```python
|
||||
@router(bootstrap)
|
||||
def route(self):
|
||||
intent = self.classify_intent(
|
||||
self._routing_prompt(self.state.last_user_message),
|
||||
("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
|
||||
llm=self.conversational_config.intent_llm or "gpt-4o-mini",
|
||||
)
|
||||
self.state.last_intent = intent
|
||||
return intent
|
||||
```
|
||||
|
||||
웹 리서치나 다단계 tool이 필요하면 **`@listen("RESEARCH")`** 등에서 `Agent.kickoff()`와 tool 사용 — 단순 `LLM.call()` 대신.
|
||||
|
||||
## flow가 끝났지만 사용자는 계속 대화할 때
|
||||
|
||||
`FlowFinished`는 **이번 그래프 실행**이 완료됨을 의미합니다. 같은 `session_id`로 또 다른 `kickoff`로 대화가 이어집니다. `@persist`가 `messages`, 플래그, 컨텍스트를 복원합니다.
|
||||
|
||||
**Persist 패턴:** 전체 `Flow` 클래스보다 **단일 종료 스텝**(예: `finalize`)에 `@persist`를 두는 것이 좋습니다. 클래스 수준 persist는 매 메서드 후 저장하며, `load_state`는 최신 행을 사용해 같은 턴의 핸들러 업데이트를 놓칠 수 있습니다.
|
||||
|
||||
후속 채팅 줄에 `@human_feedback`를 쓰지 마세요. 특정 스텝 출력을 사람이 승인해야 할 때만 사용하세요.
|
||||
|
||||
## 대화형 `Flow` (실험적)
|
||||
|
||||
<Warning>
|
||||
**실험적 기능입니다.** 대화형 `Flow`의 API 표면(`conversational = True`,
|
||||
`handle_turn`, `ConversationConfig`, `RouterConfig`, `ConversationState`,
|
||||
내장 그래프와 헬퍼)은 `crewai.experimental` 하위에 있으며 정식 출시
|
||||
전까지 변경될 수 있습니다. 특정 동작에 의존한다면 CrewAI 버전을 고정하고
|
||||
변경 사항이 있는지 changelog를 확인하세요. 피드백과 이슈 환영합니다.
|
||||
</Warning>
|
||||
|
||||
`Flow` 서브클래스에 `conversational = True`를 지정하면 대화형 챗 그래프가 활성화됩니다. 베이스 `Flow`가 `@start` / `@router` / `converse_turn` / `end_conversation` 그래프를 노출하고, `state.messages`를 관리하며, router LLM을 구동하고, 턴 간 trace 배치를 열린 상태로 유지합니다. 여러분은 **커스텀 라우트**만 작성하면 되고, 나머지는 프레임워크가 담당합니다.
|
||||
|
||||
LLM 기반 라우터와 라우트별 핸들러로 멀티턴 챗을 만들고 싶지만 라이프사이클을 직접 배선하고 싶지 않을 때 사용하세요. 완전한 제어가 필요하면 위의 `Flow[ChatState]`로 내려가세요.
|
||||
|
||||
### 빠른 예제
|
||||
|
||||
```python
|
||||
from crewai import LLM, Flow
|
||||
from crewai.flow import listen
|
||||
from crewai.experimental.conversational import (
|
||||
ConversationConfig,
|
||||
ConversationState,
|
||||
RouterConfig,
|
||||
)
|
||||
|
||||
|
||||
ROUTER_LLM = LLM(model="gpt-4o-mini")
|
||||
|
||||
|
||||
@ConversationConfig(
|
||||
system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.",
|
||||
llm=ROUTER_LLM,
|
||||
router=RouterConfig(), # 라우트 + 설명은 @listen 핸들러에서 자동 발견
|
||||
)
|
||||
class SupportFlow(Flow[ConversationState]):
|
||||
conversational = True
|
||||
|
||||
@listen("INTERNET_SEARCH")
|
||||
def handle_internet_search(self) -> str:
|
||||
"""Fresh web research, current news, real-time lookups."""
|
||||
...
|
||||
self.append_assistant_message(reply)
|
||||
return reply
|
||||
|
||||
@listen("CREWAI_DOCS")
|
||||
def handle_crewai_docs(self) -> str:
|
||||
"""Look up the CrewAI documentation for framework/API questions."""
|
||||
...
|
||||
self.append_assistant_message(reply)
|
||||
return reply
|
||||
|
||||
|
||||
flow = SupportFlow()
|
||||
try:
|
||||
flow.handle_turn("뭘 할 수 있어?") # converse(빌트인)로 라우팅
|
||||
flow.handle_turn("AI 뉴스를 웹에서 찾아줘.") # INTERNET_SEARCH로 라우팅
|
||||
flow.handle_turn("첫 번째 결과를 요약해줘.") # 다시 converse로 라우팅
|
||||
finally:
|
||||
flow.finalize_session_traces()
|
||||
```
|
||||
|
||||
로컬 터미널 채팅에는 `chat()`을 사용하세요:
|
||||
|
||||
```python
|
||||
def kickoff() -> None:
|
||||
SupportFlow().chat()
|
||||
```
|
||||
|
||||
`chat()`은 `handle_turn()`을 REPL로 감싸고, `exit` / `quit`에서 종료하며, 기본적으로 빈 줄을 건너뛰고, 세션이 끝날 때 `finalize_session_traces()`를 호출합니다.
|
||||
|
||||
### `ConversationConfig`
|
||||
|
||||
클래스 단위의 챗 기본값을 부착하는 클래스 데코레이터입니다.
|
||||
|
||||
| 필드 | 기본값 | 목적 |
|
||||
|------|--------|------|
|
||||
| `system_prompt` | i18n `slices.conversational_system_prompt` | 빌트인 `converse_turn`이 사용하는 system 메시지. 빈 문자열(`""`)을 전달하면 system 메시지를 끕니다. |
|
||||
| `llm` | `None` | 대화용 LLM (빌트인 `converse_turn`이 사용하고 router 폴백도 됨). |
|
||||
| `router` | `None` | LLM 기반 라우팅을 위한 `RouterConfig`. 없으면 항상 `converse`로 떨어집니다. |
|
||||
| `answer_from_history_prompt` | 프레임워크 기본값 | 선택적인 `answer_from_history` 라우트용 system 메시지. |
|
||||
| `answer_from_history_llm` | `None` | 설정되면 `answer_from_history` 단축 경로가 활성화됩니다. |
|
||||
| `intent_llm` | `None` | 레거시 `intents=`/`default_intents` 사전 분류용 LLM. |
|
||||
| `default_intents` | `None` | 레거시 사전 분류용 outcome 레이블. |
|
||||
| `visible_agent_outputs` | `None` | `"all"` 또는 `append_agent_result()` 결과를 사용자에게 공개로 승격할 에이전트 이름 목록. |
|
||||
| `defer_trace_finalization` | `True` | `handle_turn()` 호출들 사이에서 하나의 trace 배치를 열어 둡니다. |
|
||||
|
||||
### `RouterConfig`와 자동 생성되는 라우트 카탈로그
|
||||
|
||||
```python
|
||||
RouterConfig(
|
||||
prompt="선택적인 도메인 프레이밍 (정책, 톤, 페르소나).",
|
||||
response_format=MyRoute, # 선택; 없으면 자동 생성
|
||||
llm=ROUTER_LLM, # ConversationConfig.llm으로 폴백
|
||||
routes=["INTERNET_SEARCH", "CREWAI_DOCS"], # 선택; 리스너에서 추론
|
||||
route_descriptions={
|
||||
"INTERNET_SEARCH": "이 라우트만 docstring 대신 사용할 설명.",
|
||||
},
|
||||
default_intent="converse", # LLM 호출 실패 또는 LLM 없음일 때 사용
|
||||
fallback_intent="converse", # LLM이 잘못된 라우트를 반환할 때 사용
|
||||
intent_field="intent",
|
||||
)
|
||||
```
|
||||
|
||||
router에 전달되는 프롬프트는 자동으로 만들어집니다. 각 라우트의 설명은 다음 우선순위로 결정됩니다:
|
||||
|
||||
1. `RouterConfig.route_descriptions[label]` — 명시적 오버라이드.
|
||||
2. `Flow.builtin_route_descriptions[label]` — `converse`, `end`, `answer_from_history`용 프레임워크 캐닝 텍스트 (router LLM용으로 다듬어진 문구).
|
||||
3. `@listen(label)` 핸들러 docstring의 첫 줄(비어있지 않은 줄).
|
||||
4. 빈 문자열 (라우트만 카탈로그에 등장하고 설명은 없음).
|
||||
|
||||
실제 사용에서 **새 라우트를 추가하는 방법은 `@listen("X")` + 한 줄짜리 docstring**입니다:
|
||||
|
||||
```python
|
||||
@listen("INTERNET_SEARCH")
|
||||
def handle_internet_search(self) -> str:
|
||||
"""Fresh web research, current news, real-time lookups."""
|
||||
...
|
||||
```
|
||||
|
||||
…그러면 router LLM은 다음을 봅니다:
|
||||
|
||||
```
|
||||
Routes:
|
||||
- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions.
|
||||
- INTERNET_SEARCH: Fresh web research, current news, real-time lookups.
|
||||
- converse: Ordinary chat, follow-ups, summaries, clarifications…
|
||||
- end: User signals the conversation is finished (goodbye, exit, done).
|
||||
```
|
||||
|
||||
`RouterConfig.prompt`는 **도메인 프레이밍** (어시스턴트 페르소나, 비즈니스 규칙, 톤)을 위한 자리입니다. 라우트 카탈로그는 자동 생성되니 `prompt` 안에 라우트 목록을 넣지 마세요. 핸들러를 추가하는 순간 동기화가 깨집니다.
|
||||
|
||||
### 빌트인 라우트
|
||||
|
||||
| 라우트 | 핸들러 | 목적 |
|
||||
|--------|--------|------|
|
||||
| `converse` | `converse_turn` | 기본 챗 핸들러. system prompt + 정식 메시지 히스토리와 함께 `ConversationConfig.llm`을 호출합니다. |
|
||||
| `end` | `end_conversation` | `state.ended = True`로 설정하고 종료 응답을 보냅니다. |
|
||||
| `answer_from_history` | `answer_from_history_turn` | 선택적. `ConversationConfig.answer_from_history_llm`이 설정되어 있고 메시지를 히스토리만으로 답할 수 있을 때 라우팅됩니다. |
|
||||
|
||||
서브클래스에 같은 이름의 핸들러를 정의하면 어떤 것이든 오버라이드할 수 있습니다.
|
||||
|
||||
### `handle_turn()` 시맨틱
|
||||
|
||||
`flow.handle_turn(message)`는 한 턴을 실행합니다:
|
||||
|
||||
1. 그래프가 다시 실행되도록 턴 단위 실행 추적(`_completed_methods`, `_method_outputs`)을 초기화합니다 — 이게 없으면 동일 인스턴스에서 반복 `kickoff` 호출 시 `Flow.kickoff_async`가 `inputs={"id": ...}`를 체크포인트 복원으로 간주해 2번째 턴부터 단락 회로가 발생합니다.
|
||||
2. 사용자 메시지를 `state.messages`에 추가하고 `current_user_message` / `last_user_message`를 설정합니다. `last_intent`는 **이전 턴 값이 유지**되어 router LLM이 신호로 활용할 수 있습니다.
|
||||
3. `conversation_start` → `route_conversation` → 선택된 `@listen` 핸들러 순으로 실행됩니다.
|
||||
4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다).
|
||||
5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다.
|
||||
|
||||
채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다.
|
||||
|
||||
### 로컬 REPL용 `chat()`
|
||||
|
||||
`flow.chat()`은 `handle_turn()` 위에 얹은 바로 쓸 수 있는 터미널 래퍼입니다:
|
||||
|
||||
```python
|
||||
flow = SupportFlow()
|
||||
flow.chat()
|
||||
```
|
||||
|
||||
일반적인 로컬 루프를 처리합니다:
|
||||
|
||||
1. 사용자 메시지를 입력받습니다.
|
||||
2. `exit` / `quit`, `EOFError`, `KeyboardInterrupt`에서 멈춥니다.
|
||||
3. `handle_turn(message, session_id=...)`를 호출합니다.
|
||||
4. 어시스턴트 결과를 출력합니다.
|
||||
5. `finally` 블록에서 지연된 세션 trace를 finalize합니다.
|
||||
|
||||
주입 가능한 I/O로 터미널 동작을 커스터마이즈할 수 있습니다:
|
||||
|
||||
```python
|
||||
flow.chat(
|
||||
session_id="demo-session",
|
||||
prompt="You: ",
|
||||
assistant_prefix="Assistant: ",
|
||||
exit_commands=("exit", "quit", "bye"),
|
||||
)
|
||||
```
|
||||
|
||||
웹 앱, 백그라운드 worker, 테스트, 커스텀 transport에서는 계속 `handle_turn()`을 직접 사용하세요.
|
||||
|
||||
### 커스텀 router 동작
|
||||
|
||||
매 라우팅 결정마다 사이드 이펙트(이벤트 버스 셋업, 텔레메트리)를 실행하려면 `route_turn`을 오버라이드하세요:
|
||||
|
||||
```python
|
||||
class SupportFlow(Flow[ConversationState]):
|
||||
conversational = True
|
||||
|
||||
def route_turn(self, context: dict[str, Any]) -> str | None:
|
||||
self.event_bus = MyBus(self)
|
||||
return super().route_turn(context)
|
||||
```
|
||||
|
||||
LLM router를 우회해 프로그램적으로 라우트를 선택하려면 `route_turn`에서 문자열을 반환하세요. `None`을 반환하면 `_route_with_config(...)`로 떨어집니다.
|
||||
|
||||
### `append_assistant_message`와 `append_agent_result`
|
||||
|
||||
`@listen(label)` 핸들러 안에서 두 가지 중 선택하세요:
|
||||
|
||||
- `self.append_assistant_message(text)` — 사용자에게 보이는 어시스턴트 턴을 `state.messages`에 추가합니다. 다음 턴의 `converse_turn`이 이 내용을 보게 됩니다.
|
||||
- `self.append_agent_result(agent_name, result, visibility="private")` — 구조화된 이벤트를 `state.events`에, 스레드를 `state.agent_threads[agent_name]`에 기록합니다. public 가시성은 자동으로 `append_assistant_message`도 호출합니다. 정식 히스토리를 더럽히지 말아야 할 임시 작업에는 private을 쓰세요.
|
||||
|
||||
`ConversationConfig.visible_agent_outputs`로 특정 에이전트의 private 결과를 전역적으로 public으로 승격할 수 있습니다 (`"all"` 또는 이름 리스트).
|
||||
|
||||
## 턴 간 트레이싱
|
||||
|
||||
`defer_trace_finalization=True` (`ConversationalConfig` 기본값):
|
||||
|
||||
- 채팅 세션 전체에 **하나의 trace batch**.
|
||||
- 첫 턴에만 **`flow_started`**; `finalize_session_traces()`에서 **`flow_finished`** 한 번.
|
||||
- 턴별 `kickoff`는 “Trace batch finalized”를 출력하지 않음.
|
||||
- **중첩 작업** (`Agent.kickoff()`, crew, Exa tool)은 **부모** batch에 추가; 내부 `AgentExecutor` flow가 세션 batch를 조기 종료하지 않음.
|
||||
|
||||
```python
|
||||
flow.chat(session_id=session_id)
|
||||
```
|
||||
|
||||
`flow.chat()`이 `finalize_session_traces()`를 대신 호출합니다. `handle_turn()`이나 `kickoff(...)`로 직접 루프를 소유하는 경우, 세션이 끝날 때 `finalize_session_traces()`를 호출하세요.
|
||||
|
||||
`suppress_flow_events=True`는 Rich 콘솔 패널만 숨깁니다. trace 및 method 이벤트는 계속 발생합니다.
|
||||
|
||||
### 대화형 `Flow` trace 수명 주기
|
||||
|
||||
실험적 [대화형 `Flow`](#대화형-flow-실험적)는 동일한 tracing 수명 주기를 따릅니다. `defer_trace_finalization` 기본값이 `True`이므로 각 `handle_turn()`이 세션 trace를 열어 둡니다. 세션 끝에서 항상 finalize하세요 — REPL/루프를 `try/finally`로 감싸고 종료 시 `flow.finalize_session_traces()`를 호출하세요. 호출하지 않으면 batch가 열린 채 남아 마지막 대화가 export되지 않을 수 있습니다.
|
||||
|
||||
## 스트리밍
|
||||
|
||||
`Flow` 클래스에 `stream = True`. `kickoff(...)`가 표준 이벤트 버스를 통해 `assistant_delta` 등 이벤트를 발생시킵니다.
|
||||
|
||||
## import
|
||||
|
||||
```python
|
||||
from crewai.flow import (
|
||||
ChatState,
|
||||
ConversationalConfig,
|
||||
ConversationalInputs,
|
||||
Flow,
|
||||
listen,
|
||||
persist,
|
||||
router,
|
||||
start,
|
||||
)
|
||||
```
|
||||
|
||||
## 참고
|
||||
|
||||
- [Flow 상태 관리 마스터하기](/ko/guides/flows/mastering-flow-state)
|
||||
- [첫 Flow 만들기](/ko/guides/flows/first-flow)
|
||||
- 데모: `lib/crewai/runner_conversational_flow_simple.py`
|
||||
550
docs/edge/ko/guides/flows/first-flow.mdx
Normal file
550
docs/edge/ko/guides/flows/first-flow.mdx
Normal file
@@ -0,0 +1,550 @@
|
||||
---
|
||||
title: 첫 Flow 빌드하기
|
||||
description: 정밀한 실행 제어가 가능한 구조화된 이벤트 기반 워크플로우를 만드는 방법을 배웁니다.
|
||||
icon: diagram-project
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Flows로 AI 워크플로우 제어하기
|
||||
|
||||
CrewAI Flows는 AI 오케스트레이션의 새로운 수준을 제공합니다. 즉, AI agent crew의 협업 능력과 절차적 프로그래밍의 정밀성 및 유연성을 결합합니다. crew가 agent 협업에서 탁월하다면, flow는 AI 시스템의 다양한 구성요소가 어떻게 그리고 언제 상호작용하는지에 대해 세밀하게 제어할 수 있게 해줍니다.
|
||||
|
||||
이 가이드에서는 원하는 주제에 대한 포괄적인 학습 가이드를 생성하는 강력한 CrewAI Flow를 만드는 과정을 소개합니다. 이 튜토리얼을 통해 Flow가 일반 코드, 직접적인 LLM 호출, crew 기반 처리 등을 결합하여 AI 워크플로우에 구조적이고 이벤트 기반의 제어를 제공하는 방법을 시연할 것입니다.
|
||||
|
||||
### 플로우의 강력한 점
|
||||
|
||||
플로우를 통해 다음과 같은 작업을 할 수 있습니다:
|
||||
|
||||
1. **다양한 AI 상호작용 패턴 결합** - 복잡한 협업 작업에는 crew를 사용하고, 더 단순한 작업에는 직접적인 LLM 호출과 절차적 논리에는 일반 코드를 사용하세요.
|
||||
2. **이벤트 기반 시스템 구축** - 구성 요소가 특정 이벤트와 데이터 변경에 어떻게 반응할지 정의할 수 있습니다.
|
||||
3. **구성 요소 간 상태 유지** - 애플리케이션의 다양한 부분 간에 데이터를 공유하고 변환할 수 있습니다.
|
||||
4. **외부 시스템과 통합** - 데이터베이스, API, 사용자 인터페이스와 같은 외부 시스템과 AI 워크플로우를 원활하게 연동할 수 있습니다.
|
||||
5. **복잡한 실행 경로 생성** - 조건부 분기, 병렬 처리 및 동적인 워크플로우를 설계할 수 있습니다.
|
||||
|
||||
### 무엇을 구축하고 배우게 될까요
|
||||
|
||||
이 가이드가 끝나면 여러분은 다음을 달성할 수 있습니다:
|
||||
|
||||
1. **사용자 입력, AI 계획, 그리고 멀티 에이전트 콘텐츠 생성이 결합된 정교한 콘텐츠 생성 시스템을 구축**했습니다.
|
||||
2. **시스템의 다양한 구성 요소 간 정보 흐름을 오케스트레이션(조율)**했습니다.
|
||||
3. **이전 단계의 완료에 따라 각 단계가 반응하는 이벤트 기반 아키텍처를 구현**했습니다.
|
||||
4. **더 복잡한 AI 애플리케이션을 확장하고 맞춤화할 수 있는 기반을 구축**했습니다.
|
||||
|
||||
이번 가이드의 creator flow는 다음과 같은 훨씬 더 발전된 애플리케이션에 적용할 수 있는 기본 패턴을 보여줍니다:
|
||||
|
||||
- 여러 전문화된 하위 시스템을 결합하는 대화형 AI assistant
|
||||
- AI 기반 변환을 포함한 복잡한 데이터 처리 파이프라인
|
||||
- 외부 서비스 및 API와 통합되는 자율적 에이전트
|
||||
- 인간이 개입하는 프로세스를 포함한 다단계 의사결정 시스템
|
||||
|
||||
함께 여러분의 첫 번째 flow를 만들어 봅시다!
|
||||
|
||||
## 사전 준비 사항
|
||||
|
||||
시작하기 전에 다음을 확인하세요:
|
||||
|
||||
1. [설치 가이드](/ko/installation)에 따라 CrewAI를 설치했는지 확인하십시오.
|
||||
2. [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)에 따라 환경에 LLM API 키를 설정했는지 확인하십시오.
|
||||
3. Python에 대한 기본적인 이해
|
||||
|
||||
## 1단계: 새로운 CrewAI Flow 프로젝트 생성
|
||||
|
||||
먼저, CLI를 사용하여 새로운 CrewAI Flow 프로젝트를 생성해봅시다. 이 명령어는 필요한 모든 디렉터리와 템플릿 파일이 포함된 기본 프로젝트 구조를 만들어줍니다.
|
||||
|
||||
```bash
|
||||
crewai create flow guide_creator_flow
|
||||
cd guide_creator_flow
|
||||
```
|
||||
|
||||
이렇게 하면 flow에 필요한 기본 구조를 가진 프로젝트가 생성됩니다.
|
||||
|
||||
<Frame caption="CrewAI Framework 개요">
|
||||
<img src="/images/flows.png" alt="CrewAI Framework 개요" />
|
||||
</Frame>
|
||||
|
||||
## 2단계: 프로젝트 구조 이해하기
|
||||
|
||||
생성된 프로젝트는 다음과 같은 구조를 가지고 있습니다. 시작용 embedded crew는 클래식 Python/YAML 레이아웃을 사용합니다. Flow 안에서 JSON-first crew를 사용하려면 crew 폴더에 `crew.jsonc`와 `agents/*.jsonc`를 만들고 `crewai.project.load_crew`로 로드하세요. 예시는 [Flows](/ko/concepts/flows#building-your-crews)를 참고하세요.
|
||||
|
||||
```
|
||||
guide_creator_flow/
|
||||
├── .gitignore
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── .env
|
||||
└── src/
|
||||
└── guide_creator_flow/
|
||||
├── __init__.py
|
||||
├── main.py
|
||||
├── crews/
|
||||
│ └── poem_crew/
|
||||
│ ├── config/
|
||||
│ │ ├── agents.yaml
|
||||
│ │ └── tasks.yaml
|
||||
│ └── poem_crew.py
|
||||
└── tools/
|
||||
└── custom_tool.py
|
||||
```
|
||||
|
||||
이 구조는 flow의 다양한 구성 요소를 명확하게 분리해줍니다:
|
||||
- `src/guide_creator_flow/main.py` 파일의 main flow 로직
|
||||
- `src/guide_creator_flow/crews` 디렉터리의 특화된 crew들
|
||||
- `src/guide_creator_flow/tools` 디렉터리의 custom tool들
|
||||
|
||||
이제 이 구조를 수정하여 guide creator flow를 만들 것입니다. 이 flow는 포괄적인 학습 가이드 생성을 조직하는 역할을 합니다.
|
||||
|
||||
## 3단계: Content Writer Crew 추가
|
||||
|
||||
우리 flow에는 콘텐츠 생성 프로세스를 처리할 전문화된 crew가 필요합니다. CrewAI CLI를 사용하여 content writer crew를 추가해봅시다:
|
||||
|
||||
```bash
|
||||
crewai flow add-crew content-crew
|
||||
```
|
||||
|
||||
이 명령어는 자동으로 crew에 필요한 디렉터리와 템플릿 파일을 생성합니다. content writer crew는 가이드의 각 섹션을 작성하고 검토하는 역할을 담당하며, 메인 애플리케이션에 의해 조율되는 전체 flow 내에서 작업하게 됩니다.
|
||||
|
||||
## 4단계: 콘텐츠 작가 Crew 구성
|
||||
|
||||
이제 콘텐츠 작가 crew를 JSONC로 구성합니다. 가이드의 고품질 콘텐츠를 만들기 위해 협업하는 두 명의 전문 에이전트 - 작가와 리뷰어 - 를 설정합니다.
|
||||
|
||||
1. `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`를 만듭니다:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"role": "Educational Content Writer",
|
||||
"goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.",
|
||||
"backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.",
|
||||
"llm": "provider/model-id",
|
||||
"settings": {
|
||||
"verbose": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`를 만듭니다:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"role": "Educational Content Reviewer and Editor",
|
||||
"goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.",
|
||||
"backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.",
|
||||
"llm": "provider/model-id",
|
||||
"settings": {
|
||||
"verbose": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`provider/model-id`를 사용하는 모델로 바꾸세요. 예: `openai/gpt-4o`, `gemini/gemini-2.0-flash-001`, `anthropic/claude-sonnet-4-6`.
|
||||
|
||||
3. `src/guide_creator_flow/crews/content_crew/crew.jsonc`를 만듭니다:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "Content Crew",
|
||||
"agents": ["content_writer", "content_reviewer"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "write_section_task",
|
||||
"description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}",
|
||||
"expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.",
|
||||
"agent": "content_writer",
|
||||
"markdown": true
|
||||
},
|
||||
{
|
||||
"name": "review_section_task",
|
||||
"description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.",
|
||||
"expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.",
|
||||
"agent": "content_reviewer",
|
||||
"context": ["write_section_task"],
|
||||
"markdown": true
|
||||
}
|
||||
],
|
||||
"process": "sequential",
|
||||
"verbose": true
|
||||
}
|
||||
```
|
||||
|
||||
`context` 필드를 통해 리뷰어가 작가의 출력을 사용할 수 있습니다.
|
||||
|
||||
4. `src/guide_creator_flow/crews/content_crew/content_crew.py`를 작은 loader로 교체합니다:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
from crewai.project import load_crew
|
||||
|
||||
|
||||
def kickoff_content_crew(inputs: dict):
|
||||
crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
|
||||
return crew.kickoff(inputs={**default_inputs, **inputs})
|
||||
```
|
||||
|
||||
이 loader는 런타임에 `crew.jsonc`를 `Crew`로 바꿉니다. 이 crew는 독립적으로도 작동할 수 있지만, 우리의 플로우에서는 더 큰 시스템의 일부로 오케스트레이션됩니다.
|
||||
|
||||
## 5단계: 플로우(Flow) 생성
|
||||
|
||||
이제 가장 흥미로운 부분입니다 - 전체 가이드 생성 과정을 오케스트레이션할 플로우를 만드는 단계입니다. 이곳에서 우리는 일반 Python 코드, 직접적인 LLM 호출, 그리고 우리의 컨텐츠 제작 crew를 결합하여 일관된 시스템으로 만듭니다.
|
||||
|
||||
우리의 플로우는 다음과 같은 일을 수행합니다:
|
||||
1. 주제와 대상 독자 수준에 대한 사용자 입력을 받습니다.
|
||||
2. 구조화된 가이드 개요를 만들기 위해 직접 LLM 호출을 합니다.
|
||||
3. 컨텐츠 writer crew를 사용하여 각 섹션을 순차적으로 처리합니다.
|
||||
4. 모든 내용을 결합하여 최종 종합 문서를 완성합니다.
|
||||
|
||||
`main.py` 파일에 우리의 플로우를 생성해봅시다:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python
|
||||
import json
|
||||
import os
|
||||
from typing import List, Dict
|
||||
from pydantic import BaseModel, Field
|
||||
from crewai import LLM
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew
|
||||
|
||||
# Define our models for structured data
|
||||
class Section(BaseModel):
|
||||
title: str = Field(description="Title of the section")
|
||||
description: str = Field(description="Brief description of what the section should cover")
|
||||
|
||||
class GuideOutline(BaseModel):
|
||||
title: str = Field(description="Title of the guide")
|
||||
introduction: str = Field(description="Introduction to the topic")
|
||||
target_audience: str = Field(description="Description of the target audience")
|
||||
sections: List[Section] = Field(description="List of sections in the guide")
|
||||
conclusion: str = Field(description="Conclusion or summary of the guide")
|
||||
|
||||
# Define our flow state
|
||||
class GuideCreatorState(BaseModel):
|
||||
topic: str = ""
|
||||
audience_level: str = ""
|
||||
guide_outline: GuideOutline = None
|
||||
sections_content: Dict[str, str] = {}
|
||||
|
||||
class GuideCreatorFlow(Flow[GuideCreatorState]):
|
||||
"""Flow for creating a comprehensive guide on any topic"""
|
||||
|
||||
@start()
|
||||
def get_user_input(self):
|
||||
"""Get input from the user about the guide topic and audience"""
|
||||
print("\n=== Create Your Comprehensive Guide ===\n")
|
||||
|
||||
# Get user input
|
||||
self.state.topic = input("What topic would you like to create a guide for? ")
|
||||
|
||||
# Get audience level with validation
|
||||
while True:
|
||||
audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower()
|
||||
if audience in ["beginner", "intermediate", "advanced"]:
|
||||
self.state.audience_level = audience
|
||||
break
|
||||
print("Please enter 'beginner', 'intermediate', or 'advanced'")
|
||||
|
||||
print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n")
|
||||
return self.state
|
||||
|
||||
@listen(get_user_input)
|
||||
def create_guide_outline(self, state):
|
||||
"""Create a structured outline for the guide using a direct LLM call"""
|
||||
print("Creating guide outline...")
|
||||
|
||||
# Initialize the LLM
|
||||
llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline)
|
||||
|
||||
# Create the messages for the outline
|
||||
messages = [
|
||||
{"role": "system", "content": "You are a helpful assistant designed to output JSON."},
|
||||
{"role": "user", "content": f"""
|
||||
Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners.
|
||||
|
||||
The outline should include:
|
||||
1. A compelling title for the guide
|
||||
2. An introduction to the topic
|
||||
3. 4-6 main sections that cover the most important aspects of the topic
|
||||
4. A conclusion or summary
|
||||
|
||||
For each section, provide a clear title and a brief description of what it should cover.
|
||||
"""}
|
||||
]
|
||||
|
||||
# Make the LLM call with JSON response format
|
||||
response = llm.call(messages=messages)
|
||||
|
||||
# Parse the JSON response
|
||||
outline_dict = json.loads(response)
|
||||
self.state.guide_outline = GuideOutline(**outline_dict)
|
||||
|
||||
# Ensure output directory exists before saving
|
||||
os.makedirs("output", exist_ok=True)
|
||||
|
||||
# Save the outline to a file
|
||||
with open("output/guide_outline.json", "w") as f:
|
||||
json.dump(outline_dict, f, indent=2)
|
||||
|
||||
print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections")
|
||||
return self.state.guide_outline
|
||||
|
||||
@listen(create_guide_outline)
|
||||
def write_and_compile_guide(self, outline):
|
||||
"""Write all sections and compile the guide"""
|
||||
print("Writing guide sections and compiling...")
|
||||
completed_sections = []
|
||||
|
||||
# Process sections one by one to maintain context flow
|
||||
for section in outline.sections:
|
||||
print(f"Processing section: {section.title}")
|
||||
|
||||
# Build context from previous sections
|
||||
previous_sections_text = ""
|
||||
if completed_sections:
|
||||
previous_sections_text = "# Previously Written Sections\n\n"
|
||||
for title in completed_sections:
|
||||
previous_sections_text += f"## {title}\n\n"
|
||||
previous_sections_text += self.state.sections_content.get(title, "") + "\n\n"
|
||||
else:
|
||||
previous_sections_text = "No previous sections written yet."
|
||||
|
||||
# Run the content crew for this section
|
||||
result = kickoff_content_crew(inputs={
|
||||
"section_title": section.title,
|
||||
"section_description": section.description,
|
||||
"audience_level": self.state.audience_level,
|
||||
"previous_sections": previous_sections_text,
|
||||
"draft_content": ""
|
||||
})
|
||||
|
||||
# Store the content
|
||||
self.state.sections_content[section.title] = result.raw
|
||||
completed_sections.append(section.title)
|
||||
print(f"Section completed: {section.title}")
|
||||
|
||||
# Compile the final guide
|
||||
guide_content = f"# {outline.title}\n\n"
|
||||
guide_content += f"## Introduction\n\n{outline.introduction}\n\n"
|
||||
|
||||
# Add each section in order
|
||||
for section in outline.sections:
|
||||
section_content = self.state.sections_content.get(section.title, "")
|
||||
guide_content += f"\n\n{section_content}\n\n"
|
||||
|
||||
# Add conclusion
|
||||
guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n"
|
||||
|
||||
# Save the guide
|
||||
with open("output/complete_guide.md", "w") as f:
|
||||
f.write(guide_content)
|
||||
|
||||
print("\nComplete guide compiled and saved to output/complete_guide.md")
|
||||
return "Guide creation completed successfully"
|
||||
|
||||
def kickoff():
|
||||
"""Run the guide creator flow"""
|
||||
GuideCreatorFlow().kickoff()
|
||||
print("\n=== Flow Complete ===")
|
||||
print("Your comprehensive guide is ready in the output directory.")
|
||||
print("Open output/complete_guide.md to view it.")
|
||||
|
||||
def plot():
|
||||
"""Generate a visualization of the flow"""
|
||||
flow = GuideCreatorFlow()
|
||||
flow.plot("guide_creator_flow")
|
||||
print("Flow visualization saved to guide_creator_flow.html")
|
||||
|
||||
if __name__ == "__main__":
|
||||
kickoff()
|
||||
```
|
||||
|
||||
이 플로우에서 일어나는 과정을 분석해봅시다:
|
||||
|
||||
1. 구조화된 데이터에 대한 Pydantic 모델을 정의하여 타입 안전성과 명확한 데이터 표현을 보장합니다.
|
||||
2. 플로우 단계별로 데이터를 유지하기 위한 state 클래스를 생성합니다.
|
||||
3. 세 가지 주요 플로우 단계를 구현합니다:
|
||||
- `@start()` 데코레이터로 사용자 입력을 받습니다.
|
||||
- 직접 LLM 호출로 가이드 개요를 생성합니다.
|
||||
- content crew로 각 섹션을 처리합니다.
|
||||
4. `@listen()` 데코레이터를 활용해 단계 간 이벤트 기반 관계를 설정합니다.
|
||||
|
||||
이것이 바로 flows의 힘입니다 - 다양한 처리 유형(사용자 상호작용, 직접적인 LLM 호출, crew 기반 작업)을 하나의 일관된 이벤트 기반 시스템으로 결합할 수 있습니다.
|
||||
|
||||
## 6단계: 환경 변수 설정하기
|
||||
|
||||
프로젝트 루트에 `.env` 파일을 생성하고 API 키를 입력하세요. 공급자 구성에 대한 자세한 내용은 [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요.
|
||||
|
||||
```sh .env
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
# or
|
||||
GEMINI_API_KEY=your_gemini_api_key
|
||||
# or
|
||||
ANTHROPIC_API_KEY=your_anthropic_api_key
|
||||
```
|
||||
|
||||
## 7단계: 의존성 설치
|
||||
|
||||
필수 의존성을 설치합니다:
|
||||
|
||||
```bash
|
||||
crewai install
|
||||
```
|
||||
|
||||
## 8단계: Flow 실행하기
|
||||
|
||||
이제 여러분의 flow가 실제로 작동하는 모습을 볼 차례입니다! CrewAI CLI를 사용하여 flow를 실행하세요:
|
||||
|
||||
```bash
|
||||
crewai flow kickoff
|
||||
```
|
||||
|
||||
이 명령어를 실행하면 flow가 다음과 같이 작동하는 것을 확인할 수 있습니다:
|
||||
1. 주제와 대상 수준을 입력하라는 메시지가 표시됩니다.
|
||||
2. 가이드의 체계적인 개요를 생성합니다.
|
||||
3. 각 섹션을 처리할 때 content writer와 reviewer가 협업합니다.
|
||||
4. 마지막으로 모든 내용을 종합하여 완성도 높은 가이드를 만듭니다.
|
||||
|
||||
이는 여러 구성요소(인공지능 및 비인공지능 모두)가 포함된 복잡한 프로세스를 flows가 어떻게 조정할 수 있는지 보여줍니다.
|
||||
|
||||
## 9단계: Flow 시각화하기
|
||||
|
||||
flow의 강력한 기능 중 하나는 구조를 시각화할 수 있다는 점입니다.
|
||||
|
||||
```bash
|
||||
crewai flow plot
|
||||
```
|
||||
|
||||
이 명령은 flow의 구조를 보여주는 HTML 파일을 생성하며, 각 단계 간의 관계와 그 사이에 흐르는 데이터를 확인할 수 있습니다. 이러한 시각화는 복잡한 flow를 이해하고 디버깅하는 데 매우 유용합니다.
|
||||
|
||||
## 10단계: 출력물 검토하기
|
||||
|
||||
flow가 완료되면 `output` 디렉토리에서 두 개의 파일을 찾을 수 있습니다:
|
||||
|
||||
1. `guide_outline.json`: 가이드의 구조화된 개요가 포함되어 있습니다
|
||||
2. `complete_guide.md`: 모든 섹션이 포함된 종합적인 가이드입니다
|
||||
|
||||
이 파일들을 잠시 검토하고 여러분이 구축한 시스템을 되돌아보세요. 이 시스템은 사용자 입력, 직접적인 AI 상호작용, 협업 에이전트 작업을 결합하여 복잡하고 고품질의 결과물을 만들어냅니다.
|
||||
|
||||
## 가능한 것의 예술: 첫 번째 Flow 그 이상
|
||||
|
||||
이 가이드에서 배운 내용은 훨씬 더 정교한 AI 시스템을 만드는 데 기반이 됩니다. 다음은 이 기본 flow를 확장할 수 있는 몇 가지 방법입니다:
|
||||
|
||||
### 사용자 상호작용 향상
|
||||
|
||||
더욱 인터랙티브한 플로우를 만들 수 있습니다:
|
||||
- 입력 및 출력을 위한 웹 인터페이스
|
||||
- 실시간 진행 상황 업데이트
|
||||
- 인터랙티브한 피드백 및 개선 루프
|
||||
- 다단계 사용자 상호작용
|
||||
|
||||
### 추가 처리 단계 추가하기
|
||||
|
||||
다음과 같은 추가 단계로 flow를 확장할 수 있습니다:
|
||||
- 개요 작성 전 사전 리서치
|
||||
- 일러스트를 위한 이미지 생성
|
||||
- 기술 가이드용 코드 스니펫 생성
|
||||
- 최종 품질 보증 및 사실 확인
|
||||
|
||||
### 더 복잡한 Flows 생성하기
|
||||
|
||||
더 정교한 flow 패턴을 구현할 수 있습니다:
|
||||
- 사용자 선호도나 콘텐츠 유형에 따른 조건 분기
|
||||
- 독립적인 섹션의 병렬 처리
|
||||
- 피드백과 함께하는 반복적 개선 루프
|
||||
- 외부 API 및 서비스와의 통합
|
||||
|
||||
### 다양한 도메인에 적용하기
|
||||
|
||||
동일한 패턴을 사용하여 다음과 같은 flow를 만들 수 있습니다:
|
||||
- **대화형 스토리텔링**: 사용자 입력을 바탕으로 개인화된 이야기를 생성
|
||||
- **비즈니스 인텔리전스**: 데이터를 처리하고, 인사이트를 도출하며, 리포트를 생성
|
||||
- **제품 개발**: 아이디어 구상, 디자인, 기획을 지원
|
||||
- **교육 시스템**: 개인화된 학습 경험을 제공
|
||||
|
||||
## 주요 특징 시연
|
||||
|
||||
이 guide creator flow에서는 CrewAI의 여러 강력한 기능을 시연합니다:
|
||||
|
||||
1. **사용자 상호작용**: flow는 사용자로부터 직접 입력을 수집합니다
|
||||
2. **직접적인 LLM 호출**: 효율적이고 단일 목적의 AI 상호작용을 위해 LLM 클래스를 사용합니다
|
||||
3. **Pydantic을 통한 구조화된 데이터**: 타입 안정성을 보장하기 위해 Pydantic 모델을 사용합니다
|
||||
4. **컨텍스트를 활용한 순차 처리**: 섹션을 순서대로 작성하면서 이전 섹션을 컨텍스트로 제공합니다
|
||||
5. **멀티 에이전트 crew**: 콘텐츠 생성을 위해 특화된 에이전트(writer 및 reviewer)를 활용합니다
|
||||
6. **상태 관리**: 프로세스의 다양한 단계에 걸쳐 상태를 유지합니다
|
||||
7. **이벤트 기반 아키텍처**: 이벤트에 응답하기 위해 `@listen` 데코레이터를 사용합니다
|
||||
|
||||
## 플로우 구조 이해하기
|
||||
|
||||
플로우의 주요 구성 요소를 분해하여 자신만의 플로우를 만드는 방법을 이해할 수 있도록 도와드리겠습니다:
|
||||
|
||||
### 1. 직접 LLM 호출
|
||||
|
||||
Flow를 사용하면 간단하고 구조화된 응답이 필요할 때 언어 모델에 직접 호출할 수 있습니다:
|
||||
|
||||
```python
|
||||
llm = LLM(
|
||||
model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude...
|
||||
response_format=GuideOutline
|
||||
)
|
||||
response = llm.call(messages=messages)
|
||||
```
|
||||
|
||||
특정하고 구조화된 출력이 필요할 때 crew를 사용하는 것보다 더 효율적입니다.
|
||||
|
||||
### 2. 이벤트 기반 아키텍처
|
||||
|
||||
Flows는 데코레이터를 사용하여 컴포넌트 간의 관계를 설정합니다:
|
||||
|
||||
```python
|
||||
@start()
|
||||
def get_user_input(self):
|
||||
# First step in the flow
|
||||
# ...
|
||||
|
||||
@listen(get_user_input)
|
||||
def create_guide_outline(self, state):
|
||||
# This runs when get_user_input completes
|
||||
# ...
|
||||
```
|
||||
|
||||
이렇게 하면 애플리케이션에 명확하고 선언적인 구조가 만들어집니다.
|
||||
|
||||
### 3. 상태 관리
|
||||
|
||||
flow는 단계 간 상태를 유지하여 데이터를 쉽게 공유할 수 있습니다:
|
||||
|
||||
```python
|
||||
class GuideCreatorState(BaseModel):
|
||||
topic: str = ""
|
||||
audience_level: str = ""
|
||||
guide_outline: GuideOutline = None
|
||||
sections_content: Dict[str, str] = {}
|
||||
```
|
||||
|
||||
이 방식은 flow 전반에 걸쳐 데이터를 추적하고 변환하는 타입 안전(type-safe)한 방법을 제공합니다.
|
||||
|
||||
### 4. Crew 통합
|
||||
|
||||
Flow는 복잡한 협업 작업을 위해 crew와 원활하게 통합될 수 있습니다:
|
||||
|
||||
```python
|
||||
result = kickoff_content_crew(inputs={
|
||||
"section_title": section.title,
|
||||
# ...
|
||||
})
|
||||
```
|
||||
|
||||
이를 통해 애플리케이션의 각 부분에 적합한 도구를 사용할 수 있습니다. 단순한 작업에는 직접적인 LLM 호출을, 복잡한 협업에는 crew를 사용할 수 있습니다.
|
||||
|
||||
## 다음 단계
|
||||
|
||||
이제 첫 번째 flow를 구축했으니 다음을 시도해 볼 수 있습니다:
|
||||
|
||||
1. 더 복잡한 flow 구조와 패턴을 실험해 보세요.
|
||||
2. `@router()`를 사용하여 flow에서 조건부 분기를 만들어 보세요.
|
||||
3. 더 복잡한 병렬 실행을 위해 `and_` 및 `or_` 함수를 탐색해 보세요.
|
||||
4. flow를 외부 API, 데이터베이스 또는 사용자 인터페이스에 연결해 보세요.
|
||||
5. 여러 전문화된 crew를 하나의 flow에서 결합해 보세요.
|
||||
6. [대화형 Flow](/ko/guides/flows/conversational-flows)로 멀티턴 채팅 앱 구축 (`kickoff` per message, `ChatSession`, 지연 트레이싱)
|
||||
|
||||
<Check>
|
||||
축하합니다! 정규 코드, 직접적인 LLM 호출, crew 기반 처리를 결합하여 포괄적인 가이드를 생성하는 첫 번째 CrewAI Flow를 성공적으로 구축하셨습니다. 이러한 기초적인 역량을 바탕으로 절차적 제어와 협업적 인텔리전스를 결합하여 복잡하고 다단계의 문제를 해결할 수 있는 점점 더 정교한 AI 애플리케이션을 만들 수 있습니다.
|
||||
</Check>
|
||||
125
docs/edge/ko/guides/flows/inputs-id-deprecation.mdx
Normal file
125
docs/edge/ko/guides/flows/inputs-id-deprecation.mdx
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "inputs.id에서 restore_from_state_id로 마이그레이션"
|
||||
description: "더 이상 지원되지 않는 inputs.id 하이드레이션에서 지원되는 restore_from_state_id 필드로 @persist 흐름을 이동"
|
||||
icon: "arrow-right-arrow-left"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
`inputs` 내에서 `id`를 전달하여 `@persist` 흐름을 하이드레이트하는 것은 **더 이상 지원되지 않으며**
|
||||
향후 릴리스에서 제거될 예정입니다. 대체품인 `restore_from_state_id`는 CrewAI **v1.14.5 이상**에서 사용할 수 있으며,
|
||||
아래 단계는 업그레이드 후 적용됩니다.
|
||||
</Warning>
|
||||
|
||||
## 개요
|
||||
|
||||
이전 실행에서 `@persist` 흐름을 하이드레이트하는 문서화된 방법은
|
||||
해당 실행의 UUID를 `inputs.id`로 전달하는 것입니다. CrewAI는 이제
|
||||
`inputs` 페이로드를 과부하하지 않고 동일한 하이드레이션을 수행하는 전용 필드인
|
||||
`restore_from_state_id`를 제공합니다 — 그리고 하이드레이션 키를 새로운 실행의
|
||||
정체성과 결합하지 않습니다.
|
||||
|
||||
## 마이그레이션
|
||||
|
||||
현재 `inputs={"id": ...}`로 `@persist` 흐름을 시작하는 경우:
|
||||
|
||||
```python
|
||||
# 더 이상 지원되지 않음
|
||||
flow = CounterFlow()
|
||||
flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"})
|
||||
```
|
||||
|
||||
`restore_from_state_id`로 전환하십시오:
|
||||
|
||||
```python
|
||||
# 지원됨
|
||||
flow = CounterFlow()
|
||||
flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv")
|
||||
```
|
||||
|
||||
두 모드는 서로 다른 계보 의미론을 가지고 있습니다:
|
||||
|
||||
- `inputs={"id": <uuid>}` (더 이상 지원되지 않음) — **재개**: 제공된
|
||||
id 아래에 기록이 작성되어 동일한 `flow_uuid` 이력이 확장됩니다.
|
||||
- `restore_from_state_id=<uuid>` — **분기**: 스냅샷에서 상태를 하이드레이트한 후
|
||||
새로운 `state.id` 아래에 기록합니다. 원본 흐름의 이력은 보존됩니다.
|
||||
|
||||
대부분의 프로덕션 시나리오에서는 — 이전 상태에서 시드된 흐름을 다시 실행하는 경우 — 분기가
|
||||
필요합니다. 전체 정신 모델은 [Flow State 마스터링](/ko/guides/flows/mastering-flow-state)을 참조하십시오.
|
||||
|
||||
CrewAI AMP REST API를 통해 흐름을 시작하는 경우, 아래 [AMP](#amp)에서
|
||||
동일한 페이로드 마이그레이션을 참조하십시오.
|
||||
|
||||
## 왜 `@persist`에 대해 `inputs.id`를 더 이상 지원하지 않습니까?
|
||||
|
||||
`inputs.id`는 현재 이전 실행에서 `@persist` 흐름을 재개하는 문서화된 방법입니다. 문제는
|
||||
동일한 UUID가 두 가지 작업을 동시에 수행한다는 것입니다:
|
||||
|
||||
1. **어떤 스냅샷에서 `@persist`가 하이드레이트되는지를 선택합니다** — 해당 UUID 아래에 저장된 상태를 로드합니다.
|
||||
2. **새 실행의 흐름 실행 ID가 됩니다** (`state.id`는 SDK에서; 일부 컨텍스트에서는 `flow_id`로 표시됨) — 이
|
||||
시작에서의 모든 `@persist` 기록도 동일한 UUID 아래에 작성됩니다.
|
||||
|
||||
이 이중 역할이 이 가이드에서 설명하는 문제의 근본 원인입니다. 제공된 UUID가 새 실행의 id이기도 하므로,
|
||||
동일한 `inputs.id`를 전달하는 두 번의 시작은 두 개의 별도 실행이 아닙니다 — 그들은 id를 공유하고,
|
||||
지속성 기록을 공유하며, (AMP에서) 실행 목록에서 행을 공유합니다. "이 스냅샷에서 하이드레이트하지만,
|
||||
이 실행을 별도로 기록하십시오"라고 말할 방법이 없습니다.
|
||||
|
||||
`restore_from_state_id`가 그 분리입니다. 이는 `@persist`에 어떤 스냅샷에서 하이드레이트할지를 알려주며,
|
||||
새 실행이 새로운 `state.id`를 받을 수 있도록 합니다. 하이드레이션 소스와 기록된 실행은 더 이상 동일한 UUID가 아닙니다 — 이는 대부분의 프로덕션 시나리오에서 실제로 원하는 것입니다.
|
||||
|
||||
## 제거 일정
|
||||
|
||||
`@persist` 하이드레이션을 위한 `inputs.id`는 CrewAI의 향후 릴리스에서 제거될 예정입니다. 즉각적인 강제 종료는 없으며 — 기존 흐름은 계속 작동합니다 — 하지만 v1.14.5 이상으로 업그레이드하면,
|
||||
새 코드에서는 `restore_from_state_id`를 사용해야 하며, 기존 흐름은 다음 편리한 기회에 마이그레이션해야 합니다.
|
||||
|
||||
## AMP
|
||||
|
||||
흐름을 CrewAI AMP에 배포하는 경우, 마이그레이션은 배포된 팀에 전송되는 시작 페이로드로 확장되며,
|
||||
`inputs.id`를 재사용하는 가시적인 증상은 배포 대시보드에 나타납니다. 아래 두 개의 하위 섹션이 이를 다룹니다.
|
||||
|
||||
### 시작 페이로드 마이그레이션
|
||||
|
||||
현재 `inputs`에 `id`를 포함하여 배포된 흐름을 시작하는 경우:
|
||||
|
||||
```bash
|
||||
# 더 이상 지원되지 않음
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
-d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \
|
||||
https://your-crew-url.crewai.com/kickoff
|
||||
```
|
||||
|
||||
UUID를 최상위 `restoreFromStateId` 필드로 이동하십시오:
|
||||
|
||||
```bash
|
||||
# 지원됨
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_CREW_TOKEN" \
|
||||
-d '{
|
||||
"inputs": {"topic": "AI Agent Frameworks"},
|
||||
"restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv"
|
||||
}' \
|
||||
https://your-crew-url.crewai.com/kickoff
|
||||
```
|
||||
|
||||
`restoreFromStateId`는 시작 페이로드에서 `inputs` 옆에 위치하며, 내부에 있지 않습니다.
|
||||
`inputs` 객체는 이제 흐름이 실제로 소비하는 값만 포함합니다.
|
||||
|
||||
### `inputs.id`가 재사용될 때 발생하는 일
|
||||
|
||||
AMP가 기존 실행과 `inputs.id`가 일치하는 흐름의 시작을 수신하면,
|
||||
새로운 기록을 생성하는 대신 기존 기록으로 해결됩니다. 배포 대시보드에서 다음을 확인할 수 있습니다:
|
||||
|
||||
- **실행 상태** — 새로운 실행의 상태가 이전 실행의 상태를 덮어씁니다. 완료된 실행은
|
||||
다시 `실행 중`으로 전환되거나, `완료`된 실행은 새로운 시작이 실패할 경우 `오류`로 전환될 수 있습니다 — 어쨌든 대시보드는 더 이상
|
||||
원래 실행을 반영하지 않습니다.
|
||||
- **추적** — OTel 추적이 시작 간에 쌓이기 때문에 동일한 실행 id를 공유합니다; 이전 실행의 추적은
|
||||
새로운 실행의 추적과 교체되거나 혼합됩니다. 단계별 재생은 더 이상 단일 실행에 해당하지 않습니다.
|
||||
- **실행 목록** — 별도의 행으로 나타나야 할 시작이 단일 항목으로 축소되어 이력을 숨깁니다.
|
||||
|
||||
`restoreFromStateId`로 마이그레이션하면 모든 시작이 자체 실행으로 유지됩니다 — 각자의 상태, 추적 및 목록의 행을 가지며 — 여전히 이전 실행에서 상태를 하이드레이트합니다.
|
||||
|
||||
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
|
||||
흐름이 어떤 모드가 필요한지 확실하지 않거나 마이그레이션 중 문제가 발생하면 지원 팀에 문의하십시오.
|
||||
</Card>
|
||||
815
docs/edge/ko/guides/flows/mastering-flow-state.mdx
Normal file
815
docs/edge/ko/guides/flows/mastering-flow-state.mdx
Normal file
@@ -0,0 +1,815 @@
|
||||
---
|
||||
title: 플로우 상태 관리 마스터하기
|
||||
description: 견고한 AI 애플리케이션 구축을 위한 CrewAI 플로우에서 상태를 관리, 유지 및 활용하는 종합 가이드입니다.
|
||||
icon: diagram-project
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## 플로우에서 State의 힘 이해하기
|
||||
|
||||
State 관리는 모든 고급 AI 워크플로우의 중추입니다. CrewAI Flows에서 state 시스템은 컨텍스트를 유지하고, 단계 간 데이터를 공유하며, 복잡한 애플리케이션 로직을 구축할 수 있도록 해줍니다. State 관리에 능숙해지는 것은 신뢰할 수 있고, 유지보수가 용이하며, 강력한 AI 애플리케이션을 만들기 위해 필수적입니다.
|
||||
|
||||
이 가이드는 CrewAI Flows에서 state를 관리하는 데 꼭 알아야 할 기본 개념부터 고급 기법까지, 실용적인 코드 예제와 함께 단계별로 안내합니다.
|
||||
|
||||
### 상태 관리가 중요한 이유
|
||||
|
||||
효과적인 상태 관리는 다음을 가능하게 합니다:
|
||||
|
||||
1. **실행 단계 간의 컨텍스트 유지** - 워크플로의 다양한 단계 간에 정보를 원활하게 전달할 수 있습니다.
|
||||
2. **복잡한 조건부 논리 구성** - 누적된 데이터를 기반으로 의사 결정을 내릴 수 있습니다.
|
||||
3. **지속적인 애플리케이션 생성** - 워크플로 진행 상황을 저장하고 복원할 수 있습니다.
|
||||
4. **에러를 우아하게 처리** - 더 견고한 애플리케이션을 위한 복구 패턴을 구현할 수 있습니다.
|
||||
5. **애플리케이션 확장** - 적절한 데이터 조직을 통해 복잡한 워크플로를 지원할 수 있습니다.
|
||||
6. **대화형 애플리케이션 활성화** - 컨텍스트 기반 AI 상호작용을 위해 대화 내역을 저장하고 접근할 수 있습니다.
|
||||
|
||||
멀티턴 채팅(`kickoff` per user line, `ChatState`, 의도 라우팅, 지연 트레이싱, `ChatSession`)은 [대화형 Flow](/ko/guides/flows/conversational-flows)를 참고하세요.
|
||||
|
||||
이러한 기능을 효과적으로 활용하는 방법을 살펴보겠습니다.
|
||||
|
||||
## 상태 관리 기본 사항
|
||||
|
||||
### Flow 상태 라이프사이클
|
||||
|
||||
CrewAI Flow에서 상태는 예측 가능한 라이프사이클을 따릅니다:
|
||||
|
||||
1. **초기화** - flow가 생성될 때, 상태는 초기화됩니다(빈 딕셔너리 또는 Pydantic 모델 인스턴스로)
|
||||
2. **수정** - flow 메서드는 실행되는 동안 상태에 접근하고 이를 수정합니다
|
||||
3. **전달** - 상태는 flow 메서드들 사이에 자동으로 전달됩니다
|
||||
4. **영속화** (선택 사항) - 상태는 스토리지에 저장될 수 있고 나중에 다시 불러올 수 있습니다
|
||||
5. **완료** - 최종 상태는 모든 실행된 메서드의 누적 변경 사항을 반영합니다
|
||||
|
||||
이 라이프사이클을 이해하는 것은 효과적인 flow를 설계하는 데 매우 중요합니다.
|
||||
|
||||
### 상태 관리의 두 가지 접근 방식
|
||||
|
||||
CrewAI에서는 흐름에서 상태를 관리하는 두 가지 방법을 제공합니다:
|
||||
|
||||
1. **비구조적 상태** - 유연성을 위해 딕셔너리와 유사한 객체 사용
|
||||
2. **구조적 상태** - 타입 안전성과 검증을 위해 Pydantic 모델 사용
|
||||
|
||||
각 접근 방식을 자세히 살펴보겠습니다.
|
||||
|
||||
## 비구조적 상태 관리
|
||||
|
||||
비구조적 상태는 사전(dictionary)과 유사한 방식을 사용하여, 단순한 애플리케이션에 유연성과 단순성을 제공합니다.
|
||||
|
||||
### 작동 방식
|
||||
|
||||
비구조화된 상태의 경우:
|
||||
- `self.state`를 통해 상태에 접근하며, 이는 딕셔너리처럼 동작합니다
|
||||
- 언제든지 키를 자유롭게 추가, 수정, 삭제할 수 있습니다
|
||||
- 모든 상태는 모든 flow 메서드에서 자동으로 사용할 수 있습니다
|
||||
|
||||
### 기본 예제
|
||||
|
||||
다음은 비구조적 상태 관리를 보여주는 간단한 예제입니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
|
||||
class UnstructuredStateFlow(Flow):
|
||||
@start()
|
||||
def initialize_data(self):
|
||||
print("Initializing flow data")
|
||||
# Add key-value pairs to state
|
||||
self.state["user_name"] = "Alex"
|
||||
self.state["preferences"] = {
|
||||
"theme": "dark",
|
||||
"language": "English"
|
||||
}
|
||||
self.state["items"] = []
|
||||
|
||||
# The flow state automatically gets a unique ID
|
||||
print(f"Flow ID: {self.state['id']}")
|
||||
|
||||
return "Initialized"
|
||||
|
||||
@listen(initialize_data)
|
||||
def process_data(self, previous_result):
|
||||
print(f"Previous step returned: {previous_result}")
|
||||
|
||||
# Access and modify state
|
||||
user = self.state["user_name"]
|
||||
print(f"Processing data for {user}")
|
||||
|
||||
# Add items to a list in state
|
||||
self.state["items"].append("item1")
|
||||
self.state["items"].append("item2")
|
||||
|
||||
# Add a new key-value pair
|
||||
self.state["processed"] = True
|
||||
|
||||
return "Processed"
|
||||
|
||||
@listen(process_data)
|
||||
def generate_summary(self, previous_result):
|
||||
# Access multiple state values
|
||||
user = self.state["user_name"]
|
||||
theme = self.state["preferences"]["theme"]
|
||||
items = self.state["items"]
|
||||
processed = self.state.get("processed", False)
|
||||
|
||||
summary = f"User {user} has {len(items)} items with {theme} theme. "
|
||||
summary += "Data is processed." if processed else "Data is not processed."
|
||||
|
||||
return summary
|
||||
|
||||
# Run the flow
|
||||
flow = UnstructuredStateFlow()
|
||||
result = flow.kickoff()
|
||||
print(f"Final result: {result}")
|
||||
print(f"Final state: {flow.state}")
|
||||
```
|
||||
|
||||
### 비구조적 상태를 사용할 때
|
||||
|
||||
비구조적 상태는 다음과 같은 경우에 이상적입니다:
|
||||
- 빠른 프로토타이핑 및 간단한 플로우
|
||||
- 동적으로 변화하는 상태 요구
|
||||
- 구조가 사전에 알려지지 않을 수 있는 경우
|
||||
- 간단한 상태 요구가 있는 플로우
|
||||
|
||||
비구조적 상태는 유연하지만, 타입 검사 및 스키마 검증이 없기 때문에 복잡한 애플리케이션에서 오류가 발생할 수 있습니다.
|
||||
|
||||
## 구조화된 상태 관리
|
||||
|
||||
구조화된 상태는 Pydantic 모델을 사용하여 flow의 상태에 대한 스키마를 정의함으로써 타입 안전성, 검증, 그리고 더 나은 개발자 경험을 제공합니다.
|
||||
|
||||
### 작동 방식
|
||||
|
||||
구조화된 상태에서는:
|
||||
- 상태 구조를 나타내는 Pydantic 모델을 정의합니다.
|
||||
- 이 모델 타입을 유형 매개변수로 Flow 클래스에 전달합니다.
|
||||
- `self.state`를 통해 상태에 접근할 수 있으며, 이는 Pydantic 모델 인스턴스처럼 동작합니다.
|
||||
- 모든 필드는 정의된 타입에 따라 검증됩니다.
|
||||
- IDE 자동 완성 및 타입 체크 지원을 받을 수 있습니다.
|
||||
|
||||
### 기본 예제
|
||||
|
||||
구조화된 상태 관리를 구현하는 방법은 다음과 같습니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from pydantic import BaseModel, Field
|
||||
from typing import List, Dict, Optional
|
||||
|
||||
# Define your state model
|
||||
class UserPreferences(BaseModel):
|
||||
theme: str = "light"
|
||||
language: str = "English"
|
||||
|
||||
class AppState(BaseModel):
|
||||
user_name: str = ""
|
||||
preferences: UserPreferences = UserPreferences()
|
||||
items: List[str] = []
|
||||
processed: bool = False
|
||||
completion_percentage: float = 0.0
|
||||
|
||||
# Create a flow with typed state
|
||||
class StructuredStateFlow(Flow[AppState]):
|
||||
@start()
|
||||
def initialize_data(self):
|
||||
print("Initializing flow data")
|
||||
# Set state values (type-checked)
|
||||
self.state.user_name = "Taylor"
|
||||
self.state.preferences.theme = "dark"
|
||||
|
||||
# The ID field is automatically available
|
||||
print(f"Flow ID: {self.state.id}")
|
||||
|
||||
return "Initialized"
|
||||
|
||||
@listen(initialize_data)
|
||||
def process_data(self, previous_result):
|
||||
print(f"Processing data for {self.state.user_name}")
|
||||
|
||||
# Modify state (with type checking)
|
||||
self.state.items.append("item1")
|
||||
self.state.items.append("item2")
|
||||
self.state.processed = True
|
||||
self.state.completion_percentage = 50.0
|
||||
|
||||
return "Processed"
|
||||
|
||||
@listen(process_data)
|
||||
def generate_summary(self, previous_result):
|
||||
# Access state (with autocompletion)
|
||||
summary = f"User {self.state.user_name} has {len(self.state.items)} items "
|
||||
summary += f"with {self.state.preferences.theme} theme. "
|
||||
summary += "Data is processed." if self.state.processed else "Data is not processed."
|
||||
summary += f" Completion: {self.state.completion_percentage}%"
|
||||
|
||||
return summary
|
||||
|
||||
# Run the flow
|
||||
flow = StructuredStateFlow()
|
||||
result = flow.kickoff()
|
||||
print(f"Final result: {result}")
|
||||
print(f"Final state: {flow.state}")
|
||||
```
|
||||
|
||||
### 구조화된 상태의 이점
|
||||
|
||||
구조화된 상태를 사용하면 여러 가지 장점이 있습니다:
|
||||
|
||||
1. **타입 안정성** - 개발 단계에서 타입 오류를 잡을 수 있습니다
|
||||
2. **자체 문서화** - 상태 모델이 어떤 데이터가 사용 가능한지 명확히 문서화합니다
|
||||
3. **검증** - 데이터 타입과 제약 조건을 자동으로 검증합니다
|
||||
4. **IDE 지원** - 자동 완성과 인라인 문서화를 받을 수 있습니다
|
||||
5. **기본값** - 누락된 데이터에 대한 대체값을 쉽게 정의할 수 있습니다
|
||||
|
||||
### 구조화된 상태를 사용할 때
|
||||
|
||||
구조화된 상태는 다음과 같은 경우에 권장됩니다:
|
||||
- 명확하게 정의된 데이터 스키마를 가진 복잡한 플로우
|
||||
- 여러 개발자가 동일한 코드를 작업하는 팀 프로젝트
|
||||
- 데이터 검증이 중요한 애플리케이션
|
||||
- 특정 데이터 타입 및 제약 조건을 강제로 적용해야 하는 플로우
|
||||
|
||||
## 자동 상태 ID
|
||||
|
||||
비구조화 상태와 구조화 상태 모두 상태 인스턴스를 추적하고 관리하는 데 도움이 되는 고유한 식별자(UUID)를 자동으로 부여받습니다.
|
||||
|
||||
### 작동 방식
|
||||
|
||||
- 비구조화 state의 경우, ID는 `self.state["id"]`로 접근할 수 있습니다.
|
||||
- 구조화 state의 경우, ID는 `self.state.id`로 접근할 수 있습니다.
|
||||
- 이 ID는 flow가 생성될 때 자동으로 생성됩니다.
|
||||
- ID는 flow의 생명주기 동안 동일하게 유지됩니다.
|
||||
- ID는 추적, 로깅, 저장된 state의 조회에 사용할 수 있습니다.
|
||||
|
||||
이 UUID는 persistence를 구현하거나 여러 flow 실행을 추적할 때 특히 유용합니다.
|
||||
|
||||
## 동적 상태 업데이트
|
||||
|
||||
구조화된 상태를 사용하든 비구조화된 상태를 사용하든, flow의 실행 중 언제든지 상태를 동적으로 업데이트할 수 있습니다.
|
||||
|
||||
### 단계 간 데이터 전달
|
||||
|
||||
Flow 메서드는 값을 반환할 수 있으며, 이러한 반환값은 리스닝 메서드의 인자로 전달됩니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
|
||||
class DataPassingFlow(Flow):
|
||||
@start()
|
||||
def generate_data(self):
|
||||
# This return value will be passed to listening methods
|
||||
return "Generated data"
|
||||
|
||||
@listen(generate_data)
|
||||
def process_data(self, data_from_previous_step):
|
||||
print(f"Received: {data_from_previous_step}")
|
||||
# You can modify the data and pass it along
|
||||
processed_data = f"{data_from_previous_step} - processed"
|
||||
# Also update state
|
||||
self.state["last_processed"] = processed_data
|
||||
return processed_data
|
||||
|
||||
@listen(process_data)
|
||||
def finalize_data(self, processed_data):
|
||||
print(f"Received processed data: {processed_data}")
|
||||
# Access both the passed data and state
|
||||
last_processed = self.state.get("last_processed", "")
|
||||
return f"Final: {processed_data} (from state: {last_processed})"
|
||||
```
|
||||
|
||||
이 패턴을 사용하면 직접적인 데이터 전달과 state 업데이트를 결합하여 최대한 유연하게 작업할 수 있습니다.
|
||||
|
||||
## 플로우 상태 지속
|
||||
|
||||
CrewAI의 가장 강력한 기능 중 하나는 실행 간에 플로우 상태를 지속할 수 있다는 점입니다. 이를 통해 중단, 재개, 심지어 실패 후에도 복구할 수 있는 워크플로우를 구현할 수 있습니다.
|
||||
|
||||
### @persist() 데코레이터
|
||||
|
||||
`@persist()` 데코레이터는 상태 지속을 자동화하여 flow의 상태를 실행의 주요 지점마다 저장합니다.
|
||||
|
||||
#### 클래스 수준 지속성
|
||||
|
||||
클래스 수준에서 `@persist()`를 적용하면 모든 메서드 실행 후 상태가 저장됩니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from crewai.flow.persistence import persist
|
||||
from pydantic import BaseModel
|
||||
|
||||
class CounterState(BaseModel):
|
||||
value: int = 0
|
||||
|
||||
@persist() # Apply to the entire flow class
|
||||
class PersistentCounterFlow(Flow[CounterState]):
|
||||
@start()
|
||||
def increment(self):
|
||||
self.state.value += 1
|
||||
print(f"Incremented to {self.state.value}")
|
||||
return self.state.value
|
||||
|
||||
@listen(increment)
|
||||
def double(self, value):
|
||||
self.state.value = value * 2
|
||||
print(f"Doubled to {self.state.value}")
|
||||
return self.state.value
|
||||
|
||||
# First run
|
||||
flow1 = PersistentCounterFlow()
|
||||
result1 = flow1.kickoff()
|
||||
print(f"First run result: {result1}")
|
||||
|
||||
# Second run - state is automatically loaded
|
||||
flow2 = PersistentCounterFlow()
|
||||
result2 = flow2.kickoff()
|
||||
print(f"Second run result: {result2}") # Will be higher due to persisted state
|
||||
```
|
||||
|
||||
#### 메서드 수준 지속성
|
||||
|
||||
더 세밀한 제어를 위해 `@persist()`를 특정 메서드에 적용할 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from crewai.flow.persistence import persist
|
||||
|
||||
class SelectivePersistFlow(Flow):
|
||||
@start()
|
||||
def first_step(self):
|
||||
self.state["count"] = 1
|
||||
return "First step"
|
||||
|
||||
@persist() # Only persist after this method
|
||||
@listen(first_step)
|
||||
def important_step(self, prev_result):
|
||||
self.state["count"] += 1
|
||||
self.state["important_data"] = "This will be persisted"
|
||||
return "Important step completed"
|
||||
|
||||
@listen(important_step)
|
||||
def final_step(self, prev_result):
|
||||
self.state["count"] += 1
|
||||
return f"Complete with count {self.state['count']}"
|
||||
```
|
||||
|
||||
#### 영속 상태 포크하기
|
||||
|
||||
`@persist`는 `kickoff` / `kickoff_async`에서 두 가지 별개의 하이드레이션 모드를 지원합니다. 동일한 계보를 계속하려면 **재개**(`inputs["id"]`)를 사용하고, 스냅샷에서 시작하는 새 계보를 시작하려면 **포크**(`restore_from_state_id`)를 사용하세요:
|
||||
|
||||
| | kickoff 후 `state.id` | `@persist` 기록 위치 |
|
||||
|---|---|---|
|
||||
| `inputs["id"]` (재개) | 제공된 id | 제공된 id (기록 확장) |
|
||||
| `restore_from_state_id` (포크) | 새 id, 또는 고정 시 `inputs["id"]` | 새 id (원본 보존) |
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start
|
||||
from crewai.flow.persistence import persist
|
||||
from pydantic import BaseModel
|
||||
|
||||
class CounterState(BaseModel):
|
||||
id: str = ""
|
||||
counter: int = 0
|
||||
|
||||
@persist
|
||||
class CounterFlow(Flow[CounterState]):
|
||||
@start()
|
||||
def step(self):
|
||||
self.state.counter += 1
|
||||
|
||||
# 실행 1: 새 상태, counter 0 -> 1
|
||||
flow_1 = CounterFlow()
|
||||
flow_1.kickoff()
|
||||
|
||||
# 포크: flow_1의 최신 스냅샷에서 하이드레이트, 단 새 state.id에 기록
|
||||
flow_2 = CounterFlow()
|
||||
flow_2.kickoff(restore_from_state_id=flow_1.state.id)
|
||||
# flow_2는 counter=1(하이드레이트)로 시작하고, step()이 2로 증가시킵니다.
|
||||
# flow_1의 flow_uuid 기록은 변경되지 않습니다.
|
||||
```
|
||||
|
||||
동작 노트:
|
||||
|
||||
- `restore_from_state_id`가 영속에서 발견되지 않음 → kickoff는 조용히 기본 동작으로 폴백됩니다 (기존 `inputs["id"]`의 미발견 동작 미러링). 예외는 발생하지 않습니다.
|
||||
- `restore_from_state_id`를 `from_checkpoint`와 결합하면 `ValueError`가 발생합니다 — 서로 다른 상태 시스템(`@persist` 대 Checkpointing)을 대상으로 하므로 결합할 수 없습니다.
|
||||
- `restore_from_state_id=None`(기본값)은 매개변수 없는 kickoff와 바이트 단위로 동일합니다.
|
||||
- 포크 중 `inputs["id"]`를 고정하면 새 실행이 다른 플로우와 영속 키를 공유함을 의미합니다 — 일반적으로 `restore_from_state_id`만 사용하는 것이 좋습니다.
|
||||
|
||||
## 고급 상태 패턴
|
||||
|
||||
### 상태 기반 조건부 로직
|
||||
|
||||
state를 사용하여 flow에서 복잡한 조건부 로직을 구현할 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, router, start
|
||||
from pydantic import BaseModel
|
||||
|
||||
class PaymentState(BaseModel):
|
||||
amount: float = 0.0
|
||||
is_approved: bool = False
|
||||
retry_count: int = 0
|
||||
|
||||
class PaymentFlow(Flow[PaymentState]):
|
||||
@start()
|
||||
def process_payment(self):
|
||||
# Simulate payment processing
|
||||
self.state.amount = 100.0
|
||||
self.state.is_approved = self.state.amount < 1000
|
||||
return "Payment processed"
|
||||
|
||||
@router(process_payment)
|
||||
def check_approval(self, previous_result):
|
||||
if self.state.is_approved:
|
||||
return "approved"
|
||||
elif self.state.retry_count < 3:
|
||||
return "retry"
|
||||
else:
|
||||
return "rejected"
|
||||
|
||||
@listen("approved")
|
||||
def handle_approval(self):
|
||||
return f"Payment of ${self.state.amount} approved!"
|
||||
|
||||
@listen("retry")
|
||||
def handle_retry(self):
|
||||
self.state.retry_count += 1
|
||||
print(f"Retrying payment (attempt {self.state.retry_count})...")
|
||||
# Could implement retry logic here
|
||||
return "Retry initiated"
|
||||
|
||||
@listen("rejected")
|
||||
def handle_rejection(self):
|
||||
return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries."
|
||||
```
|
||||
|
||||
### 복잡한 상태 변환 처리
|
||||
|
||||
복잡한 상태 변환의 경우, 전용 메서드를 만들어 처리할 수 있습니다.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from pydantic import BaseModel
|
||||
from typing import List, Dict
|
||||
|
||||
class UserData(BaseModel):
|
||||
name: str
|
||||
active: bool = True
|
||||
login_count: int = 0
|
||||
|
||||
class ComplexState(BaseModel):
|
||||
users: Dict[str, UserData] = {}
|
||||
active_user_count: int = 0
|
||||
|
||||
class TransformationFlow(Flow[ComplexState]):
|
||||
@start()
|
||||
def initialize(self):
|
||||
# Add some users
|
||||
self.add_user("alice", "Alice")
|
||||
self.add_user("bob", "Bob")
|
||||
self.add_user("charlie", "Charlie")
|
||||
return "Initialized"
|
||||
|
||||
@listen(initialize)
|
||||
def process_users(self, _):
|
||||
# Increment login counts
|
||||
for user_id in self.state.users:
|
||||
self.increment_login(user_id)
|
||||
|
||||
# Deactivate one user
|
||||
self.deactivate_user("bob")
|
||||
|
||||
# Update active count
|
||||
self.update_active_count()
|
||||
|
||||
return f"Processed {len(self.state.users)} users"
|
||||
|
||||
# Helper methods for state transformations
|
||||
def add_user(self, user_id: str, name: str):
|
||||
self.state.users[user_id] = UserData(name=name)
|
||||
self.update_active_count()
|
||||
|
||||
def increment_login(self, user_id: str):
|
||||
if user_id in self.state.users:
|
||||
self.state.users[user_id].login_count += 1
|
||||
|
||||
def deactivate_user(self, user_id: str):
|
||||
if user_id in self.state.users:
|
||||
self.state.users[user_id].active = False
|
||||
self.update_active_count()
|
||||
|
||||
def update_active_count(self):
|
||||
self.state.active_user_count = sum(
|
||||
1 for user in self.state.users.values() if user.active
|
||||
)
|
||||
```
|
||||
|
||||
이와 같은 헬퍼 메서드 생성 패턴은 flow 메서드를 깔끔하게 유지하면서 복잡한 상태 조작을 가능하게 해줍니다.
|
||||
|
||||
## Crews로 상태 관리하기
|
||||
|
||||
CrewAI에서 가장 강력한 패턴 중 하나는 flow 상태 관리와 crew 실행을 결합하는 것입니다.
|
||||
|
||||
### 크루에 상태 전달하기
|
||||
|
||||
플로우 상태를 사용하여 크루에 매개변수를 전달할 수 있습니다:
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from pydantic import BaseModel
|
||||
|
||||
class ResearchState(BaseModel):
|
||||
topic: str = ""
|
||||
depth: str = "medium"
|
||||
results: str = ""
|
||||
|
||||
class ResearchFlow(Flow[ResearchState]):
|
||||
@start()
|
||||
def get_parameters(self):
|
||||
# In a real app, this might come from user input
|
||||
self.state.topic = "Artificial Intelligence Ethics"
|
||||
self.state.depth = "deep"
|
||||
return "Parameters set"
|
||||
|
||||
@listen(get_parameters)
|
||||
def execute_research(self, _):
|
||||
# Create agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal=f"Research {self.state.topic} in {self.state.depth} detail",
|
||||
backstory="You are an expert researcher with a talent for finding accurate information."
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Transform research into clear, engaging content",
|
||||
backstory="You excel at communicating complex ideas clearly and concisely."
|
||||
)
|
||||
|
||||
# Create tasks
|
||||
research_task = Task(
|
||||
description=f"Research {self.state.topic} with {self.state.depth} analysis",
|
||||
expected_output="Comprehensive research notes in markdown format",
|
||||
agent=researcher
|
||||
)
|
||||
|
||||
writing_task = Task(
|
||||
description=f"Create a summary on {self.state.topic} based on the research",
|
||||
expected_output="Well-written article in markdown format",
|
||||
agent=writer,
|
||||
context=[research_task]
|
||||
)
|
||||
|
||||
# Create and run crew
|
||||
research_crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run crew and store result in state
|
||||
result = research_crew.kickoff()
|
||||
self.state.results = result.raw
|
||||
|
||||
return "Research completed"
|
||||
|
||||
@listen(execute_research)
|
||||
def summarize_results(self, _):
|
||||
# Access the stored results
|
||||
result_length = len(self.state.results)
|
||||
return f"Research on {self.state.topic} completed with {result_length} characters of results."
|
||||
```
|
||||
|
||||
### State에서 Crew 출력 처리하기
|
||||
|
||||
Crew가 완료되면, 해당 출력을 처리하여 flow state에 저장할 수 있습니다:
|
||||
|
||||
```python
|
||||
@listen(execute_crew)
|
||||
def process_crew_results(self, _):
|
||||
# Parse the raw results (assuming JSON output)
|
||||
import json
|
||||
try:
|
||||
results_dict = json.loads(self.state.raw_results)
|
||||
self.state.processed_results = {
|
||||
"title": results_dict.get("title", ""),
|
||||
"main_points": results_dict.get("main_points", []),
|
||||
"conclusion": results_dict.get("conclusion", "")
|
||||
}
|
||||
return "Results processed successfully"
|
||||
except json.JSONDecodeError:
|
||||
self.state.error = "Failed to parse crew results as JSON"
|
||||
return "Error processing results"
|
||||
```
|
||||
|
||||
## 상태 관리 모범 사례
|
||||
|
||||
### 1. 상태를 집중적으로 유지하세요
|
||||
|
||||
상태를 설계할 때 꼭 필요한 내용만 포함하도록 하세요:
|
||||
|
||||
```python
|
||||
# Too broad
|
||||
class BloatedState(BaseModel):
|
||||
user_data: Dict = {}
|
||||
system_settings: Dict = {}
|
||||
temporary_calculations: List = []
|
||||
debug_info: Dict = {}
|
||||
# ...many more fields
|
||||
|
||||
# Better: Focused state
|
||||
class FocusedState(BaseModel):
|
||||
user_id: str
|
||||
preferences: Dict[str, str]
|
||||
completion_status: Dict[str, bool]
|
||||
```
|
||||
|
||||
### 2. 복잡한 플로우를 위한 구조화된 상태 사용
|
||||
|
||||
플로우의 복잡도가 증가할수록 구조화된 상태의 가치는 점점 커집니다:
|
||||
|
||||
```python
|
||||
# Simple flow can use unstructured state
|
||||
class SimpleGreetingFlow(Flow):
|
||||
@start()
|
||||
def greet(self):
|
||||
self.state["name"] = "World"
|
||||
return f"Hello, {self.state['name']}!"
|
||||
|
||||
# Complex flow benefits from structured state
|
||||
class UserRegistrationState(BaseModel):
|
||||
username: str
|
||||
email: str
|
||||
verification_status: bool = False
|
||||
registration_date: datetime = Field(default_factory=datetime.now)
|
||||
last_login: Optional[datetime] = None
|
||||
|
||||
class RegistrationFlow(Flow[UserRegistrationState]):
|
||||
# Methods with strongly-typed state access
|
||||
```
|
||||
|
||||
### 3. 문서 상태 전이
|
||||
|
||||
복잡한 흐름의 경우, 실행 중에 상태가 어떻게 변하는지 문서화하세요:
|
||||
|
||||
```python
|
||||
@start()
|
||||
def initialize_order(self):
|
||||
"""
|
||||
Initialize order state with empty values.
|
||||
|
||||
State before: {}
|
||||
State after: {order_id: str, items: [], status: 'new'}
|
||||
"""
|
||||
self.state.order_id = str(uuid.uuid4())
|
||||
self.state.items = []
|
||||
self.state.status = "new"
|
||||
return "Order initialized"
|
||||
```
|
||||
|
||||
### 4. 상태 오류를 정상적으로 처리하기
|
||||
|
||||
상태 접근에 대한 오류 처리를 구현하세요:
|
||||
|
||||
```python
|
||||
@listen(previous_step)
|
||||
def process_data(self, _):
|
||||
try:
|
||||
# Try to access a value that might not exist
|
||||
user_preference = self.state.preferences.get("theme", "default")
|
||||
except (AttributeError, KeyError):
|
||||
# Handle the error gracefully
|
||||
self.state.errors = self.state.get("errors", [])
|
||||
self.state.errors.append("Failed to access preferences")
|
||||
user_preference = "default"
|
||||
|
||||
return f"Used preference: {user_preference}"
|
||||
```
|
||||
|
||||
### 5. 상태를 사용하여 진행 상황 추적
|
||||
|
||||
긴 실행 흐름에서 진행 상황을 추적하기 위해 상태를 활용하세요:
|
||||
|
||||
```python
|
||||
class ProgressTrackingFlow(Flow):
|
||||
@start()
|
||||
def initialize(self):
|
||||
self.state["total_steps"] = 3
|
||||
self.state["current_step"] = 0
|
||||
self.state["progress"] = 0.0
|
||||
self.update_progress()
|
||||
return "Initialized"
|
||||
|
||||
def update_progress(self):
|
||||
"""Helper method to calculate and update progress"""
|
||||
if self.state.get("total_steps", 0) > 0:
|
||||
self.state["progress"] = (self.state.get("current_step", 0) /
|
||||
self.state["total_steps"]) * 100
|
||||
print(f"Progress: {self.state['progress']:.1f}%")
|
||||
|
||||
@listen(initialize)
|
||||
def step_one(self, _):
|
||||
# Do work...
|
||||
self.state["current_step"] = 1
|
||||
self.update_progress()
|
||||
return "Step 1 complete"
|
||||
|
||||
# Additional steps...
|
||||
```
|
||||
|
||||
### 6. 가능한 경우 불변(Immutable) 연산 사용하기
|
||||
|
||||
특히 구조화된 상태에서는 명확성을 위해 불변 연산을 선호하세요:
|
||||
|
||||
```python
|
||||
# 리스트를 즉시 수정하는 대신:
|
||||
self.state.items.append(new_item) # 변경 가능한 연산
|
||||
|
||||
# 새로운 상태를 생성하는 것을 고려하세요:
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
|
||||
class ItemState(BaseModel):
|
||||
items: List[str] = []
|
||||
|
||||
class ImmutableFlow(Flow[ItemState]):
|
||||
@start()
|
||||
def add_item(self):
|
||||
# 추가된 항목과 함께 새로운 리스트 생성
|
||||
self.state.items = [*self.state.items, "new item"]
|
||||
return "Item added"
|
||||
```
|
||||
|
||||
## 플로우 상태 디버깅
|
||||
|
||||
### 상태 변경 로깅
|
||||
|
||||
개발할 때 상태 변화를 추적하기 위해 로깅을 추가하세요:
|
||||
|
||||
```python
|
||||
import logging
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
class LoggingFlow(Flow):
|
||||
def log_state(self, step_name):
|
||||
logging.info(f"State after {step_name}: {self.state}")
|
||||
|
||||
@start()
|
||||
def initialize(self):
|
||||
self.state["counter"] = 0
|
||||
self.log_state("initialize")
|
||||
return "Initialized"
|
||||
|
||||
@listen(initialize)
|
||||
def increment(self, _):
|
||||
self.state["counter"] += 1
|
||||
self.log_state("increment")
|
||||
return f"Incremented to {self.state['counter']}"
|
||||
```
|
||||
|
||||
### 상태 시각화
|
||||
|
||||
디버깅을 위해 상태를 시각화하는 메서드를 추가할 수 있습니다:
|
||||
|
||||
```python
|
||||
def visualize_state(self):
|
||||
"""Create a simple visualization of the current state"""
|
||||
import json
|
||||
from rich.console import Console
|
||||
from rich.panel import Panel
|
||||
|
||||
console = Console()
|
||||
|
||||
if hasattr(self.state, "model_dump"):
|
||||
# Pydantic v2
|
||||
state_dict = self.state.model_dump()
|
||||
elif hasattr(self.state, "dict"):
|
||||
# Pydantic v1
|
||||
state_dict = self.state.dict()
|
||||
else:
|
||||
# Unstructured state
|
||||
state_dict = dict(self.state)
|
||||
|
||||
# Remove id for cleaner output
|
||||
if "id" in state_dict:
|
||||
state_dict.pop("id")
|
||||
|
||||
state_json = json.dumps(state_dict, indent=2, default=str)
|
||||
console.print(Panel(state_json, title="Current Flow State"))
|
||||
```
|
||||
|
||||
## 결론
|
||||
|
||||
CrewAI Flows에서 상태 관리를 마스터하면 컨텍스트를 유지하고, 복잡한 결정을 내리며, 일관된 결과를 제공하는 정교하고 견고한 AI 애플리케이션을 구축할 수 있는 힘을 얻게 됩니다.
|
||||
|
||||
비구조화 상태든 구조화 상태든 적절한 상태 관리 방식을 구현하면 유지 관리가 용이하고, 확장 가능하며, 실제 문제를 효과적으로 해결할 수 있는 플로우를 만들 수 있습니다.
|
||||
|
||||
더 복잡한 플로우를 개발할수록 좋은 상태 관리는 유연성과 구조성 사이의 올바른 균형을 찾는 것임을 기억하세요. 이를 통해 코드가 강력하면서도 이해하기 쉬워집니다.
|
||||
|
||||
<Check>
|
||||
이제 CrewAI Flows에서 상태 관리의 개념과 실습을 마스터하셨습니다! 이 지식을 통해 컨텍스트를 효과적으로 유지하고, 단계 간 데이터를 공유하며, 정교한 애플리케이션 로직을 구현하는 견고한 AI 워크플로우를 만들 수 있습니다.
|
||||
</Check>
|
||||
|
||||
## 다음 단계
|
||||
|
||||
- flow에서 구조화된 state와 비구조화된 state를 모두 실험해 보세요
|
||||
- 장기 실행 워크플로를 위해 state 영속성을 구현해 보세요
|
||||
- [첫 crew 만들기](/ko/guides/crews/first-crew)를 탐색하여 crew와 flow가 어떻게 함께 작동하는지 확인해 보세요
|
||||
- 더 고급 기능을 원한다면 [Flow 참고 문서](/ko/concepts/flows)를 확인해 보세요
|
||||
Reference in New Issue
Block a user