콘텐츠로 이동

3.3. 에이전트 프로필

Backend.AI GO는 커뮤니티가 공유하는 사전 구성된 프로필을 검색하고 설치하거나, 직접 만들 수 있는 에이전트 프로필 시스템을 제공합니다.

에이전트 프로필이란?

에이전트 프로필은 Cowork 에이전트의 동작 방식을 정의하는 구성입니다. 각 프로필에는 다음이 포함됩니다:

  • 시스템 프롬프트: 에이전트의 성격과 전문성을 형성하는 지침
  • 도구 구성: 활성화된 도구와 해당 권한 설정
  • 모델 선호도: 프로필의 사용 사례에 권장되는 모델
  • 설정 오버라이드: 온도, 최대 토큰 수, 서브 에이전트 제한 등의 사용자 정의 설정

프로필 접근하기

  1. 사이드바에서 Cowork 아이콘을 클릭합니다.
  2. Cowork 패널에서 프로필 선택기를 엽니다.
  3. 로컬 또는 커뮤니티 탭에서 프로필을 탐색합니다.

프로필 선택기는 사용 가능한 모든 프로필을 표시합니다. 로컬 탭에는 설치 및 사용자 정의 프로필이, 커뮤니티 탭에는 활성화된 레지스트리 소스의 프로필이 표시됩니다.

커뮤니티 프로필 설치하기

레지스트리에서 프로필을 설치하려면:

  1. Community 탭에서 사용 가능한 프로필을 탐색합니다.
  2. 프로필 설명과 태그를 읽고 필요에 맞는 프로필을 찾습니다.
  3. 프로필 카드의 Install 버튼을 클릭합니다.
  4. 설치가 완료될 때까지 대기합니다.

설치가 완료되면 프로필이 커뮤니티 배지 표시와 함께 로컬 탭에 나타납니다.

프로필 정보

각 프로필 카드는 다음을 표시합니다:

  • 이름: 프로필의 표시 이름
  • 설명: 프로필이 수행하도록 설계된 작업
  • 태그: 카테고리 및 기능 (예: "research", "coding", "web-search")
  • 소스: 프로필이 제공되는 레지스트리 소스
  • 설치 상태: 프로필이 이미 설치되었는지 여부

여러 소스가 활성화된 경우 Community 탭 헤더의 필터 칩을 사용하여 소스별로 프로필을 필터링할 수 있습니다.

레지스트리 새로고침

레지스트리 인덱스는 네트워크 요청을 줄이기 위해 1시간 동안 로컬에 캐시됩니다. 목록을 강제로 새로고침하려면:

  1. Community 탭 헤더의 Refresh 버튼을 클릭합니다.
  2. 레지스트리가 최신 인덱스를 가져올 때까지 대기합니다.

레지스트리 소스 관리

Backend.AI GO는 여러 레지스트리 소스를 지원하여 다양한 GitHub 저장소에서 프로필을 검색하고 설치할 수 있습니다.

기본 소스

기본적으로 Backend.AI GO는 다음 공식 커뮤니티 레지스트리를 포함합니다:

https://github.com/lablup/agent-catalog

이 소스는 제거할 수 없으며 검증된 커뮤니티 기여 프로필을 제공합니다.

사용자 정의 소스 추가

사용자 정의 레지스트리 소스를 추가하려면:

  1. Settings (사이드바의 톱니바퀴 아이콘)으로 이동합니다.
  2. 설정 메뉴에서 Agent Registry Sources를 선택합니다.
  3. Add Source를 클릭합니다.
  4. GitHub 저장소 세부 정보를 입력합니다:
    • Repository Owner: GitHub 사용자 이름 또는 조직 (예: lablup)
    • Repository Name: 저장소 이름 (예: agent-catalog)
    • Branch: 브랜치 이름 (예: main)
    • Label: 이 소스의 표시 이름 (예: "My Custom Profiles")
  5. Add를 클릭하여 검증 및 저장합니다.

소스는 추가되기 전에 검증됩니다. 저장소 루트에 유효한 index.json 파일이 있어야 합니다.

