프로젝트 생성과 첫 호출

개요

세 가지 프로젝트 타입을 만들 수 있습니다.

llamon agent — 단일 에이전트 서버
llamon flow — 멀티 에이전트 그래프
llamon orchestrator / llamon orch — 자식 에이전트를 조율하는 Workflow Orchestrator (오케스트레이터 가이드)

모두 새 프로젝트 디렉토리에 템플릿 파일을 생성합니다. 기본 흐름은 생성 → llamon run 로컬 실행 → llamon prepare-offline 배포 준비 → llamon deploy 원격 배포입니다.

현재 설치된 SDK가 제공하는 공개 템플릿과 Runtime Evaluation starter는 공통 카탈로그에서 확인할 수 있습니다. CLI와 Studio의 새 프로젝트 화면은 이 카탈로그를 함께 사용하므로 한쪽에만 보이는 템플릿이 생기지 않습니다.

uv run llamon scaffold list
uv run llamon scaffold list --kind flow
uv run llamon scaffold list --output json

uv 설치와 기본 실행은 환경 설정을 참고하세요.

빠른 시작

# 1) 생성 (인자 없이 실행하면 대화형 메뉴)
uv run llamon agent my-agent --template agent-general --memory postgres --yes
cd my-agent

# 2) .env 채우기 (LLAMON_REGISTRY_HOST 등 — setup 페이지 참고)

# 3) 로컬 실행
uv run llamon run .

# 4) 첫 호출 (다른 터미널)
curl -s http://localhost:8000/.well-known/agent-card.json
curl -s -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "msg-001",
        "contextId": "demo",
        "role": "user",
        "parts": [{"kind": "text", "text": "안녕하세요"}]
      }
    }
  }'

응답이 오면 첫 성공입니다. 포트는 .env의 PORT 값에 따라 달라질 수 있습니다. 요청 필드 의미와 A2A 0.3.0 응답 예시는 A2A 메시지 요청을 참고하세요.

무엇을 만들까

llamon agent는 단일 에이전트 서버, llamon flow는 멀티 에이전트 그래프(비즈니스 로직 노드 포함, 기본 --runtime-source registry)를 만듭니다. 처음이라면 보통 agent-general로 충분합니다. 구조화 결과는 agent-structured, DataPart 요약은 data-summary, ORCH가 만든 임시 후보 판정은 outcome-evaluator를 고르세요.

Studio에서 새 프로젝트 만들기

uv run llamon studio .

Studio 시작 화면의 새 프로젝트에서 프로젝트 타입 → Runtime Source → 템플릿을 고르고, 필요할 때만 고급 설정을 펼칩니다. 만들기 전 Review 단계는 생성 파일, 필요한 env, readiness blocker와 다음 명령을 미리 보여 줍니다. 생성 후 Agent와 Flow는 비주얼 편집기로, Orchestrator는 app/orchestrator.py와 orchestrator.toml을 기준으로 하는 read-only 요약으로 엽니다.

Runtime Source 기본값은 Registry입니다. Agent는 Registry 전용/Local 전용 템플릿을 나눠 표시하고, Flow는 각 공개 템플릿에 현재 선택한 Registry 또는 Local 구현을 적용합니다. Quick Recipe도 Registry(기본)·Local·Orchestrator 그룹으로 분리되며, 선택한 카드는 현재 설정과 일치하는 동안 활성 상태로 남습니다.

Agent·Flow의 Local은 “같은 머신”이 아니라 Registry 비의존 연결입니다. Local에서 Component Source를 components로 고르면 app/components.py와 명시적 components= bootstrap을 생성하고, 기본 direct는 기존 Agent(...) 코드를 그대로 유지합니다. Orchestrator에는 별도의 Runtime Source selector가 있으며 두 템플릿 모두 Registry와 Local을 지원합니다.

Agent: Registry·직접 모델 연결·구조화·업무 특화 템플릿
Flow: Sequential·Parallel·Routing·HTTP와 Registry/local runtime
Orchestrator: generic·local-children, Agentic rules-first/full 또는 Deterministic
Starter: 없음(기본)·observability·rubric-judge·groundedness

Recipe gallery의 카드는 같은 입력값으로 preview를 먼저 만들며, 예제 프로젝트 복사본을 저장소에 커밋하지 않습니다. Template 카드에는 현재 mode와 Registry/Local 지원 범위가 각각 표시됩니다.

