환경 설정

이 문서에서 할 일

이 페이지를 마치면 uv 설치 → 템플릿 패키지 준비 → llamon CLI 실행 → 첫 프로젝트 생성까지 끝납니다. 에이전트 코드를 직접 작성하는 단계는 다음 문서에서 다룹니다.

0. 템플릿 패키지 받기

llamon CLI는 llamon-agent-template 패키지 안에 동봉된 SDK wheel로 동작합니다. 먼저 이 패키지를 확보하세요.

출처	내용
내부 배포 채널	llamon-agent-template-<version>.tar.gz 배포 패키지
압축 해제 후 포함 파일	llamon_agent-*.whl, llamon_agent-*.whl.sha256, uv.lock, update_sdk_wheel.sh

압축을 풀고 그 디렉토리 안에서 모든 명령을 실행합니다.

tar -xzf llamon-agent-template-X.Y.Z.tar.gz
cd llamon-agent-template

---

사전 요구 사항

항목	최소 버전
Python	3.11 이상, 기본 권장 3.14
uv	최신 버전
Docker	20.10 이상 (llamon run 실행 시 필요)
docker compose	v2 이상

---

1. uv 설치

uv는 Python 패키지 매니저로, llamon-agent-template 프로젝트 실행에 사용합니다.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널을 재시작하거나 아래 명령으로 PATH를 적용하세요:

source $HOME/.local/bin/env

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

또는 winget을 사용하는 경우:

winget install --id=astral-sh.uv -e

설치 후 PowerShell을 재시작하세요.

설치 확인:

uv --version

---

2. Python 설치 (uv로 관리)

uv python install 3.14

uv가 Python 버전을 자동으로 관리하므로 시스템에 별도로 Python을 설치할 필요가 없습니다.

---

3. llamon-agent-template 프로젝트 설정

제공받은 llamon-agent-template 디렉토리에는 다음이 이미 포함되어 있습니다.

파일	설명
llamon_agent-*.whl	SDK 패키지 (별도 다운로드 불필요)
llamon_agent-*.whl.sha256	무결성 검증용 체크섬
uv.lock	의존성 버전 고정 파일 (frozen)

사용자가 할 작업은 .venv 가상 환경 생성 하나입니다.

uv sync --frozen        # .venv 생성 + 의존성 설치 (uv.lock 기준)

• --frozen은 동봉된 uv.lock을 변경 없이 그대로 사용합니다. uv sync로 실행해도 결과는 동일하지만, --frozen이 lock 파일 변경을 방지해 더 안전합니다.
• SDK wheel의 SHA-256 무결성 검증은 Docker 빌드 시 자동 수행됩니다 (Dockerfile 내 sha256sum -c).
• 완료 후 .venv/ 안에 llamon CLI가 자동으로 등록됩니다.

---

4. llamon CLI 실행 방법

llamon-agent-template 디렉토리 안에서 uv run 접두사로 실행합니다:

# 생성
uv run llamon --help
uv run llamon agent --help            # 단일 에이전트 프로젝트 생성
uv run llamon flow --help             # 플로우(멀티 에이전트 그래프) 프로젝트 생성

# 로컬 실행/점검
uv run llamon run --help              # 로컬 docker compose 실행/정리
uv run llamon doctor --help           # 프로젝트 점검

# 오프라인 준비/패키징
uv run llamon prepare-offline --help  # doctor → vendor-deps → doctor → package 한 번에 실행
uv run llamon vendor-deps --help      # (개별) 오프라인 wheelhouse만 준비
uv run llamon package --help          # (개별) 배포용 tar.gz만 생성

# 배포/운영
uv run llamon deploy --help           # SSH 접근 가능한 원격 서버 배포 (폐쇄망 아님)
uv run llamon restore-online --help   # prepare-offline 이전 Dockerfile 복원

# 보조 도구
uv run llamon studio --help           # 플로우 Studio 실행
uv run llamon memory --help           # 메모리 DB 관리 (prune 등)

주요 흐름만 빠르게 보면 아래처럼 이해하면 됩니다.

