프로젝트 설정 구조

이 문서에서 할 일

.env · config.py · nodes.py 3계층에 설정값을 어디에 둘지 기준을 잡습니다. 먼저 Registry 기반 에이전트 를 읽으면 좋습니다.

이 문서는 이런 경우에 보세요

• 생성된 프로젝트에서 .env, config.py, nodes.py 중 어디를 고쳐야 할지 헷갈릴 때
• 여러 노드가 공유하는 설정값을 정리하고 싶을 때
• Studio의 승급/강등 제안이나 기존 프로젝트 마이그레이션 기준을 확인할 때

환경값과 config.py — 3계층 모델

원칙

config.py는 공유되는 이름과 기본값의 단일 진입점입니다. 값과 secrets는 항상 .env → RuntimeEnv 경유로 읽으세요.

프로젝트 설정값은 수명주기(lifecycle) 축으로 나눠 두면 “어디에 뭐가 있어야 하지?”라는 혼란이 사라집니다.

계층	위치	담는 것	예시
노드 수명	nodes.py 상단 RuntimeEnv(source_file=__file__)	해당 노드 하나만 쓰는 환경변수 값	단일 HTTP 노드의 API_ENDPOINT
프로젝트 수명	config.py	여러 노드가 공유하는 이름·기본값 + 배선 정보	registry_llm, agent UUID, ExtensionConfig, 공유 환경변수 키 기본값
배포 수명	.env	배포 환경별 실제 값 + secrets	POSTGRES_URL, API_KEY, OPENAI_API_KEY

어디에 둘지 결정하는 규칙

• 1개 노드만 쓰는 환경변수 → 해당 nodes.py 상단에서 RuntimeEnv 직접 호출
• 2개 이상 노드가 공유하는 환경변수 → config.py에 기본값을 올리고 각 노드에서 import
• 모든 “실제 값”과 secrets → .env에만. config.py에 secret이 들어가면 안 됨

강제 아닌 가이드라인

3계층은 강제가 아니라 가이드라인입니다. 참조 노드가 1개여도 긴 프롬프트·도메인 상수·enum·매핑 테이블처럼 가독성이나 도메인 의미가 기준이면 config.py에 두는 게 자연스럽습니다.

Studio의 승급 제안은 단순 “참조 카운트” 기반이라 무시해도 동작에 영향이 없습니다 — 프로젝트 의미론에 맞게 판단하세요.

승급·강등 (Studio 자동 제안)

Studio는 노드 코드를 분석해 승급(2개 이상 노드가 같은 키를 공유 → config.py로) 과 강등(config.py 상수가 1개 노드만 참조 → 노드 로컬로) 을 제안합니다. 키마다 기본값이 다르면 적용 불가이며 값 통일을 먼저 안내합니다. SECRET·KEY·TOKEN·PASSWORD·DSN·URL·PASS 가 이름에 들어가면 자동 승급에서 제외됩니다(수동은 가능). [적용] 전 diff 미리보기로 확인하고, 쓰기 실패 시 전체 롤백됩니다.

Agent Editor 저장은 안전합니다

v0.2.0부터 Studio 저장은 config.py의 build_extension() 함수만 AST-merge로 교체합니다. 사용자가 추가한 상수(AGENT_A_ID, *_EXT 등)·승급된 공유 상수·주석은 모두 보존됩니다.

config.py 에 환경변수 값이 직접 들어간 경우 (Migration)

v0.2.0 이전 프로젝트에서는 config.py 에 POSTGRES_URL = "postgresql://..." 처럼 값을 직접 작성해 사용한 경우가 있습니다. 다음 두 가지 중 편한 쪽을 선택하세요.

방법 1) Studio 경고에 따라 점진 전환 (권장)

Studio 노드 사이드패널 하단의 “config.py 에 secret 의심 상수” 경고를 확인합니다. 경고 상수는 .env 로 옮기고, config.py 에서는 값 대신 이름 참조만 남기세요.

# Before (config.py)
POSTGRES_URL = "postgresql://user:***@host/db"

# After (config.py — 이 상수를 아예 제거)
# (아무것도 남기지 않음)

# After (app/nodes.py — RuntimeEnv 로 직접 읽기)
from llamon_agent.config import RuntimeEnv
env = RuntimeEnv(source_file=__file__)
POSTGRES_URL = env.get("POSTGRES_URL", "")   # 값은 .env 에서 주입

.env 파일에 실제 값을 두는 건 기존과 동일합니다:

POSTGRES_URL=postgresql://user:pass@host/db

방법 2) Studio 강등 제안 수락

비밀값이 아닌 공유 상수(예: 숫자/문자 기본값)가 config.py 에 정의되어 있고 참조 노드가 1개뿐이면, Studio 가 자동으로 “노드 로컬로 되돌릴까?” 강등 제안을 띄웁니다. [미리보기] → [적용] 으로 수정.

방법 3) 유지

Studio UI 도움 없이 기존 config.py 구성을 그대로 두고 싶다면 그냥 두세요. 기존 코드는 변함없이 동작합니다. 다만 secret 값은 반드시 .env 로 옮기길 권장합니다 — 커밋 레벨에서 자격 증명 노출 리스크가 큽니다.

다음 단계

• 입력 선별: InputContracts
• 확정 MCP 호출: deterministic_tool