상황별 추천 (템플릿 + 명령)

내 상황에 맞는 템플릿과 후속 명령 조합입니다. 기본 scaffold는 compose 자산을 포함하므로 llamon run·llamon deploy·prepare-offline을 바로 쓸 수 있습니다.

상황	템플릿	후속 명령
로컬에서 바로 확인	`agent-general` 또는 `flow-seq`	`llamon run .`
SSH 원격 서버에 배포	기본 scaffold	`llamon deploy . --target ubuntu@<server>`
폐쇄망(오프라인) 반입	기본 scaffold	`llamon prepare-offline . --clean`
플로우로 시작	`flow-seq`	`llamon run .`
ORCH 결과 evaluator 배포	`outcome-evaluator`	prompt seed 확인 → Registry 수동 업로드 → `llamon run .`

GitLab 서버 배포 자산이 필요하면 생성 시 --deploy-profile gitlab-server를 추가하고, Docker Compose 자산이 아예 필요 없으면 --no-docker를 씁니다.

uv run llamon agent my-agent \
  --template agent-general \
  --deploy-profile gitlab-server \
  --yes

단일 에이전트 (`llamon agent`)

템플릿	언제	설명
`agent-general`	일반 대화·검색·도구 호출	사용자에게 보여줄 텍스트 중심 Registry 에이전트
`agent-structured`	분류·추출·판정	다음 단계가 읽을 `output_data` 중심. `app/runtime_adapter.py`가 모델 JSON을 검증해 `output_text`/`output_data`를 보장
`data-summary`	DataPart 요약·WorkHistory	response contract로 입력을 투영하고 요약 DataPart를 생성
`outcome-evaluator`	ORCH 후보 검증	SDK verification adapter가 요청과 판정을 fail-closed로 검증하고 decision DataPart 하나만 반환
`agent-ollama`	Ollama 직접 연결	Registry 없이 Ollama API 사용
`agent-openai`	Registry 없이 OpenAI	OpenAI API URL 직접 연결
`agent-anthropic`	Registry 없이 Anthropic	Claude API 직접 연결
`agent-structured-ollama`	Registry 없이 구조화 출력	Ollama 출력 JSON을 Pydantic으로 검증

일반 Agent의 최종 응답 평가 예제까지 만들려면 --example을 추가합니다. observability는 네트워크 없는 완성도 baseline, rubric-judge는 정확성·명확성 rubric, groundedness는 입력 documents 근거 평가를 합성합니다. 모두 app/evaluation.py와 계약 테스트를 만들고 evaluator를 create_server()에 연결합니다. 별도의 runtime_adapter.py를 만들거나 기존 어댑터를 바꾸지 않습니다. ORCH verification 전용인 outcome-evaluator에는 starter를 적용할 수 없고 memory도 항상 off입니다.

멀티 에이전트 플로우 (`llamon flow`)

템플릿	언제	그래프
`flow-seq`	순서대로 연결	`agent_a → business_logic → agent_b`
`flow-parallel`	동시에 실행	`agent_a + agent_b → merge → business_logic`
`flow-route`	조건 분기	`router → agent_a/b → business_logic`
`flow-http`	HTTP 파이프라인	`http → transform → merge → agent`

관측과 평가 코드까지 포함하려면 어느 Flow 템플릿에든 --example observability|rubric-judge|groundedness를 추가합니다. 기존 노드 함수와 배포 설정은 그대로 유지되고, 선택한 노드의 evaluator 목록만 합성됩니다.

Workflow Orchestrator (`llamon orchestrator`, `llamon orch`)

여러 자식의 선택·실행·재개·최종 응답을 한 경계에서 관리합니다. 대화형 생성은 bounded agentic loop를 기본으로 제안하며, 구조적으로 확정된 경로를 먼저 실행하는 rules-first를 권장합니다. LLM 판단이 필요 없는 병렬·트랜잭션 흐름은 deterministic의 run_turn(ctx) 템플릿으로 시작합니다.

템플릿	언제	설명
`generic`	Registry/HTTP child를 섞어 사용	agentic·deterministic workflow 공통 자산 생성
`local-children`	HTTP/port child로 시작	Registry 또는 Components controller를 명시적으로 선택

