euleragent 기초 튜토리얼 모음

이 디렉토리는 euleragent를 처음 사용하는 개발자를 위한 9개의 단계별 튜토리얼을 포함합니다. 각 튜토리얼은 독립적으로 읽을 수 있지만, 번호 순서대로 학습하면 가장 효과적입니다.

튜토리얼 목록

번호	파일	제목	핵심 학습 내용
01	01_getting_started.md	시작하기 — 워크스페이스 설정과 첫 번째 실행	`init`, `new`, `run`, `approve`, `logs` 기본 흐름 전체
02	02_plan_execute_mode.md	Plan 모드 vs Execute 모드	두 모드의 차이, 에이전틱 루프, `--max-loops`, `--artifact-name`
03	03_hitl_approval.md	HITL 승인 워크플로우	승인 레코드 구조, 수락·수정·거부, 위험 수준(risk level)
04	04_task_file_and_batch.md	태스크 파일, 변수 치환, 배치, 재개 실행	`--task-file`, `--var`, `--min-proposals`, `--resume-run`
05	05_chat_and_memory.md	대화 모드와 장기기억	`chat`, `--continue`, `--debug-memory`, `memory status/search/open`
06	06_dynamic_workflow.md	Dynamic 워크플로우	`--dynamic`, `workflow show/resume`, REST API
07	07_web_rag.md	웹 검색 + 로컬 지식베이스 (RAG)	`rag init/add/status/query`, `web.search` 보안 설정
08	08_mcp_provider_and_tools.md	MCP 프로바이더 설정과 도구 관리	MCP 서버 설정, `mcp sync/show`, SearchRouter, 카탈로그 스냅샷
09	09_scoped_llm_profile.md	스코프별 LLM 프로필과 외부 LLM 승인	`--llm-plan/--llm-final`, 폴백→승인→재실행 사이클, 일괄 승인

튜토리얼 학습 순서

권장 학습 경로는 다음과 같습니다. 각 튜토리얼은 이전 내용을 기반으로 확장됩니다.

01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09
시작하기  모드   승인   배치   메모리  다이나믹  RAG   MCP   LLM프로필

처음 euleragent를 설치한다면 반드시 01번부터 시작하세요. 워크스페이스 초기화와 에이전트 생성이 선행되어야 이후 튜토리얼이 원활하게 진행됩니다.

각 튜토리얼 설명 및 학습 성과

01. 시작하기 — 워크스페이스 설정과 첫 번째 실행

euleragent의 전체 기본 흐름을 한 번에 경험합니다. 설치부터 첫 번째 에이전트 실행, 승인 처리, 감사 로그 확인까지 end-to-end 실습을 진행합니다.

학습 성과: - euleragent 설치 및 워크스페이스 초기화 - 에이전트 생성 (euleragent new) - 첫 번째 태스크 실행 및 결과 확인 - 승인 대기 목록 확인 및 일괄 수락 - 감사 로그(audit log) 읽기

02. Plan 모드 vs Execute 모드

같은 태스크를 두 가지 모드로 실행하여 차이를 직접 비교합니다. 에이전틱 루프의 동작 방식과 --max-loops, --min-proposals, --artifact-name 옵션을 실습합니다.

학습 성과: - Plan 모드와 Execute 모드의 차이 이해 - 언제 어떤 모드를 써야 하는지 판단 기준 습득 - 에이전틱 루프(--max-loops) 제어 - 커스텀 아티팩트 파일명 지정

03. HITL 승인 워크플로우

사람이 에이전트의 행동을 검토하고 제어하는 HITL(Human-In-The-Loop) 승인 흐름을 완전히 이해합니다. 승인 레코드의 구조, 파라미터 수정, 거부 처리를 실습합니다.

학습 성과: - 승인 레코드 JSON 구조 이해 - 개별 승인 수락·수정·거부 - 위험 수준(low/medium/high)별 처리 방침 - 일괄 승인 필터링 (--tool, --run-id)

04. 태스크 파일, 변수 치환, 배치, 재개 실행

