콘텐츠로 이동

4.4. 스쿼드 템플릿 카탈로그

스쿼드 템플릿 카탈로그를 사용하면 GitHub 기반 카탈로그에 게시된 미리 제작된 스쿼드 템플릿을 찾아 설치할 수 있습니다. 이는 개별 에이전트 프로필을 배포하는 것과 동일한 다중 소스 레지스트리를 사용합니다. 카탈로그는 바로 사용할 수 있는 팀 레시피(예: "오픈소스 코드 리뷰 크루" 또는 "한국어 번역 팀")를 제공하므로, 처음부터 구성할 필요 없이 완전히 구성된 스쿼드를 추가할 수 있습니다.

카탈로그 템플릿은 로컬에 설치된 후 다른 사용자 템플릿과 똑같이 동작합니다. 적용, 내보내기, 삭제가 가능합니다. 내장 템플릿은 읽기 전용으로 유지됩니다.

카탈로그 둘러보기

  1. 사이드바에서 카탈로그 페이지를 엽니다.
  2. 스쿼드 템플릿 탭을 선택합니다.
  3. 각 카드에는 템플릿의 아이콘, 이름, 카테고리, 설명, 태그, 작성자, 버전, 출처 소스가 표시됩니다.

레지스트리 소스를 두 개 이상 구성한 경우, 필터 칩을 사용해 그리드를 단일 소스로 좁힐 수 있습니다. 새로고침을 사용하면 로컬 캐시를 무시하고 최신 인덱스를 다시 가져옵니다.

스쿼드 템플릿과 에이전트 프로필은 하나의 공유 레지스트리 소스 목록을 통해 배포됩니다. 설정 → 레지스트리 소스에서 소스를 추가, 제거, 활성화 또는 비활성화하면 커뮤니티(에이전트) 탭과 스쿼드 템플릿 탭에 동시에 적용됩니다. 스쿼드 템플릿을 위한 별도의 소스 목록은 없습니다.

템플릿 설치하기

카드에서 설치를 클릭합니다. Backend.AI GO가 소스에서 템플릿 JSON을 가져와 스키마 버전을 검증하고 로컬 squad-templates 디렉터리에 기록합니다. 설치가 완료되면:

  • 카드에 설치가 아닌 설치됨이 표시됩니다.
  • 템플릿이 템플릿 갤러리(스쿼드 → 새 스쿼드)에 카탈로그에서 설치됨 배지와 함께 내장 및 로컬 생성 템플릿과 나란히 나타납니다.

설치된 템플릿이 참조하는 모델

카탈로그 템플릿은 각 에이전트의 모델 설정을 담고 있습니다. 설치된 템플릿이 로컬에 없는 모델을 참조하는 경우, 해당 에이전트는 자동으로 설정 → 모델에서 지정한 기본 모델로 대체됩니다. 따라서 설치된 템플릿은 선호 모델을 다운로드하기 전에도 항상 사용할 수 있습니다. 스쿼드 템플릿 탭은 그리드 위에 이 동작에 대한 안내를 표시합니다.

템플릿 제거하기

카탈로그 템플릿은 설치되면 사용자 템플릿이 되므로, 다른 사용자 템플릿을 제거하는 것과 동일한 방식으로 제거합니다.

  • 템플릿 갤러리(스쿼드 → 새 스쿼드)에서 템플릿 카드의 삭제 동작을 사용하고 확인합니다.

내장 템플릿은 삭제할 수 없습니다. 설치된 카탈로그 템플릿을 삭제하면 로컬 사본만 제거되며, 언제든지 카탈로그에서 다시 설치할 수 있습니다.

스쿼드 템플릿을 카탈로그에 게시하기

카탈로그를 작성하는 것은 순수한 데이터 작업입니다. 앱 릴리스나 백엔드 서비스가 관여하지 않습니다. 카탈로그는 raw.githubusercontent.com을 통해 제공되는 GitHub 저장소일 뿐입니다.

1. 템플릿 JSON 작성하기

직접 만든 스쿼드를 내보내거나(템플릿으로 저장 후 갤러리에서 내보내기) 템플릿 JSON 스키마를 따라 직접 작성하여 올바른 템플릿 JSON을 얻습니다. 카탈로그 저장소의 안정적인 경로에 배치합니다. 예:

your-catalog/
├── index.json
├── code-assistants/
│   └── python-expert.json        # 에이전트 프로필
└── squad-templates/
    └── code-review-crew.json     # 스쿼드 템플릿

스쿼드 템플릿의 관례적인 위치는 최상위 squad-templates/ 디렉터리이지만, 인덱스가 가리키기만 하면 어떤 상대 경로든 동작합니다.

2. index.json에 kind: "squad_template"로 나열하기

카탈로그의 index.json은 에이전트 프로필과 스쿼드 템플릿 모두에 대한 요약 항목을 하나의 목록에 담습니다. 각 스쿼드 템플릿 항목을 "kind": "squad_template"로 표시합니다.

{
  "version": 1,
  "updatedAt": "2026-05-28T00:00:00Z",
  "profiles": [
    {
      "path": "code-assistants/python-expert.json",
      "name": "Python Expert",
      "category": "code_assistant",
      "kind": "agent_profile"
    },
    {
      "path": "squad-templates/code-review-crew.json",
      "name": "Code Review Crew",
      "description": "Security, performance, and style reviewers as one team.",
      "category": "review",
      "author": "your-org",
      "icon": "🔐",
      "tags": ["review", "code-quality"],
      "version": "1.0.0",
      "kind": "squad_template"
    }
  ]
}

인덱스 형식은 추가적이며 하위 호환됩니다.

  • kind 필드가 없는 항목은 agent_profile로 기본 설정되므로, 기존 에이전트 전용 카탈로그(예: lablup/agent-catalog)는 변경 없이 계속 동작합니다.
  • squad_template을 이해하지 못하는 이전 앱 버전도 새 인덱스를 계속 파싱하며, 처리할 수 없는 종류는 단순히 무시합니다.

인덱스 항목은 카드 표시를 위한 요약 필드만 담습니다. 전체 에이전트 구성, 프롬프트, 도구, 모델 설정은 path에 있는 템플릿 JSON에 있으며, 사용자가 설치할 때만 가져옵니다.

3. 앱에서 소스 추가하기

설정 → 레지스트리 소스를 열고 저장소(소유자, 저장소, 브랜치, 레이블)를 추가하면, 앱이 저장소에 올바른 index.json이 포함되어 있는지 검증합니다. 그러면 스쿼드 템플릿이 스쿼드 템플릿 탭에 나타납니다. 소스 목록이 공유되므로, 에이전트 프로필이 있다면 동일한 소스에서 커뮤니티 탭에 나타납니다.

보안

카탈로그는 현재 서명이나 체크섬 검증을 수행하지 않습니다. GitHub TLS만 신뢰합니다. 서명되지 않은 스쿼드 템플릿을 배포하는 것은 허용됩니다. 스쿼드 템플릿은 순수한 구성(시스템 프롬프트, 도구 플래그, 모델 설정)이므로 가져오기 시 임의의 코드를 실행할 수 없기 때문입니다. 설치는 로컬 템플릿 가져오기와 동일한 검증 및 콘텐츠 제한(크기 상한, 에이전트 수, 필드 길이 검사)을 거치며, 가져온 템플릿은 항상 내장이 아닌 사용자 템플릿으로 강제됩니다.

에이전트 프로필과 스쿼드 템플릿을 모두 동일하게 다루는 카탈로그 전체 서명 검증은 별도의 후속 작업으로 추적됩니다.

작동 방식

둘러보기는 에이전트 프로필에 이미 사용되는 공유 집계 레지스트리 인덱스, HTTP 가져오기 + 캐시 계층, 다중 소스 저장소를 재사용합니다. 스쿼드 전용 부분은 인덱스 항목의 kind 판별자, 스쿼드 템플릿 저장 계층을 통해 템플릿을 설치하는 설치 핸들러, 그리고 스쿼드 템플릿 탭뿐입니다. 데스크톱(Tauri)과 헤드리스(REST) 빌드 모두 전체 둘러보기 및 설치 흐름을 지원합니다. REST 엔드포인트는 POST /api/v1/squad-registry/install입니다.