--runtime-source registry는 기존 Registry controller와 child 의미를 유지합니다. --runtime-source local은 child·controller model·prompt를 생성된 app/components.py에서 해석하며 Registry로 fallback하지 않습니다.

Orchestrator도 같은 --example starter를 받을 수 있습니다. 이 경우 평가 대상은 자식 호출 각각이 아니라 Orchestrator의 최종 completed 출력입니다. 자식 호출 평가는 ctx.call_observed()가 반환하는 observation ref에 별도로 연결합니다.

# 가장 짧은 시작: Wizard가 workflow와 필요한 ID·자식 연결을 묻습니다.
uv run llamon orch support-desk

자동화에서만 선택값을 모두 고정합니다.

# CI용 Agentic rules-first 생성
uv run llamon orch support-desk \
  --template generic \
  --workflow agentic \
  --scope rules-first \
  --agent rag=8101 \
  --agentic-model 59 \
  --agentic-prompt support-supervisor \
  --yes

# CI용 Deterministic 생성
uv run llamon orch settlement \
  --workflow deterministic \
  --agent primary=8101 \
  --yes

--workflow agentic은 --scope rules-first|full을 받습니다. rules-first는 OKF 고정 경로 뒤에 bounded controller를 두고, full은 첫 의미 판단부터 controller가 맡습니다. 두 범위 모두 input/output guardrail, WorkMemory, HumanReview, 호출 상한을 같은 오케스트레이터 경계에서 적용합니다.

대화형 Wizard에서 Agentic을 고르면 누락된 controller model Registry ID와 supervisor prompt Registry ID를 이어서 묻습니다. Registry를 조회하거나 값을 추측하지는 않습니다.

기존 --recipe direct|rules|adaptive|hybrid|agentic도 호환을 위해 유지합니다. 기존 프로젝트와 자동화는 그대로 동작하며, 새 프로젝트는 --workflow를 사용하세요. --recipe와 --workflow는 한 명령에서 함께 지정하지 않습니다.

비TTY 또는 --yes 자동화에서 새 workflow를 만들 때는 --workflow를 명시하세요. --workflow와 --recipe를 모두 생략하면 하위 호환을 위해 기존 direct scaffold를 생성합니다.

자식 연결은 orchestrator.toml [agents]에 매핑합니다. 오케스트레이터는 자체 WorkflowState store를 쓰므로 --memory 옵션은 받지 않지만, 컴포넌트 공급원은 --runtime-source registry|local로 고릅니다. 생략은 기존 추론을 보존합니다. 결정하지 못한 Agent 연결은 CLI가 추측하지 않고 readiness 항목으로 남깁니다.

자세한 작성법은 오케스트레이터 가이드를 참고하세요.

내부 스캐폴드 ID(registry-general, graph-sequential, ollama, orchestrator-generic 등)는 구현용 이름입니다. CLI·문서는 공개 키(agent-general, flow-seq, generic 등)를 기준으로 보면 됩니다.

생성 명령

# 단일 에이전트
uv run llamon agent my-agent --template agent-general --yes

# Agent 최종 응답을 평가하는 예제
uv run llamon agent my-agent --template agent-general --example observability --yes

# ORCH verification evaluator (memory는 항상 off)
uv run llamon agent quality-evaluator \
  --template outcome-evaluator \
  --memory off \
  --yes

# 멀티 에이전트 플로우
uv run llamon flow my-flow --template flow-seq --yes

# 기존 노드 함수를 유지하는 관측·평가 예제
uv run llamon flow my-flow --template flow-seq --example observability --yes

# LLM rubric judge가 포함된 Agent starter
uv run llamon agent judged-agent \
  --template agent-general \
  --example rubric-judge \
  --yes

# 근거 평가가 포함된 Deterministic Orchestrator starter
uv run llamon orch grounded-orch \
  --template generic \
  --workflow deterministic \
  --agent primary=8101 \
  --example groundedness \
  --yes

# 멀티턴 오케스트레이터 — 상세 선택은 Wizard에서 입력
uv run llamon orch support-desk

