에이전트/플로우 생성 (llamon agent/flow)

이 문서에서 할 일

llamon agent / llamon flow 로 새 프로젝트를 생성하고 .env 를 초기화한 뒤, 로컬에서 첫 호출까지 확인합니다. 먼저 환경 설정 을(를) 마치세요.

개요

llamon agent(단일 에이전트), llamon flow(멀티 에이전트 그래프)는 새 프로젝트 디렉토리에 템플릿 파일을 생성합니다.

기본 흐름: llamon agent 생성 → llamon run 로컬 실행 → llamon prepare-offline 배포 준비 → llamon deploy 원격 배포.

uv 설치와 기본 실행은 환경 설정, 배포 시나리오별 조합은 생성/배포 시나리오를 참고하세요.

---

빠른 시작

시작 전 준비

이 문서는 환경 설정을 마쳤다고 가정합니다(uv 설치 + 템플릿 패키지 준비). 특히 아래 3) 로컬 실행의 llamon run은 Docker Desktop(또는 Docker 데몬)이 실행 중이어야 동작하며, 꺼져 있으면 Cannot connect to the Docker daemon 오류가 납니다.

# 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를 고르면 됩니다.

단일 에이전트 (llamon agent)

템플릿	언제	설명
agent-general	일반 대화·검색·도구 호출	사용자에게 보여줄 텍스트 중심 Registry 에이전트
agent-structured	분류·추출·판정	다음 단계가 읽을 output_data 중심. app/runtime_adapter.py가 모델 JSON을 검증해 output_text/output_data를 보장
agent-local	로컬 Ollama 실험	Ollama 직접 연결
agent-openai	Registry 없이 OpenAI	OpenAI API URL 직접 연결
agent-anthropic	Registry 없이 Anthropic	Claude API 직접 연결

멀티 에이전트 플로우 (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

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

---

생성 명령

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

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

--template만 바꾸면 다른 종류가 됩니다(위 표 참고). --memory postgres를 주면 docker-compose.local.yml에 postgres 서비스가 자동 포함되고, 기본 DB 이름은 <project_name>_memory입니다.

---

.env 설정

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

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

두 플래그를 모두 생략해도 채울 값이 남아 있으면, 생성 후 “지금 입력할까요?”를 한 번 물어봅니다.

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	템플릿 지정 (위 표 참고)
--memory off|in-memory|postgres|sqlite(legacy)	메모리 모드
--runtime-source registry|local	런타임 소스 (registry: 레지스트리 노드, local: 로컬 LLM)
--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 키 / 로컬 LLM 연결값	필수
config.py	② LLM/Prompt/MCP/Guardrail ID 또는 로컬 Agent 설정	필수
agent_card.py	③ 카드 정보·스킬	필수
main.py	진입점	수정 불필요

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

파일	역할	수정
.env	① Registry Host 또는 로컬 LLM 연결값	필수
config.py	② 에이전트 UUID / 로컬 Agent 설정	필수
nodes.py	③ 노드 함수·비즈니스 로직	필수
graph.py	④ 노드 연결 구조 (.edge())	필요 시
agent_card.py	⑤ 카드 정보·스킬	필수
main.py	진입점	수정 불필요

설정값 배치 원칙

위치	담는 것
.env	배포 환경별 실제 값과 secrets
config.py	여러 노드가 공유하는 이름·기본값·배선 정보
nodes.py	특정 노드 하나만 쓰는 구현 디테일

자세한 기준, Studio 승급/강등 제안, 기존 프로젝트 마이그레이션은 프로젝트 설정 구조를 참고하세요.

---

다음 단계

• 에이전트 구성 배우기: Registry 기반 에이전트 → 프로젝트 설정 구조
• 노드·스킬 편집: Studio UI 또는 생성된 파일 직접 수정
• 그래프 패턴: 직렬 · 병렬 · 조건 분기
• 로컬 실행/패키징/점검: llamon run/doctor/prepare-offline
• 원격 배포: llamon deploy
• 자주 발생하는 오류: 문제 해결