콘텐츠로 이동
LLaMON Agent SDK v0.6.0

오케스트레이터 시작하기

오케스트레이터는 여러 자식 Agent를 한 업무 흐름으로 묶습니다. 새 프로젝트에서는 먼저 실행 방식을 고르세요. 요청의 의미를 보고 도구를 선택해야 하면 Agentic, 호출 순서가 코드로 확정돼 있으면 Deterministic이 맞습니다.

선택알맞은 업무실행을 결정하는 곳
--workflow agentic상담, 검색, 분류처럼 요청마다 필요한 도구가 달라지는 업무OKF 규칙과 제한된 controller
--workflow deterministic정산, 병렬 조회, 외부 트랜잭션처럼 순서를 고정해야 하는 업무run_turn(ctx) Python 코드

대화형 업무라면 agentic의 rules-first로 시작하는 편이 좋습니다. DataPart schema나 명시적 조건으로 확정할 수 있는 요청은 규칙이 처리하고, 모호한 요청만 controller가 판단합니다. 처음부터 모든 도구 선택을 controller에 맡겨야 할 때만 --scope full을 사용하세요.

프로젝트 만들기

섹션 제목: “프로젝트 만들기”

처음 만드는 프로젝트라면 짧게 시작하세요.

Terminal window
# Wizard가 workflow, model·prompt와 자식 연결을 순서대로 묻습니다.
uv run llamon orch support-desk

orch는 orchestrator의 공식 별칭입니다. Wizard에서 Agentic rules-first를 고르면 확정 경로는 OKF 규칙으로 처리하고 나머지만 controller가 판단하는 프로젝트를 만듭니다. 처음부터 controller가 판단해야 하면 Agentic full, 호출 순서를 코드로 고정하려면 Deterministic run_turn을 고르세요.

긴 옵션형 명령은 사람이 외워 입력하는 빠른 시작이 아니라 CI나 팀 표준 scaffold를 재현하는 자동화 경로입니다.

Terminal window
# CI에서는 선택값을 모두 고정해 같은 scaffold를 반복 생성합니다.
uv run llamon orch support-desk \
  --runtime-source registry \
  --workflow agentic \
  --scope rules-first \
  --agent search=registry:support-search \
  --agentic-model 59 \
  --agentic-prompt support-supervisor \
  --yes

호출 순서를 직접 작성할 프로젝트는 이렇게 만듭니다.

Terminal window
# 대화형 Wizard에서 Deterministic run_turn을 선택해도 됩니다.
uv run llamon orch settlement


# 비대화형 자동화에서는 workflow와 자식을 명시합니다.
uv run llamon orch settlement \
  --runtime-source registry \
  --workflow deterministic \
  --agent inventory=registry:inventory \
  --agent payment=registry:payment \
  --yes

--agent alias=target은 자식의 연결 주소만 선언합니다. Agentic controller가 그 자식을 도구로 쓸 수 있다는 뜻은 아닙니다. 도구 허용 범위와 read_only·side_effecting 안전 등급은 orchestrator.toml에 따로 적습니다.

기존 --recipe direct|rules|adaptive|hybrid|agentic은 호환 설정입니다. 기존 자동화는 그대로 둘 수 있지만, 새 프로젝트에서는 --workflow agentic|deterministic을 사용하세요. --recipe와 --workflow를 한 명령에 함께 지정할 수 없습니다. Adaptive는 신규 workflow가 아니라 --recipe adaptive --preview 전용 레거시 미리보기입니다.

Registry 또는 Components source

섹션 제목: “Registry 또는 Components source”

두 Orchestrator 템플릿은 모두 --runtime-source registry|local을 받습니다. 생략하면 기존 prefix·recipe·generator 추론을 그대로 사용하므로 기존 자동화 결과는 바뀌지 않습니다. 명시적으로 registry를 고르면 target을 registry:<id>로 쓰고 Registry resolver를 사용합니다. local을 고르면 app/components.py와 in-memory resolver를 만들고 target은 bare ID로 씁니다.

입력 호환을 위해 local에서도 registry:<id>를 받을 수 있지만 prefix만 제거해 현재 Components ID로 해석합니다. Registry로 fallback하지 않으며, 누락된 child·controller·utility ref는 선택 source와 field path를 포함해 부팅 전에 실패합니다.

Terminal window
# Registry 없이 child와 controller model/prompt를 Components로 조립
uv run llamon orch support-desk \
  --template generic \
  --runtime-source local \
  --workflow agentic \
  --agent search=support-search \
  --agentic-model controller \
  --agentic-prompt controller-prompt \
  --yes

생성되는 파일

섹션 제목: “생성되는 파일”
파일먼저 확인할 내용
app/orchestrator.pyworkflow 진입점과 애플리케이션이 책임질 조립 코드
orchestrator.toml자식 target, AgenticProgram, 도구 안전 등급, 상태·기억 정책
okf/routing rule과 라우팅에 함께 쓰는 response contract
main.py서버 composition root. 보통 생성 직후에는 수정하지 않음
README.md프로젝트별 실행 명령과 남은 설정

rules-first 프로젝트의 Python은 실행 기계를 다시 구현하지 않습니다.

app/orchestrator.py
from llamon_agent.orchestrator import RuleSource, rules_workflow




# 현재 요청의 구조화 facts를 먼저 규칙과 대조합니다.
workflow = rules_workflow(
    source=RuleSource.request(context_turns=10),
    name="work",
)


# 서버가 이 진입점을 감지해 checkpoint와 최종화를 관리합니다.
run_turn = workflow.run

최소 설정

섹션 제목: “최소 설정”

Agentic 프로젝트는 controller와 허용할 도구만 먼저 연결하면 됩니다.

orchestrator.toml
[agents]
search = "registry:support-search"


[agentic.support]
model = "59"
prompt = "support-supervisor"
max_controller_steps = 4
max_tool_calls = 3


[agentic.support.human_review]
# 담당자 검수 포트를 붙이기 전에는 대기 상태가 생기지 않게 끕니다.
mode = "disabled"


[agentic.support.tools.search]
# 조회 전용 도구만 사용자 승인 없이 호출할 수 있습니다.
safety = "read_only"
input = "context"
response_data_schema = "support.search.result.v1"

전체 키와 허용값은 오케스트레이터 설정·API에 있습니다. 앱 전용 값은 [app.<namespace>]에 두고 composition root에서 검증하세요. SDK는 프로젝트 Python을 자동 import해 앱 설정의 뜻을 추측하지 않습니다.

orchestrator.toml
[app.turn_context]
# 이 값의 범위와 의미는 애플리케이션 validator가 소유합니다.
recent_turns = 5

첫 실행 전 확인

섹션 제목: “첫 실행 전 확인”
Terminal window
# TOML, alias, workflow wiring과 OKF 문서를 정적으로 검사합니다.
uv run llamon doctor .


# 로컬 A2A 서버를 실행합니다.
uv run python main.py

llamon doctor가 통과해도 연결된 자식의 도메인 계약까지 보장되지는 않습니다. 첫 테스트에서는 정상 완료뿐 아니라 input_required, 도메인 오류, 준비 중인 자식, 네트워크 실패를 각각 확인하세요.

다음 단계는 선택한 workflow에 따라 다릅니다.