소스 관리

Agent Registry Sources 설정 페이지에서 다음을 수행할 수 있습니다:

  • 소스 토글: 소스를 제거하지 않고 활성화 또는 비활성화
  • 소스 편집: 사용자 정의 소스의 레이블 또는 브랜치 업데이트
  • 소스 제거: 사용자 정의 소스 삭제 (기본 소스는 제거할 수 없음)

비활성화된 소스의 프로필은 Community 탭에 표시되지 않습니다.

사용자 정의 레지스트리 형식

사용자 정의 레지스트리는 프로필 메타데이터, 다운로드 URL, 버전 정보를 포함하는 JSON 인덱스를 제공해야 합니다.

인덱스의 각 프로필 항목은 언어별 표시를 위한 선택적 translations 필드를 지원합니다. 키는 IETF BCP 47 로케일 문자열(예: "ko", "ja", "zh-CN")이며, 각 로케일 항목에 번역된 name과 description을 지정할 수 있습니다. 해당 로케일에 번역이 없으면 기본 영어 필드로 자동 대체됩니다.

{
  "path": "code-assistants/python-expert.json",
  "name": "Python Expert",
  "description": "Python coding assistant",
  "category": "code_assistant",
  "tags": ["python", "coding"],
  "version": "1.0.0",
  "translations": {
    "ko": {
      "name": "파이썬 전문가",
      "description": "파이썬 코딩 어시스턴트"
    }
  }
}

translations 필드는 선택 사항이며 하위 호환성을 유지합니다. 이 필드가 없는 기존 인덱스도 변경 없이 계속 동작합니다.

콘텐츠 검증

Backend.AI GO는 설치 전에 커뮤니티 프로필의 무결성(바이트가 변경되지 않음)과, 선택적으로 진위성(신뢰할 수 있는 작성자가 게시함)을 검증할 수 있습니다. 동일한 검증 경로가 카탈로그의 스쿼드 템플릿도 다루므로, 하나의 체계가 모든 카탈로그 리소스를 보호합니다. 검증은 부가적이며 하위 호환됩니다. 기존의 서명되지 않은 카탈로그(공식 lablup/agent-catalog 포함)는 계속 동작합니다.

검증된 프로필 게시하기

각 프로필의 index.json 항목에 체크섬(그리고 선택적으로 서명)을 추가합니다.

  • 체크섬(무결성). 프로필 JSON의 정확한 바이트에 대한 sha256:<hex> 다이제스트를 항목의 checksum 필드에 넣습니다.
printf 'sha256:%s\n' "$(sha256sum code-assistants/python-expert.json | cut -d' ' -f1)"
  • 서명(진위성, 선택). 동일한 바이트에 대한 분리형 base64 Ed25519 서명을 항목의 signature 필드에 넣습니다. 일치하는 base64 공개 키를 소스의 신뢰 앵커로 설정합니다(설정 → 레지스트리 소스 → 검증 설정 → 서명 공개 키). 둘 다 있으면 서명이 검증되며, 불일치 시 설치가 차단됩니다.
{
  "path": "code-assistants/python-expert.json",
  "name": "Python Expert",
  "checksum": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "signature": "QmFzZTY0LWVuY29kZWQgRWQyNTUxOSBzaWduYXR1cmU="
}

소스별 검증 요구

각 소스에는 콘텐츠 검증 필수 토글이 있습니다(설정 → 레지스트리 소스 → 검증 설정).

  • 꺼짐(공개 GitHub 및 기존 소스의 기본값). 서명되지 않은 프로필은 설치되지만 커뮤니티 탭에서 미검증으로 표시됩니다(절대 녹색 "검증됨" 체크가 아님). 체크섬/서명을 가진 프로필은 여전히 검증되며, 불일치는 항상 설치를 차단합니다.
  • 켜짐. 이 소스에서의 모든 설치는 검증을 통과해야 합니다. 체크섬/서명이 없거나 불일치하는 프로필은 명확한 현지화된 오류와 함께 차단됩니다.

