스쿼드 만들기¶

템플릿을 선택하거나 에이전트를 직접 구성하여 스쿼드를 만들 수 있습니다. 네 단계 마법사가 기본 정보, 워크스페이스 선택, 에이전트 구성, 최종 검토를 안내합니다.

템플릿 사용하기¶

가장 빠른 시작 방법은 미리 만들어진 템플릿을 사용하는 것입니다. 사이드바에서 스쿼드 페이지를 열고 스쿼드 생성을 클릭하면 템플릿 갤러리가 나타납니다.

기본 제공 템플릿¶

템플릿 카드를 클릭하면 스쿼드를 만들기 전에 에이전트와 구성을 미리 볼 수 있습니다.

사용자 지정 템플릿¶

모든 스쿼드를 재사용 가능한 템플릿으로 저장할 수 있습니다. 스쿼드의 구성을 세밀하게 조정한 후 템플릿으로 저장 작업을 사용하면 향후 사용을 위해 갤러리에서 사용할 수 있게 됩니다.

설정 마법사¶

1단계: 기본 정보¶

스쿼드의 이름과 선택적 설명을 입력합니다. 스쿼드의 목적을 식별할 수 있는 명확한 이름을 선택하세요 (예: "인증 모듈 스쿼드", "블로그 콘텐츠 스쿼드").

2단계: 워크스페이스¶

스쿼드가 파일을 저장할 워크스페이스 디렉토리를 선택합니다. 마법사가 다음을 검증합니다:

• 경로가 절대 경로인지
• 경로가 존재하고 쓰기 가능한지
• 다른 스쿼드가 같은 디렉토리를 사용하고 있지 않은지
• 경로가 애플리케이션 데이터 디렉토리에 닿지 않는지

워크스페이스는 플랜, 태스크, 에이전트 파일, 메타데이터를 위한 하위 디렉토리로 구성됩니다.

스쿼드를 만들면 해당 디렉토리와 하위 디렉토리를 만들고 logs/에 테스트 파일을 하나 써 봅니다. 여기서 실패하면 스쿼드는 만들어지지 않고, 오류에 경로와 운영체제가 알린 이유가 나옵니다. 나중에 스쿼드의 워크스페이스를 바꿀 때도 같은 방식으로 확인하죠. 헤드리스 서버의 웹 UI를 사용할 때는 이 확인이 서버에서 이뤄지므로, 워크스페이스는 서버가 쓸 수 있는 경로여야 합니다. 배포되는 systemd 유닛에서는 홈 디렉토리를 사용할 수 없고, 오류에 관련된 유닛 설정이 함께 나옵니다. 자세한 내용은 systemd 환경의 스쿼드 워크스페이스를 보세요.

애플리케이션 데이터 디렉토리 자체, 그 안쪽, 그 상위 디렉토리를 워크스페이스로 지정하면 거부되며, 레거시 ~/.backend-ai-go 디렉토리나 소켓 디렉토리에 닿는 경로도 마찬가지입니다. 이 디렉토리에는 설정, API 접근 키, 저장된 자격 증명, 저장된 스쿼드가 들어 있어, 겹치는 워크스페이스를 지정하면 모든 스쿼드 에이전트가 이 전부를 읽고 쓸 수 있게 되고 워크스페이스 디렉토리 유지 없이 스쿼드를 삭제하면 이 디렉토리가 함께 삭제됩니다. 같은 이유로 홈 디렉토리를 선택하는 것도 거부되지만, 그 안의 프로젝트 디렉토리는 사용할 수 있습니다. 이 검사는 이후 워크스페이스를 탐색하거나 검색할 때마다 다시 실행되므로, 이 검사가 생기기 전에 기록된 워크스페이스를 가진 스쿼드라도 애플리케이션 소유 디렉토리를 노출하지 않고 거부합니다.

3단계: 에이전트¶

스쿼드의 에이전트를 구성합니다. 다음 방법을 사용할 수 있습니다:

• 템플릿에서 시작 — 선택한 템플릿에서 에이전트가 미리 채워집니다
• 수동으로 에이전트 추가 — 에이전트 추가를 클릭하고 역할을 선택합니다
• 프로필에서 가져오기 — 코워크 에이전트 프로필 마켓플레이스에서 에이전트 구성을 가져옵니다

각 에이전트에 대해 다음을 구성합니다:

에이전트 역할¶

• 플래너 — 스쿼드를 조율합니다. 요청을 분석하고, 플랜을 만들고, 태스크를 할당하고, 진행 상황을 추적합니다. 스쿼드당 정확히 한 명의 플래너를 지정하세요.

• 개발자 — 코드를 작성하고 수정합니다. 프로젝트 파일을 읽고 쓰기 위한 파일 시스템 도구에 접근할 수 있습니다.

• 리뷰어 — 품질, 보안, 정확성을 위해 출력을 검토합니다. 일반적으로 읽기 전용 접근 권한을 가집니다.

• 작성자 — 문서, 글, 기타 서면 콘텐츠를 작성합니다.