• 생성: agent, flow
• 로컬 실행/점검: run, doctor
• 오프라인 준비/패키징 (폐쇄망): prepare-offline, vendor-deps, package, restore-online
• 원격 배포 (SSH 가능 환경, 폐쇄망 아님): deploy
• GitLab/server 배포 자산 생성: --deploy-profile gitlab-server
• 보조 도구: studio, memory

실행/점검과 배포 예시는 각각 로컬 실행/점검, 원격 배포 문서를 참고하세요.

전역 설치 (선택 사항)

프로젝트 디렉토리 외부에서도 llamon 명령을 바로 사용하려면:

uv tool install ./llamon_agent-*.whl

설치 후에는 접두사 없이 사용 가능합니다:

llamon agent

제거하려면:

uv tool uninstall llamon-agent

---

5. 새 프로젝트 생성

llamon-agent-template 디렉토리 안에서 새 프로젝트를 생성합니다. 생성된 프로젝트는 현재 디렉토리의 하위 디렉토리로 만들어집니다.

# 단일 에이전트: 대화형
uv run llamon agent

# 단일 에이전트: 한 줄 생성 (Registry 기반 기본)
uv run llamon agent my-agent --template agent-general --yes

# 멀티 에이전트 플로우: 대화형
uv run llamon flow

# 멀티 에이전트 플로우: 한 줄 생성
uv run llamon flow my-flow --template flow-seq --yes

자세한 내용은 에이전트/플로우 생성 (llamon agent/flow), 로컬 실행/점검 (llamon run/doctor/prepare-offline), 원격 배포 (llamon deploy)를 참고하세요.

---

6. 환경 변수 (한눈에)

.env.example을 .env로 복사한 뒤 채웁니다. 템플릿을 고르면 생성된 .env에는 그 시나리오에 필요한 변수만 들어 있으므로, 보통 아래 “연결 변수” 한두 개만 채우면 됩니다.

시나리오 → 템플릿 → 연결 변수

내 상황에 맞는 한 줄만 보면 됩니다.

시나리오	권장 템플릿	채울 연결 변수
LLaMON Registry 사용	agent-general (기본) · agent-structured (구조화 출력)	LLAMON_REGISTRY_HOST
OpenAI API 직접	agent-openai	OPENAI_API_KEY
Anthropic API 직접	agent-anthropic	ANTHROPIC_API_KEY
로컬 Ollama 실험	agent-local	OLLAMA_BASE_URL (기본 http://localhost:11434)

예를 들어 agent-openai를 골랐다면 OPENAI_API_KEY만 채우면 되고, 이 키는 다른 템플릿에서는 쓰이지 않습니다. (provider 템플릿은 모델명을 지정하는 OPENAI_MODEL·ANTHROPIC_MODEL·OLLAMA_MODEL도 함께 생성하지만, 기본값이 있어 선택입니다.)

Registry 접근권이 없다면 직접 모델 연결 페이지로 이동하세요.

모든 템플릿 공통 (전부 선택)

관측성·로깅 변수입니다. 어떤 템플릿이든 동일하게 동작하며 없어도 됩니다.

변수	용도	예시
LANGFUSE_PUBLIC_KEY · LANGFUSE_SECRET_KEY	Langfuse tracing (둘 다 있으면 자동 활성화)	pk-lf-... · sk-lf-...
LANGFUSE_BASE_URL	Langfuse 호스트	https://us.cloud.langfuse.com
LANGFUSE_ENABLED	tracing 강제 on/off (미설정 시 키 유무로 자동 판단)	true
LOG_LEVEL	SDK·사용자 코드(app.*) 로그 레벨 (DEBUG/INFO/WARNING/ERROR)	WARNING
UVICORN_LOG_LEVEL	uvicorn 서버 로그 레벨 (LOG_LEVEL과 독립)	info

세부 동작은 문제 해결 → SDK 로그 레벨 참조.

---

문제 해결

자주 발생하는 오류와 해결 방법은 문제 해결을 참고하세요.