--template만 바꾸면 다른 종류가 됩니다(위 표 참고). 메모리를 지원하는 템플릿은 모두 MEMORY_BACKEND를 읽는 동일한 코드를 생성하므로, 처음 in-memory를 골라도 나중에 Python 수정 없이 .env를 postgres로 바꾸고 uv run python scripts/migrate_memory.py를 실행하면 됩니다. --memory postgres를 주면 compose.yml에 PostgreSQL·migration·keyring init 서비스가 자동으로 포함되고, 기본 DB 이름은 <project_name>_memory입니다. outcome-evaluator는 요청 간 기억이 판정에 섞이지 않도록 memory를 off로 고정하며, 다른 --memory 값은 생성 단계에서 거부합니다. 상세한 DSN·키링 설정은 메모리 영속화와 암호화를 참고하세요.

.env 설정

생성된 .env에는 <레지스트리주소>처럼 아직 채워야 할 값이 남아 있습니다. 채우는 방법은 세 가지입니다.

메모리 관련 키는 모든 전환 가능 템플릿에서 backend → scope/keyring → pool/lifecycle → runtime/migration DSN → memory limit 순서로 동일하게 정렬됩니다. 기본이 off 또는 in_memory이면 PostgreSQL DSN과 키링은 읽지 않습니다.

# 1) 생성 시 값 직접 주입
uv run llamon agent my-agent --template agent-general --yes \
  --env LLAMON_REGISTRY_HOST=http://<레지스트리주소>:7860

# 2) 대화형 입력 (--yes와 함께 못 씀)
uv run llamon agent my-agent --template agent-general --configure-env

--configure-env는 포트와 그 밖에 채워야 할 값을 하나씩 물어 .env에 채워 줍니다. 포트는 단일이면 PORT를 묻고, 멀티면 BASE_PORT 하나만 입력하면 나머지가 자동 배정됩니다. 반대로 --yes는 질문을 건너뛰고 기본값을 그대로 쓰므로, 둘은 함께 줄 수 없습니다.

두 플래그를 모두 생략해도 채울 값이 남아 있으면, 생성 후 “지금 입력할까요?”를 한 번 물어봅니다. outcome-evaluator는 예외입니다. 새 prompt ID는 seed를 Registry에 올린 뒤 생기므로 생성할 때는 자동으로 묻지 않습니다. 업로드를 마친 뒤 .env에 ID를 입력하세요. 기존 ID가 있다면 --configure-env를 명시해 생성 중에 입력할 수도 있습니다.

이 템플릿의 trace backend는 기본적으로 none입니다. 운영 관측은 인증값을 설정한 뒤 명시적으로 켜세요. 생성된 tests/conftest.py는 NullBackend를 강제하므로 테스트가 로컬 .env의 Langfuse 인증값을 읽어 실제 trace를 보내지 않습니다.

3) 기본값 자동 상속 — LLAMON_REGISTRY_HOST가 현재 셸 환경변수나 CLI 실행 디렉토리의 .env에 있으면, 생성된 프로젝트 .env에 기본값으로 자동 반영됩니다.

유용한 옵션

# 파일을 쓰지 않고 생성/덮어쓰기 예정 파일 + 필요한 .env 키만 출력
uv run llamon agent my-agent --template agent-general --yes --dry-run
uv run llamon agent my-agent --template agent-general --yes --dry-run --output json

# 생성 후 .env 준비 + docker compose 기동 + agent-card 확인까지 자동
uv run llamon agent my-agent --template agent-general --yes --quickstart

--output json은 --dry-run과 함께 사용합니다. --quickstart는 환경값/UUID가 준비된 경우에 동작합니다.

주요 플래그

플래그	설명
`--template`	템플릿 지정 (위 표 참고)
`--example observability\|rubric-judge\|groundedness`	일반 Agent·Flow·Orchestrator에 Runtime Evaluation starter 추가
`--memory off\|in-memory\|postgres\|sqlite(legacy)`	메모리 모드
`--runtime-source registry\|local`	scaffold/runtime 소스 (local: Registry 비의존 직접 연결)
`--component-source direct\|components`	Agent·Flow local 공급원. Components는 명시적 catalog와 bootstrap 생성
`--port`	서비스 포트
`--no-docker` · `--no-git` · `--force`	docker 자산·git init 생략 / 기존 디렉토리 덮어쓰기
`--yes`	질문에 모두 기본값 자동 선택

.env 관련(--env, --configure-env)은 위 .env 설정, 점검·자동 실행(--dry-run, --quickstart)은 위 유용한 옵션 항목을 보세요. SDK 소스(--sdk-source/--sdk-version)·배포 자산(--deploy-profile)·로컬 provider(--ollama-base-url, --local-provider)와 전체 목록은 --help에 있습니다.