이는 기본적으로 안전합니다. 체크섬/서명이 일치하지 않는 리소스는 절대 설치되지 않으며, "콘텐츠 검증 필수"를 켜는 것은 소스별 명시적 작업입니다. 설치 후 프로필 카드에 검증됨 또는 미검증 배지가 표시됩니다(전송 신뢰 우회는 녹색 체크가 아닌 미검증 — 신뢰할 수 있는 소스로 표시됨).

자체 호스팅 (Go Enterprise) 카탈로그 소스

레지스트리 소스는 GitHub가 아닌 온프레미스 카탈로그 서버를 가리키고 인증할 수 있습니다. 설정 → 레지스트리 소스 → 소스 추가에서 자체 호스팅 카탈로그 서버를 켜고 서버의 전체 기본 URL을 입력한 다음, 소스의 전송 인증 패널을 구성합니다.

  • 인증 방법: none / bearer / api_key / basic / mtls.
  • 사용자 지정 CA / 프록시: 기업 사설 CA를 신뢰하고(소스별 경로 또는 전역 설정 → 일반 → 사용자 지정 CA 인증서 경로) 송신 프록시를 통해 라우팅합니다. "TLS 검증 건너뛰기" 옵션은 없습니다.
  • 자격 증명 저장: 소스별 비밀(토큰, API 키, 비밀번호, mTLS 클라이언트 ID)은 운영체제 키체인에만 저장되며, sources.json에 기록되거나 로그에 남거나 UI로 반환되지 않습니다. 패널은 자격 증명이 설정되어 있는지만 표시합니다.

전송 인증과 콘텐츠 검증은 독립적이며 함께 구성할 수 있습니다. "전송 신뢰, 미서명" 검증 우회와 카탈로그 엔드포인트 자체의 인바운드 인증 보안 요구 사항을 포함한 전체 자체 호스팅 설정은 스쿼드 템플릿 카탈로그 → 자체 호스팅 카탈로그 인증을 참조하세요.

오프라인 동작

각 레지스트리 소스는 stale-while-revalidate 캐싱 전략을 사용합니다:

  • 온라인: 첫 번째 액세스 시 최신 인덱스를 가져온 다음 1시간 동안 캐시 사용
  • 오프라인: 사용 가능한 경우 마지막 캐시된 인덱스 사용
  • 캐시 누락: 캐시된 데이터가 없고 네트워크를 사용할 수 없는 경우 오류 표시

여러 소스가 구성된 경우 실패한 소스는 경고 배너를 표시하지만 성공적으로 가져온 소스는 계속 작동합니다.

개인정보 보호 및 보안

  • 커뮤니티 프로필은 공개 GitHub 저장소에서 가져옵니다
  • 프로필 설치는 로컬 전용입니다(원격 측정 또는 추적 없음)
  • 설치하기 전에 항상 프로필 설명과 권한을 검토하세요
  • 공식 레지스트리의 프로필은 유지 관리자가 검토합니다

프로필 기여하기

커뮤니티 레지스트리에 자신의 에이전트 프로필을 기여하려면 agent-catalog 저장소에 풀 리퀘스트를 제출하세요.

문제 해결

프로필 설치 실패

해결 방법: 에이전트 프로필 디렉터리에 대한 쓰기 권한이 있는지 확인하세요. 자세한 내용은 오류 메시지를 확인하세요.

레지스트리 인덱스 로드 실패

해결 방법: 네트워크 연결을 확인하세요. 오프라인인 경우 앱은 사용 가능한 캐시된 데이터를 사용하려고 시도합니다. 일부 소스만 실패하는 경우 Community 탭의 경고 배너에서 소스별 오류 세부 정보를 확인하세요.

사용자 정의 소스 검증 실패

해결 방법: GitHub 저장소가 존재하고 공개되어 있으며 지정된 브랜치의 저장소 루트에 유효한 index.json 파일이 있는지 확인하세요.

설치 후 프로필이 나타나지 않음

해결 방법: 로컬 탭으로 이동하여 새로고침을 클릭하여 로컬 프로필 목록을 새로고침하세요.