• 사용자 지정 — 미리 정의된 카테고리에 맞지 않는 역할을 정의합니다. 사용자 지정 역할 이름을 입력하고 시스템 프롬프트를 조정하세요.

4단계: 검토¶

전체 스쿼드 구성을 검토합니다:

• 스쿼드 이름과 설명
• 워크스페이스 경로
• 역할과 도구 접근 권한이 표시된 에이전트 목록
• 지정된 플래너 에이전트

스쿼드 만들기를 클릭하면 완료됩니다. 워크스페이스 디렉토리가 자동으로 생성되고 초기화됩니다.

필수 항목이 아직 비어 있으면(예: 사용자화로 에이전트 구성 단계로 바로 이동해 워크스페이스 디렉토리를 지정하지 않은 경우) 제출하지 않고 해당 단계로 돌아갑니다. 백엔드에서 생성이 실패하면 오류가 다이얼로그 안에 표시되고, 수정한 에이전트를 포함한 입력 구성이 그대로 유지되므로 문제를 해결한 뒤 다시 시도할 수 있습니다.

스쿼드 관리¶

스쿼드 편집¶

스쿼드를 열고 구성을 수정합니다 — 이름 변경, 에이전트 추가 또는 제거, 시스템 프롬프트 변경, 도구 접근 권한 조정. 변경 사항은 다음 실행부터 적용됩니다.

에이전트별 모델 지정¶

스쿼드는 보통 역할에 따라 에이전트마다 다른 모델을 사용하는데, 예를 들어 플래너에는 큰 모델을, 작성자에게는 작은 모델을 지정하는 식입니다. 스쿼드 상세 페이지 헤더의 더 보기(⋯) 메뉴에 있는 에이전트 모델 설정이나 스쿼드 카드의 모델 설정을 누르면 에이전트마다 모델 선택기가 있는 대화 상자가 열리고, 여러 에이전트에 서로 다른 모델을 한 번에 지정할 수 있습니다.

• 각 선택기에는 해당 에이전트가 지금 사용하는 모델이 표시됩니다. 다른 모델을 고르면 변경됩니다.
• 모두 변경에서 모델을 고르면 모든 에이전트의 선택기가 그 모델로 채워집니다. 선택기는 그대로 편집할 수 있어서, 적용하기 전에 일부 에이전트만 다른 모델로 바꿀 수 있습니다.
• 기본 모델을 고르면 에이전트의 모델 지정이 지워지고, 해당 에이전트는 설정 > 모델의 기본 에이전트 모델을 사용합니다. 이 항목에는 그 모델의 이름이 표시되고, 지정되지 않았다면 지정 안 됨으로 표시됩니다.
• 바뀐 에이전트에는 변경됨 표시가 붙고, 적용 버튼에 변경 개수가 나타납니다. 스쿼드에 저장된 값과 다른 항목이 없으면 버튼은 비활성화됩니다.

적용하면 해당 스쿼드에 한해 모든 변경이 한 번에 저장되고, 모델이 바뀐 에이전트 수가 알림으로 표시됩니다. 적용하지 않은 변경이 있을 때 대화 상자 바깥을 누르면 창이 닫히지 않고 흔들리며, 취소를 누르면 변경이 버려집니다. 원격 에이전트(등록된 원격 프로필에서 추가한 에이전트)는 모델 호출이 원격 노드에서 실행되므로 목록에 나오지 않습니다.

스쿼드 삭제¶

스쿼드를 삭제할 때 다음을 선택할 수 있습니다:

• 워크스페이스 디렉토리 유지 — 앱에서 스쿼드를 제거하지만 디스크의 모든 파일은 보존
• 모두 삭제 — 스쿼드와 워크스페이스 디렉토리를 모두 제거

워크스페이스에서 가져오기¶

스쿼드 탭의 워크스페이스에서 가져오기(개요 탭에도 바로가기가 있습니다)를 누르면 폴더 선택 창이 열리고, 선택한 폴더의 내용에 따라 다음 두 가지 중 하나가 일어납니다.

• 폴더에 .squad-config.json 매니페스트가 있는 경우. 이 파일은 워크스페이스 디렉토리 유지를 선택하고 스쿼드를 삭제할 때 기록됩니다. 마법사가 복원 모드로 열리며 스쿼드의 이름, 설명, 에이전트가 미리 채워지므로, 구성을 확인한 뒤 스쿼드 항목을 다시 생성할 수 있습니다.
• 폴더에 매니페스트가 없는 경우. 기존 스쿼드의 워크스페이스나 새 프로젝트 폴더를 포함한 나머지 모든 디렉토리가 여기에 해당합니다. 마법사가 생성 모드로 열리고 해당 폴더가 워크스페이스로 이미 선택되어 있으므로, 이미 가지고 있는 코드를 중심으로 새 스쿼드를 구성할 수 있습니다.

매니페스트가 있지만 읽을 수 없는 경우(잘린 파일, 잘못된 JSON, 지원하지 않는 스키마 버전)에는 마법사가 열리지 않고 오류가 표시됩니다. 파일을 고치거나 삭제한 뒤 다시 시도하세요.