개요·핵심 개념
Registry 기반 에이전트 SDK + CLI입니다. 모델·프롬프트·툴을 ID로 참조해 에이전트를 만들고, llamon CLI 하나로 프로젝트 생성부터 로컬 실행·폐쇄망 배포까지 같은 인터페이스로 진행합니다. 모든 에이전트는 A2A 프로토콜로 통신합니다.
uv sync --frozen # 의존성 설치uv run llamon agent my-agent --yes # 프로젝트 생성cd my-agent # 생성된 프로젝트로 이동# .env 채우기 (LLAMON_REGISTRY_HOST 등)uv run llamon run . # 로컬 실행무엇을 만들까 — agent · flow · orchestrator
섹션 제목: “무엇을 만들까 — agent · flow · orchestrator”프로젝트 타입은 세 가지입니다. 한 질문으로 고를 수 있습니다 — 이번 턴의 분기가 지난 턴에 쌓아둔 업무 상태를 읽어야 하나?
| 프로젝트 타입 | 무엇 | 상태(state) | 언제 |
|---|---|---|---|
| agent | 단일 에이전트 (LLM + tools/MCP + guardrail) | 에이전트별 멀티턴 메모리(thread) | 대화·검색·도구 호출 하나로 끝날 때 |
| flow | 정적 LangGraph 그래프 — 한 호출 안의 순서·분기·병렬 | 대화 메모리(thread) | 여러 노드를 한 번의 호출 안에서 엮을 때 |
| orchestrator | 여러 자식 에이전트를 묶는 stateful 워크플로우 | 대화 메모리 + 턴 간 구조적 누적 (remember·reduce) | 결과를 여러 턴에 걸쳐 누적해야 할 때 |
코드는 이렇게 생겼습니다
섹션 제목: “코드는 이렇게 생겼습니다”세 타입이 실제로 어떤 코드를 쓰는지 한눈에 비교하면:
# agent — 단일 에이전트. 모델·프롬프트·툴을 ID로 참조uv run llamon agent my-agent --yes# flow — 네 가지 그래프 패턴 중 하나로 시작 (seq · parallel · route · http)uv run llamon flow my-flow --template flow-seq --yes# orchestrator — Wizard에서 Agentic rules-first 또는 Deterministic을 선택uv run llamon orch support-deskagent·flow는 무엇을 엮을지 선언하면 런타임이 실행하고, orchestrator는 턴을 넘는 workflow 정책을 조립합니다. Agentic scaffold에서는 SDK가 선택·실행·resume·최종 emit을 맡습니다. 임의 if/for/try, 병렬 fan-out, 앱 트랜잭션이 필요할 때만 --workflow deterministic으로 관리형 run_turn 템플릿을 만듭니다. 이 경우에도 SDK가 출력 가드레일과 최종 emit을 소유합니다. 모든 orchestrator가 LLM을 쓰는 것은 아닙니다.
flow 와 orchestrator, 무엇이 다른가
섹션 제목: “flow 와 orchestrator, 무엇이 다른가”가장 헷갈리는 지점부터 짚으면 둘 다 대화 메모리는 턴을 넘어 유지됩니다. 그러니 “상태가 남느냐”로는 갈리지 않습니다. 기준은 하나입니다. 여러 자식을 가로지르는 워크플로우 레벨 누적 상태(remember·reduce)는 orchestrator에만 있습니다. flow는 흐름을 정적 그래프로 그리고, orchestrator는 bounded agentic loop 또는 명시적 run_turn으로 턴을 관리합니다.
| flow | orchestrator | |
|---|---|---|
| 비유 | 조립 라인 | 접수 창구 |
| 처리 단위 | 한 번의 요청 | 여러 번의 요청(턴) |
| 상태 | 대화 메모리는 턴을 넘어 남음 · 단, 워크플로우 레벨 누적은 없음 | 대화 메모리 + 워크플로우 레벨 누적 (remember·reduce) |
| 노드/자식 | 그래프 노드(에이전트·로직·HTTP)를 한 호출 안에서 | bounded agentic loop 또는 run_turn이 자식 에이전트를 매 턴 호출 |
- flow — 요청이 들어오면 노드들을 순서·분기·병렬로 거쳐 응답을 내고 끝납니다. → 예: 한 메시지를 받아 분류 → 요약 → 응답 까지 한 번에.
- orchestrator — bounded agentic loop 또는 명시적 코드가 매 턴 자식을 호출하고 결과를 워크플로 상태에 쌓아 다음 턴에서 이어갑니다. → 예: 턴1에 신분증, 턴2에 소득증명… 필수 서류가 다 모이면 그때 심사.
flow로 시작했다가 orchestrator로 올려야 할 신호
섹션 제목: “flow로 시작했다가 orchestrator로 올려야 할 신호”flow로 만들다가 아래 중 하나라도 나타나면 orchestrator로 올릴 때입니다:
- 지난 턴 결과를 이번 턴 입력에 합치려고 상태를 손수 들고 다니기 시작했다.
- 그래프 토폴로지로는 못 그리는
if/for/try분기가 늘었다. - “필수 항목이 다 모이면 그때 진행”처럼 여러 턴에 걸친 완료 조건이 생겼다.
셋 다 아니면 flow로 충분합니다. 불필요하게 orchestrator로 올릴 필요는 없습니다.
멘탈 모델 — 세 기둥
섹션 제목: “멘탈 모델 — 세 기둥”1. Registry — ID로 참조하는 중앙 저장소
섹션 제목: “1. Registry — ID로 참조하는 중앙 저장소”모델·프롬프트·가드레일·MCP를 ID로 보관하는 중앙 서버입니다. 코드는 ID만 참조하고, 실제 메타데이터는 런타임에 로드됩니다. 그래서 배포 환경이 바뀌어도 코드는 그대로고, .env의 LLAMON_REGISTRY_HOST 한 줄만 바꾸면 됩니다.
Registry 접근권이 없어도 됩니다 —
agent-openai·agent-anthropic·agent-ollama템플릿은 Code-first 모델 연결로 동작합니다.
2. A2A — 에이전트 사이의 공통 연결 계층
섹션 제목: “2. A2A — 에이전트 사이의 공통 연결 계층”모든 에이전트(agent·flow·orchestrator)는 **A2A 프로토콜(0.3.x)**로 메시지를 주고받습니다. 요청은 message/send·message/stream, 입력은 text·DataPart·FilePart입니다. 이 공통 연결 계층 덕분에 orchestrator가 자식 에이전트를, 에이전트가 다른 에이전트를 같은 방식으로 호출합니다.
요청·응답 형태는 A2A 메시지 요청, 에러 매핑은 에러 처리를 보세요.
3. 메모리 — 대화를 기억하는 방법
섹션 제목: “3. 메모리 — 대화를 기억하는 방법”대화 히스토리를 유지해 이전 맥락을 참고합니다. 모드는 off·in-memory·postgres이며, 운영에서는 postgres가 공유 풀 위에서 동작합니다. 필요하면 MEMORY_FACTS_MODE로 thread-scoped fact recall을 켜서 window 밖 사용자 사실을 보강할 수 있습니다. orchestrator의 턴 간 state 누적은 이 대화 메모리와 별도의 저장소를 씁니다(업무 진행 상황 vs 대화 로그).