복잡한 리서치 태스크를 파일로 관리하고, 변수로 재사용 가능하게 만들며, 이전 실행을 이어받는 방법을 학습합니다.

학습 성과: - 마크다운 태스크 파일 작성 요령 - --var KEY=VALUE로 변수 치환 - --min-proposals N으로 배치 정보 수집 강제 - --resume-run으로 plan→execute 핸드오프

05. 대화 모드와 장기기억

대화형 채팅 모드를 익히고, 에이전트가 사용자 선호를 장기기억에 저장하여 세션 간에도 기억하는 방법을 실습합니다.

학습 성과: - euleragent chat으로 인터랙티브 대화 - 선호·금지·습관 학습 후 기억 확인 - --continue로 이전 세션 이어받기 - 메모리 상태 조회 및 수동 검색

06. Dynamic 워크플로우

LLM이 복잡한 태스크를 자동으로 여러 단계(phase)로 분해하고 순서대로 실행하는 --dynamic 플래그를 학습합니다.

학습 성과: - --dynamic이 내부적으로 하는 일 이해 - 워크플로우 상태 확인 (workflow show) - 단계별 실행 및 재개 (workflow resume) - REST API로 외부 시스템과 연동

07. 웹 검색 + 로컬 지식베이스 (RAG)

web.search 도구의 HITL 보안 게이트와 로컬 문서 기반 RAG(Retrieval-Augmented Generation)를 함께 사용하는 방법을 학습합니다.

학습 성과: - rag init/add/status/query 명령어 사용 - 로컬 문서를 지식베이스에 추가 - 웹 검색 보안 설정 (도메인 화이트리스트) - 웹 검색과 로컬 KB를 함께 사용하는 실전 시나리오

08. MCP 프로바이더 설정과 도구 관리

MCP(Model Context Protocol) 서버를 연결하여 다양한 외부 검색 소스(Tavily, Brave, 커스텀 API 등)를 web.search 단일 인터페이스로 통합 관리하는 방법을 학습합니다.

학습 성과: - MCP 프로토콜 개념과 euleragent에서의 역할 이해 - workspace.yaml에 MCP 서버 설정 및 연결 - mcp sync / mcp show로 카탈로그 관리 - source_enable 승인 흐름 처리 - 카탈로그 스냅샷과 fail-closed 보안 정책 이해 - 다중 MCP 서버의 신뢰 수준별 구성

09. 스코프별 LLM 프로필과 외부 LLM 승인

계획 단계와 결과물 생성 단계에 서로 다른 LLM을 사용하는 다중 프로필 설정과, 외부 LLM 사용 시 필요한 HITL 승인 워크플로우 전체 사이클을 학습합니다.

학습 성과: - llm_profiles 설정으로 다중 LLM 프로필 관리 - --llm-plan / --llm-final로 스코프별 프로필 선택 - 외부 프로필 폴백 → 승인 → 재실행 사이클 체험 - --edit-params로 승인 시 프로필 변경 - accept-all --tool llm.external_call 일괄 승인 - Dynamic 모드에서의 스코프 적용 범위 이해

사전 준비

튜토리얼을 시작하기 전에 아래 항목을 준비하세요.

필수 환경:

항목	버전 / 조건	확인 방법
Python	3.11 이상	`python --version`
pip	최신 권장	`pip --version`
euleragent	`pip install -e .`로 설치	`euleragent --version`
Ollama	실행 중 (또는 fake 모드)	`ollama list`

Ollama 없이 테스트하는 방법:

실제 LLM 없이 튜토리얼을 진행하려면 .euleragent/config/workspace.yaml에서 다음을 설정하세요:

default_llm_profile: fake

fake 프로바이더는 결정론적인 더미 응답을 반환하므로 네트워크 없이도 전체 흐름을 테스트할 수 있습니다.

설치 확인:

pip install -e .
euleragent --help
euleragent doctor

doctor 명령어가 모든 항목에 OK를 반환하면 준비가 완료된 것입니다.