파일 구조

번호 순서로 수정합니다.

단일 에이전트 (`llamon agent`)

파일	역할	수정
`.env`	① Registry Host / API 키 / Code-first 모델 연결값	필수
`config.py`	② LLM/Prompt/MCP/A2A/Guardrail ID 또는 Code-first Agent 설정	필수
`agent_card.py`	③ 카드 정보·스킬	필수
`main.py`	진입점	수정 불필요

outcome-evaluator에는 app/evaluator_policy.py, prompt 본문을 담은 prompts/outcome-evaluator-system-prompt.template.md, Registry 업로드용으로 생성되는 prompts/outcome-evaluator-system-prompt.md, tests/conftest.py, tests/test_evaluator_policy.py가 추가됩니다. criterion은 Python에서, prompt 본문은 Markdown template에서 수정하세요. 그런 다음 python -m app.evaluator_policy --write와 --check로 seed를 다시 생성·검사합니다. 검사가 끝나면 Registry에 새 prompt version을 수동으로 올리고, .env의 model/prompt ID를 실제 값으로 바꾼 뒤 policyVariant를 높이세요.

멀티 에이전트 플로우 (`llamon flow`)

파일	역할	수정
`.env`	① Registry Host 또는 Code-first 모델 연결값	필수
`config.py`	② 공유 ID·이름·라벨·기본값 / Code-first Agent 설정	필수
`nodes.py`	③ 노드 함수·비즈니스 로직	필수
`graph.py`	④ 노드 연결 구조 (`.edge()`)	필요 시
`agent_card.py`	⑤ 카드 정보·스킬	필수
`main.py`	진입점	수정 불필요

설정값 배치 원칙

위치	담는 것
`.env`	배포 환경별 실제 값과 secrets
`config.py`	여러 노드가 공유하는 ID·이름·라벨·기본값
`nodes.py`	특정 노드 하나만 쓰는 구현 세부사항

자세한 기준, Studio 승급·강등 제안, 기존 프로젝트 마이그레이션은 에이전트 구성의 설정값 배치 원칙을 참고하세요.

SDK 패치 후 재배포

생성 후 SDK wheel을 교체했다면 아래 순서로 다시 맞추는 편이 안전합니다.

cd my-agent
./update_sdk_wheel.sh .
uv lock
uv run llamon prepare-offline . --clean
uv run llamon deploy . --target ubuntu@<server>

update_sdk_wheel.sh는 템플릿 프로젝트에 포함됩니다. ./update_sdk_wheel.sh .는 새 llamon_agent-*.whl 파일이 현재 프로젝트 루트에 이미 있을 때 쓰는 형태입니다. wheel 파일이 다른 경로에 있으면 --wheel /path/to/<wheel>.whl를 붙이세요.

여러 에이전트를 한 번에 갱신하려면 대상 디렉토리를 나란히 넘깁니다 — ./update_sdk_wheel.sh . ../agent-b ../agent-c. wheel 갱신만 하고 uv lock / uv sync는 건너뛰고 싶다면 --files-only를 추가하세요.

다음 단계

에이전트 구성 배우기: Registry 기반 에이전트
노드·스킬 편집: Studio UI 또는 생성된 파일 직접 수정
그래프 패턴: 플로우 템플릿
로컬 실행/패키징/점검: llamon run/doctor/prepare-offline
원격 배포·폐쇄망 준비: 실행과 배포
자주 발생하는 오류: 문제 해결

프로젝트 생성과 첫 호출

개요

빠른 시작

무엇을 만들까

Studio에서 새 프로젝트 만들기

상황별 추천 (템플릿 + 명령)

단일 에이전트 (llamon agent)

멀티 에이전트 플로우 (llamon flow)

Workflow Orchestrator (llamon orchestrator, llamon orch)

생성 명령

.env 설정

유용한 옵션

주요 플래그

파일 구조

단일 에이전트 (llamon agent)

멀티 에이전트 플로우 (llamon flow)

설정값 배치 원칙

SDK 패치 후 재배포

다음 단계

단일 에이전트 (`llamon agent`)

멀티 에이전트 플로우 (`llamon flow`)

Workflow Orchestrator (`llamon orchestrator`, `llamon orch`)

단일 에이전트 (`llamon agent`)

멀티 에이전트 플로우 (`llamon flow`)