01. euleragent 시작하기 — 워크스페이스 설정과 첫 번째 실행
학습 목표
이 튜토리얼을 마치면 다음을 할 수 있습니다:
- euleragent를 설치하고 상태를 확인한다
- 워크스페이스를 초기화하고 디렉토리 구조를 이해한다
- 에이전트를 생성하고
agent.yaml파일의 의미를 파악한다 - 첫 번째 태스크를 실행하고 결과를 읽는다
- 승인 목록을 확인하고 일괄 수락한다
- 감사 로그(audit log)를 통해 실행 내역을 추적한다
사전 준비
| 항목 | 버전 / 조건 |
|---|---|
| Python | 3.11 이상 |
| pip | 최신 권장 |
| euleragent | pip install -e .로 소스 설치 |
| Ollama | 실행 중 (또는 default_llm_profile: fake 사용) |
euleragent 소스 코드가 로컬에 있다고 가정합니다. 아직 클론하지 않았다면:
git clone https://github.com/your-org/euleragent.git
cd euleragent
단계별 실습
Step 0: (권장) venv로 파이썬 환경 분리하기
Python 프로젝트에서는 가상환경(venv)을 만들어 의존성(pip 패키지)과 실행 환경을 프로젝트별로 분리하는 것이 일반적입니다. 이렇게 하면 시스템 Python이나 다른 프로젝트의 패키지와 충돌하지 않고, “이 워크스페이스에서만” 필요한 라이브러리를 안전하게 설치할 수 있습니다.
euleragent도 동일하게, 워크스페이스(작업 디렉토리)에 .venv/를 만들고 그 환경을 활성화한 뒤 설치/실행하는 흐름을 표준으로 권장합니다.
예시(워크스페이스 디렉토리에서):
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
Step 1: euleragent 설치
프로젝트 루트 디렉토리에서 편집 가능(editable) 모드로 설치합니다. 이 방식을 사용하면 소스 코드를 수정한 후 재설치 없이 즉시 반영됩니다.
pip install -e .
설치가 완료되면 euleragent 명령어가 PATH에 등록됩니다:
euleragent --version
예상 출력:
euleragent 0.1.x
Step 2: 도움말 확인
--help 플래그로 사용 가능한 모든 명령어와 옵션을 확인합니다:
euleragent --help
예상 출력:
Usage: euleragent [OPTIONS] COMMAND [ARGS]...
euleragent — local-first CLI agent creation and execution framework.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
approve Manage approval queue (list, show, accept, reject)
chat Interactive chat with an agent
doctor Run environment health check
init Initialize a new workspace
logs Show audit log for a run
memory Manage long-term memory
new Scaffold a new agent from a template
rag Manage local knowledge base (RAG)
run Run an agent with a task
workflow Manage dynamic workflows
Step 3: 환경 상태 진단
doctor 명령어는 euleragent가 올바르게 작동하는지 진단합니다. 현재 디렉토리에 워크스페이스가 없어도 실행할 수 있습니다.
euleragent doctor
예상 출력:
euleragent doctor
[OK] Python 3.11.x
[OK] euleragent 0.1.x installed
[OK] Workspace: /home/user/my-project/.euleragent
[OK] Config: workspace.yaml found
[WARN] Ollama: not reachable at http://localhost:11434
Set default_llm_profile: fake in workspace.yaml for offline testing
[OK] Memory: SQLite enabled
[OK] Approvals directory: .euleragent/approvals/
팁: Ollama가 실행 중이지 않아도 튜토리얼을 진행할 수 있습니다.
workspace.yaml에서default_llm_profile: fake를 설정하면 LLM 없이 전체 흐름을 테스트할 수 있습니다.
Step 4: 워크스페이스 초기화
새 프로젝트 디렉토리를 만들고 워크스페이스를 초기화합니다.
mkdir ~/my-project && cd ~/my-project
euleragent init
예상 출력:
Workspace initialized at /home/user/my-project/.euleragent
Created: .euleragent/config/workspace.yaml
Created: .euleragent/config/company_brief.md
Created: .euleragent/agents/
Created: .euleragent/runs/
Created: .euleragent/approvals/
Created: .euleragent/projects/
Created: .euleragent/state/
생성된 디렉토리 구조를 확인합니다:
ls -la .euleragent/
.euleragent/
├── config/
│ ├── workspace.yaml # 전역 설정 파일
│ └── company_brief.md # 회사/팀 컨텍스트 (선택 사항)
├── agents/ # 에이전트 설정 디렉토리
├── runs/ # 실행 기록 (run_id별 하위 디렉토리)
├── approvals/ # HITL 승인 큐 (JSONL 파일)
├── projects/ # 프로젝트별 컨텍스트
└── state/
└── memory.db # 장기기억 SQLite DB (첫 대화 후 생성)
workspace.yaml의 기본 내용을 확인합니다:
cat .euleragent/config/workspace.yaml
# euleragent workspace configuration
# Generated by `euleragent init`. Edit freely — comments are preserved.
version: 1
llm_profiles:
local:
provider: ollama
base_url: http://localhost:11434
model: qwen3:32b
timeout_seconds: 120
keep_alive: "5m"
is_external: false
openai:
provider: openai
api_key: ""
model: gpt-4o-mini
base_url: https://api.openai.com/v1
is_external: true
# --- Gemini via OpenAI-compatible endpoint (uncomment to enable) ---
# gemini:
# provider: openai_compat
# api_key: ""
# model: gemini-2.0-flash
# base_url: https://generativelanguage.googleapis.com/v1beta/openai
# is_external: true
default_llm_profile: local
# ... (budget, policy, memory, tools_policy, rag sections) ...
mcp:
enabled: false
servers: []
# --- Uncomment below to add MCP servers ---
# servers:
# - id: demo_sqlite
# url: http://localhost:9020/mcp
# allow_tools: [sqlite.query, demo.echo]
Ollama 사용 시:
default_llm_profile: local이 기본값이므로 Ollama가 실행 중인지 확인하세요 (ollama serve). 오프라인 테스트를 원하면default_llm_profile: fake로 변경하세요.Tip:
workspace.yaml에는 주석으로 Gemini 프로필과 MCP 서버 예시가 포함되어 있습니다. - Gemini 사용:# gemini:블록의 주석을 해제하고GEMINI_API_KEY를 설정하세요. - OpenAI 사용:openai.api_key에 API 키를 입력하고default_llm_profile: openai로 변경하세요. - MCP 서버 연결:mcp:섹션의servers:주석을 해제하세요. 데모 서버는python examples/mcp/sqlite_tools_server.py로 실행할 수 있습니다.
Step 5: 에이전트 생성
euleragent new 명령어로 사전 정의된 템플릿에서 에이전트를 생성합니다. 사용 가능한 템플릿은 personal-assistant, marketing-expert, code-assistant, ops-assistant 4가지입니다.
euleragent new my-assistant --template personal-assistant
예상 출력:
Agent 'my-assistant' created at .euleragent/agents/my-assistant
Files:
agent.yaml
tools.yaml
prompts/system.md
prompts/output_templates.md
생성된 에이전트 파일을 확인합니다:
cat .euleragent/agents/my-assistant/agent.yaml
name: my-assistant
description: "Personal assistant for daily tasks and information lookup"
template: personal-assistant
version: "1.0"
memory:
enabled: true
retrieval:
top_k: 5
min_score: 0.2
provider: null # null이면 workspace.yaml의 default_llm_profile 사용
model: null # null이면 프로필 기본 모델 사용
tools_denylist: [] # 이 에이전트에서만 차단할 도구 목록
tools.yaml도 확인해봅니다:
cat .euleragent/agents/my-assistant/tools.yaml
policy: deny-all # 명시적 허용 목록에 없는 도구는 모두 차단
allowlist:
- file.read
- file.write
- memory.store
- memory.search
require_approval:
- file.write
- file.delete
- shell.exec
- web.search
- web.fetch
- email.send
deny-all 원칙:
policy: deny-all은 euleragent의 핵심 보안 설계입니다.allowlist에 명시된 도구만 에이전트가 사용할 수 있습니다.require_approval목록의 도구는 실행 전에 사람의 승인이 필요합니다.
Step 6: 첫 번째 태스크 실행 (Plan 모드)
이제 에이전트를 실행합니다. 기본 모드는 plan으로, 에이전트가 어떤 행동을 취할지 제안하고 실제 실행은 사람의 승인을 기다립니다.
euleragent run my-assistant \
--task "AI 에이전트 프레임워크를 3줄로 요약해줘" \
--mode plan
예상 출력:
Run a1b2c3d4e5f6 started (agent: my-assistant, mode: plan)
Task: AI 에이전트 프레임워크를 3줄로 요약해줘
[loop 1/5] Generating plan...
→ No tool calls proposed (text response only)
Run a1b2c3d4e5f6 completed (state: RUN_FINALIZED)
Artifacts:
.euleragent/runs/a1b2c3d4e5f6/artifacts/plan.md
0 approval(s) pending.
참고: 이 예시에서는 에이전트가 도구 호출 없이 텍스트만 반환했습니다. 도구 호출이 포함된 시나리오는 다음 단계에서 다룹니다.
생성된 아티팩트를 확인합니다:
cat .euleragent/runs/a1b2c3d4e5f6/artifacts/plan.md
## AI 에이전트 프레임워크 요약
1. AI 에이전트 프레임워크는 LLM이 도구(tool)를 호출해 실제 작업을 수행할 수 있도록 하는 오케스트레이션 레이어입니다.
2. 주요 프레임워크로는 LangChain, CrewAI, AutoGen, euleragent 등이 있으며, 각각 멀티 에이전트 협력, 반복 루프, 승인 게이트에서 차별화됩니다.
3. euleragent는 로컬 우선(local-first), HITL 승인, 감사 로그를 핵심 원칙으로 삼는 프레임워크입니다.
Step 7: 도구 호출이 포함된 태스크 실행
file.write 도구를 사용하는 태스크를 실행해 승인 흐름을 경험합니다:
euleragent run my-assistant \
--task "summary.md 파일을 만들고 AI 에이전트 프레임워크를 3줄로 요약해서 저장해줘" \
--mode plan
예상 출력:
Run b2c3d4e5f6a1 started (agent: my-assistant, mode: plan)
Task: summary.md 파일을 만들고 AI 에이전트 프레임워크를 3줄로 요약해서 저장해줘
[loop 1/5] Generating plan...
→ Proposed: file.write (risk: medium)
Run b2c3d4e5f6a1 completed (state: PENDING_APPROVAL)
1 approval(s) pending. Use `euleragent approve list --run-id b2c3d4e5f6a1`
PENDING_APPROVAL 상태는 에이전트가 승인이 필요한 도구 호출을 제안했고, 사람의 검토를 기다리고 있다는 의미입니다.
Step 8: 승인 목록 확인
euleragent approve list
예상 출력:
Pending approvals (1):
ID TOOL RISK RUN STATUS
apv_x1y2z3 file.write medium b2c3d4e5f6a1 pending
특정 런의 승인만 필터링하려면:
euleragent approve list --run-id b2c3d4e5f6a1
승인 상세 내용을 확인합니다:
euleragent approve show apv_x1y2z3
예상 출력:
{
"id": "apv_x1y2z3",
"run_id": "b2c3d4e5f6a1",
"tool_name": "file.write",
"params": {
"path": "summary.md",
"content": "## AI 에이전트 프레임워크 요약\n\n1. AI 에이전트 프레임워크..."
},
"risk_level": "medium",
"status": "pending",
"created_at": "2026-02-23T10:30:00Z"
}
Step 9: 일괄 승인 및 실행
승인 내용을 확인한 후 모든 대기 승인을 수락하고 즉시 실행합니다:
euleragent approve accept-all --run-id b2c3d4e5f6a1 --actor "user:you" --execute
예상 출력:
Accepted 1 approval(s).
[OK] file.write (apv_x1y2z3)
Executed 1/1 successfully.
Run b2c3d4e5f6a1 state: RUN_FINALIZED
Artifacts:
.euleragent/runs/b2c3d4e5f6a1/artifacts/plan.md
summary.md ← 실제 파일이 생성됨
실제로 파일이 생성되었는지 확인합니다:
cat summary.md
Step 10: 감사 로그 읽기
모든 실행의 상세 로그는 euleragent logs 명령어로 확인할 수 있습니다:
euleragent logs b2c3d4e5f6a1
예상 출력:
Run: b2c3d4e5f6a1
Agent: my-assistant
Task: summary.md 파일을 만들고...
Mode: plan
State: RUN_FINALIZED
Started: 2026-02-23 10:30:00
Ended: 2026-02-23 10:30:45
Events:
10:30:00 run.started
10:30:02 loop.started (1/5)
10:30:04 tool.proposed file.write → apv_x1y2z3
10:30:05 loop.ended
10:30:05 run.pending_approval
10:30:30 approval.accepted apv_x1y2z3
10:30:31 tool.executed file.write → OK
10:30:31 run.finalized
JSON 형식으로 출력하려면:
euleragent logs b2c3d4e5f6a1 --format json
런 디렉토리를 직접 탐색할 수도 있습니다:
ls .euleragent/runs/b2c3d4e5f6a1/
input.json # 실행 입력 파라미터
messages.jsonl # 전체 LLM 대화 기록
tool_calls.jsonl # 도구 호출 기록
approvals.jsonl # 승인 기록
artifacts/ # 생성된 파일들
diffs/ # 파일 변경 diff (해당 시)
예상 출력 요약
튜토리얼에서 실행한 각 명령어의 결과를 정리합니다:
# 설치
$ euleragent --version
euleragent 0.1.x
# 진단
$ euleragent doctor
[OK] Python 3.11.x [OK] euleragent installed ...
# 초기화
$ euleragent init
Workspace initialized at /home/user/my-project/.euleragent
# 에이전트 생성
$ euleragent new my-assistant --template personal-assistant
Agent 'my-assistant' created at .euleragent/agents/my-assistant
# 실행 (도구 호출 없는 경우)
$ euleragent run my-assistant --task "..." --mode plan
Run a1b2c3d4e5f6 completed (state: RUN_FINALIZED)
0 approval(s) pending.
# 실행 (도구 호출 있는 경우)
$ euleragent run my-assistant --task "..." --mode plan
Run b2c3d4e5f6a1 completed (state: PENDING_APPROVAL)
1 approval(s) pending.
# 일괄 승인 + 실행
$ euleragent approve accept-all --run-id b2c3d4e5f6a1 --actor "user:you" --execute
Accepted 1 approval(s). Executed 1/1 successfully.
# 감사 로그
$ euleragent logs b2c3d4e5f6a1
Run: b2c3d4e5f6a1 ... State: RUN_FINALIZED
자주 묻는 질문 / 흔한 오류
Q: euleragent: command not found 오류가 납니다.
pip install -e .가 완료되지 않았거나 pip가 설치한 스크립트 경로가 PATH에 없는 경우입니다.
# pip 설치 경로 확인
pip show euleragent | grep Location
# 일반적으로 ~/.local/bin 이 PATH에 있어야 합니다
echo $PATH | grep -o '[^:]*local[^:]*'
# PATH에 없다면 .bashrc 또는 .zshrc에 추가
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Q: euleragent doctor에서 Ollama가 not reachable이라고 나옵니다.
Ollama 없이도 fake 프로바이더로 모든 기능을 테스트할 수 있습니다:
# .euleragent/config/workspace.yaml
default_llm_profile: fake
실제 LLM을 사용하려면:
ollama serve # 터미널 1에서 실행 유지
ollama pull qwen3:8b # 모델 다운로드 (최초 1회)
Q: 워크스페이스가 이미 존재할 때 euleragent init을 실행하면 어떻게 되나요?
기존 설정 파일을 덮어쓰지 않습니다. 이미 존재하는 파일은 건드리지 않고 누락된 파일만 생성합니다. 안전하게 재실행할 수 있습니다.
Q: euleragent run 실행 후 state가 PENDING_APPROVAL인데 승인하지 않으면 어떻게 되나요?
승인 레코드는 .euleragent/approvals/ 디렉토리에 영구적으로 저장됩니다. 언제든지 나중에 euleragent approve list로 확인하고 처리할 수 있습니다. 시스템을 재시작해도 승인 대기 상태가 유지됩니다.
Q: --mode plan과 --mode execute의 차이는 무엇인가요?
plan: 에이전트가 어떤 도구를 어떻게 사용할지 제안만 하고, 실제 실행은 사람이 승인한 후에 이루어집니다.execute: 승인이 필요 없는 도구는 즉시 실행합니다.require_approval목록의 도구는 여전히 승인이 필요합니다.
자세한 내용은 02_plan_execute_mode.md를 참조하세요.
Q: --path 옵션으로 다른 경로에 워크스페이스를 만들 수 있나요?
euleragent init --path /tmp/test-workspace
이후 해당 디렉토리에서 euleragent 명령어를 실행하면 됩니다. euleragent는 현재 디렉토리에서 상위 방향으로 .euleragent/를 찾습니다.
자주 하는 실수 (순서 어긋남)
| 증상 | 원인 | 복구 |
|---|---|---|
Error: No euleragent workspace found. |
euleragent init 미실행 |
euleragent init |
Error: Agent 'X' not found. |
euleragent new 미실행 |
euleragent new X --template personal-assistant |
Error: No task provided. |
--task 또는 --task-file 누락 |
euleragent run <agent> --task '...' |
다음 단계: 02_plan_execute_mode.md — Plan 모드와 Execute 모드를 비교하고 에이전틱 루프를 이해합니다.