diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml index ddd73e71b..8911e97bf 100644 --- a/docs/source/ko/_toctree.yml +++ b/docs/source/ko/_toctree.yml @@ -36,8 +36,8 @@ # title: (번역중) Build a web browser agent using vision models - local: examples/using_different_models title: 다양한 모델 사용하기 -# - local: examples/plan_customization -# title: "(번역중) Human-in-the-Loop: Customize agent plan interactively" + - local: examples/plan_customization + title: Human-in-the-Loop: 사용자와 상호작용하며 에이전트 계획 수정하기 - local: examples/async_agent title: 에이전트를 활용한 비동기 애플리케이션 - title: Reference diff --git a/docs/source/ko/examples/plan_customization.md b/docs/source/ko/examples/plan_customization.md new file mode 100644 index 000000000..7a7aa5a0b --- /dev/null +++ b/docs/source/ko/examples/plan_customization.md @@ -0,0 +1,118 @@ +# Human-in-the-Loop: 사용자와 상호작용하며 에이전트 계획 수정하기 [[humanintheloop-customize-agent-plan-interactively]] + +이 페이지에서는 smolagents 라이브러리의 고급 사용법을 소개합니다. 특히 사용자와의 상호작용을 통한 계획 생성, 계획 수정, 그리고 에이전트 워크플로에서의 메모리 보존을 위한 Human-in-the-Loop (HITL) 접근 방식을 중점적으로 설명합니다. +예제는 `examples/plan_customization/plan_customization.py`의 코드를 기반으로 합니다. + +## 개요 [[overview]] + +이 예제는 다음과 같은 Human-in-the-Loop 전략을 구현하는 방법을 안내합니다. + +- 단계 콜백(step callback)을 사용하여 계획 생성 후 에이전트 실행 중단하기 +- 사용자가 실행 전에 에이전트의 계획을 검토하고 수정할 수 있도록 지원 (Human-in-the-Loop) +- 에이전트의 메모리를 보존하면서 실행 재개하기 +- 사용자 피드백을 기반으로 계획을 동적으로 업데이트하여 사용자가 제어권을 유지하도록 지원 + +## 핵심 개념 [[key-concepts]] + +### 단계 콜백을 이용한 계획 중단 [[step-callbacks-for-plan-interruption]] + +에이전트가 계획을 생성한 후 일시 중지하도록 설정할 수 있습니다. 이는 PlanningStep에 단계 콜백을 등록하여 구현합니다. + +```python +agent = CodeAgent( + model=InferenceClientModel(), + tools=[DuckDuckGoSearchTool()], + planning_interval=5, # 5단계마다 계획 + step_callbacks={PlanningStep: interrupt_after_plan}, + max_steps=10, + verbosity_level=1 +) +``` + +### Human-in-the-Loop: 대화형 계획 검토 및 수정 [[humanintheloop-interactive-plan-review-and-modification]] + +에이전트가 계획을 생성하면, 콜백 함수가 해당 계획을 사용자에게 보여주고 다음 옵션 중 하나를 선택하도록 안내합니다. + +1. 계획 승인 +2. 계획 수정 +3. 실행 취소 + +예제 상호작용: + +``` +============================================================ +🤖 에이전트 계획 생성됨 +============================================================ +1. 최근 AI 발전 사항 검색 +2. 상위 결과 분석 +3. 가장 중요한 3가지 돌파구 요약 +4. 각 돌파구에 대한 소스 포함 +============================================================ + +옵션을 선택하세요. +1. 계획 승인 +2. 계획 수정 +3. 취소 +선택 (1-3): +``` + +이 Human-in-the-Loop 단계를 통해 사용자는 실행이 계속되기 전에 개입하여 계획을 검토하고 수정할 수 있으며, 이를 통해 에이전트의 행동이 사용자의 의도와 일치하도록 보장할 수 있습니다. + +사용자가 수정을 선택하면 계획을 직접 편집할 수 있으며, 업데이트된 계획은 이후 실행 단계에서 사용됩니다. + +### 메모리 보존 및 실행 재개 [[memory-preservation-and-resuming-execution]] + +`reset=False` 옵션으로 에이전트를 실행하면 이전의 모든 단계와 메모리가 보존됩니다. 이를 통해 중단 또는 계획 수정 후에도 실행을 이어서 진행할 수 있습니다. + +```python +# 첫 번째 실행 (중단될 수 있음) +agent.run(task, reset=True) + +# 보존된 메모리로 재개 +agent.run(task, reset=False) +``` + +### 에이전트 메모리 검사 [[inspecting-agent-memory]] + +에이전트의 메모리를 검사하여 지금까지 수행된 모든 단계를 확인할 수 있습니다. + +```python +print(f"현재 메모리에 {len(agent.memory.steps)}개의 단계가 포함되어 있습니다.") +for i, step in enumerate(agent.memory.steps): + step_type = type(step).__name__ + print(f" {i+1}. {step_type}") +``` + +## Human-in-the-Loop 워크플로우 예시 [[example-humanintheloop-workflow]] + +1. 에이전트가 복잡한 작업을 받아 실행을 시작합니다. +2. 계획 단계가 생성되고, 사용자 검토를 위해 실행이 일시 중지됩니다. +3. 사용자가 계획을 검토하고 필요에 따라 수정합니다 (Human-in-the-Loop). +4. 승인되거나 수정된 계획으로 실행을 재개합니다. +5. 모든 단계는 향후 실행을 위해 보존되어 투명성과 제어권을 보장합니다. + +## 오류 처리 [[error-handling]] + +예제는 다음에 대한 오류 처리를 포함합니다. +- 사용자 취소 +- 계획 수정 오류 +- 실행 재개 실패 + +## 요구사항 [[requirements]] + +- smolagents 라이브러리 +- DuckDuckGoSearchTool (smolagents에 포함) +- InferenceClientModel (🤗 Hugging Face API 토큰 필요) + +## 교육적 가치 [[educational-value]] + +이 예제는 다음을 시연합니다. +- 사용자 정의 에이전트 동작을 위한 단계 콜백 구현 방법 +- 다중 단계 에이전트의 메모리 관리 기법 +- 에이전트 시스템의 사용자 상호작용 패턴 +- 동적 에이전트 제어를 위한 계획 수정 기법 +- 대화형 에이전트 시스템의 오류 처리 방법 + +--- + +전체 코드는 [`examples/plan_customization`](https://github.com/huggingface/smolagents/tree/main/examples/plan_customization)에서 확인하세요.