워크스페이스 서브에이전트
GitLab v19.5Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
워크스페이스 서브에이전트는 프로젝트 리포지터리에 Markdown 파일로 정의하는 전문 에이전트입니다. Developer Flow는 서브에이전트의 description을 기준으로 작업을 서브에이전트에 위임할지 결정합니다.
워크스페이스 서브에이전트는 프로젝트 리포지터리에 Markdown 파일로 정의하는 전문 에이전트입니다. 이 기능은 GitLab UI와 GitLab Duo CLI 모두에서 Developer Flow에만 사용할 수 있습니다.
Developer Flow는 서브에이전트의 description을 기준으로 작업을 서브에이전트에 위임할지 결정합니다.
Developer Flow에 서브에이전트를 이름으로 지정해 사용하도록 요청할 수도 있습니다.
예를 들어 이슈 또는 머지 리퀘스트 댓글에서
Developer Flow를 멘션하고
서브에이전트 이름을 지정합니다.
@duo-developer-<namespace> delegate the review of these changes to the reviewer subagent.
<namespace>를 GitLab 네임스페이스 경로로 바꿉니다.
서브에이전트를 이름으로 지정하면 위임될 가능성이 높아지지만, 작업을 위임할지는 Developer Flow가 결정합니다.
워크스페이스 서브에이전트는 다른 GitLab Duo Agent Platform 기능과 마찬가지로 GitLab Credits를 사용합니다.
워크스페이스 서브에이전트를 사용하는 경우#
워크스페이스 서브에이전트는 Developer Flow와 컨텍스트를 공유하지 않습니다. Developer Flow에 필요하지 않은 세부 정보가 작업에서 생기는 경우 서브에이전트를 사용하면, 그 세부 정보가 Developer Flow의 주 컨텍스트에 들어가지 않습니다.
예를 들어 run_command 및 edit_file 도구를 가진 린터 서브에이전트는 프로젝트 린터를 실행하고
린트 오류를 수정할 수 있습니다.
린터 출력과 개별 수정 내용은 서브에이전트의 대화에 남습니다.
Developer Flow는 수정 내용 요약과 같은 결과만 받습니다.
서브에이전트의 프롬프트가 요청하면, 결과에 다음에 피해야 할 일반적인 린터 문제를 함께 나열할 수도 있습니다.
그 밖의 예로는 변경 사항 검토, 접근 방식 조사, 보안과 같은 특정 영역 점검이 있습니다.
Developer Flow가 작업을 서브에이전트에 위임하면 서브에이전트는 다음과 같이 동작합니다.
- Developer Flow가 전달한 작업으로 시작하는 자체 대화에서 작업합니다. 결과만 Developer Flow로 돌아갑니다.
- Developer Flow의 지침 대신 자체 프롬프트를 따릅니다.
tools필드에 나열된 도구만 사용할 수 있습니다. 예를 들어read_file과grep만 가진 검토 서브에이전트는 파일을 변경할 수 없습니다.
다음 표는 워크스페이스 서브에이전트를 GitLab Duo Developer를 사용자 지정하는 다른 방법과 비교합니다.
| Customization | What it does | Use it when |
|---|---|---|
AGENTS.md |
구조, 코딩 컨벤션, 빌드 및 테스트 지침과 같은 프로젝트 컨텍스트와 컨벤션을 작업을 수행하는 에이전트의 컨텍스트에 추가합니다. 리포지터리의 모든 작업에 적용됩니다. | 리포지터리의 모든 작업이 같은 컨벤션을 따르도록 하려는 경우. |
| Agent Skills | 작업이 스킬 설명과 일치할 때 에이전트가 자동으로 불러오는 지식이나 워크플로를 제공합니다. 스킬을 불러온 에이전트가 같은 대화에서 같은 도구로 직접 작업을 수행합니다. | 작업이 일치할 때 에이전트가 특정 워크플로를 따르거나 특정 지식을 사용하도록 하려는 경우. |
| 워크스페이스 서브에이전트 | 자체 프롬프트와 도구를 가진 별도의 에이전트에서 작업을 실행하고 결과만 반환합니다. | 린터 출력과 같은 작업 세부 정보를 Developer Flow의 컨텍스트에 넣고 싶지 않거나, 자체 지침과 제한된 도구를 가진 별도의 에이전트가 필요한 경우. |
서브에이전트 정의#
각 워크스페이스 서브에이전트는 리포지터리 루트의 .agents/agents/ 디렉터리에 있는 Markdown 파일입니다.
파일은 --- 줄 사이의 YAML 프런트 매터로 시작하고 그 뒤에 프롬프트가 옵니다.
프롬프트는 파일의 Markdown 본문입니다.
다음 표는 프런트 매터 필드와 프롬프트를 설명합니다.
| Field | Required | Description |
|---|---|---|
name |
아니요 | Developer Flow가 서브에이전트를 식별하는 데 사용하는 이름입니다. 기본값은 .md 확장자를 뺀 파일 이름입니다. 프로젝트 내에서 고유해야 합니다. 최대 64자입니다. |
description |
예 | 서브에이전트가 하는 일입니다. Developer Flow는 이 내용을 기준으로 서브에이전트에 위임할 시점을 결정합니다. 최대 1,024자입니다. |
tools |
아니요 | 서브에이전트가 사용할 수 있는 도구를 쉼표로 구분한 목록 또는 YAML 목록으로 지정합니다. 사용 가능한 도구 목록의 도구 이름을 사용합니다. tools를 생략하면 서브에이전트는 어떤 도구도 사용할 수 없습니다. 전달받은 정보만으로 작업을 추론할 수 있습니다. |
| 프롬프트 | 예 | 프런트 매터 뒤에 오는 서브에이전트의 지침입니다. 최대 10,000자입니다. |
파일 요구 사항#
워크스페이스 서브에이전트는 파일이 다음 요구 사항을 모두 충족할 때만 사용됩니다.
- 파일이
.agents/agents/디렉터리 바로 아래에 있습니다. 하위 디렉터리의 파일은 무시됩니다. - 파일 이름이
.md로 끝납니다. - 파일이 UTF-8 텍스트입니다.
- 파일이
---줄 사이의 YAML 프런트 매터로 시작합니다. - 프런트 매터에
description이 있습니다. - 프런트 매터 뒤에 프롬프트가 있습니다.
- 파일 크기가 64KB 이하입니다.
파일이 이 요구 사항을 충족하지 않으면 해당 파일은 건너뜁니다.
개수 및 크기 제한#
다음 제한은 프로젝트의 모든 서브에이전트에 적용됩니다.
| Limit | Sessions in GitLab | GitLab Duo CLI sessions |
|---|---|---|
| 서브에이전트 수 | 파일 이름 순으로 처음 10개의 .md 파일을 읽습니다. |
최대 10개의 서브에이전트. 요구 사항을 충족하는 모든 서브에이전트가 전송됩니다. |
| 전체 크기 | 최대 112KB. 크기에는 각 서브에이전트의 이름, 설명, 도구, 프롬프트가 포함됩니다. 합계가 더 크면 일부 서브에이전트는 Developer Flow에서 사용할 수 없습니다. | 최대 gRPC 메시지 크기로 제한됩니다. |
세션 시작을 막는 오류#
다음 경우 Developer Flow 세션을 시작하지 못합니다.
- 두 서브에이전트의 이름이 같은 경우.
- 서브에이전트가 Developer Flow에서 사용할 수 없는 도구를 나열한 경우.
name,description또는 프롬프트가 최대 길이를 넘는 경우.- GitLab Duo CLI 세션에서 요구 사항을 충족하는 서브에이전트가 10개를 넘는 경우.
워크스페이스 서브에이전트 생성#
Developer Flow가 작업을 위임할 수 있는 전문 에이전트를 만들려면 워크스페이스 서브에이전트를 생성합니다.
사전 요구 사항:
- 베타 및 실험 기능을 켭니다.
이 설정은 단일 프로젝트에 대해서는 켤 수 없습니다.
- GitLab.com에서는 Owner 권한이 있는 사용자가 최상위 그룹에서 이 설정을 변경합니다. 최상위 그룹의 모든 하위 그룹과 프로젝트가 이 설정을 상속합니다.
- GitLab Self-Managed 및 GitLab Dedicated에서는 관리자가 인스턴스에 대해 이 설정을 변경합니다. 인스턴스의 모든 그룹과 프로젝트가 이 설정을 상속합니다.
- Developer Flow 사전 요구 사항을 충족합니다.
- 서브에이전트를 머지하기 전에 테스트하려면 GitLab Duo CLI 9.21.0 이상을 설치합니다.
워크스페이스 서브에이전트를 생성하려면:
-
프로젝트의 브랜치에서
.agents/agents/디렉터리에 Markdown 파일을 생성합니다. 예:.agents/agents/reviewer.md. -
프런트 매터와 프롬프트를 추가합니다. 예:
--- name: reviewer description: Reviews code changes and reports a short list of findings. tools: read_file, grep --- You are a meticulous code reviewer. When delegated a task, read the files it names and report a short list of findings. Do not modify any file. -
머지하기 전에 서브에이전트를 테스트합니다. GitLab의 세션은 기본 브랜치에서만 서브에이전트를 읽지만, GitLab Duo CLI는 로컬 작업 디렉터리에서 파일을 읽습니다.
- 프로젝트의 루트 디렉터리에서 GitLab Duo CLI로 Developer Flow 세션을 시작합니다.
- Developer Flow에 서브에이전트에 작업을 위임하도록 요청하거나, 서브에이전트의 설명과 일치하는 작업을 줍니다.
- 세션에
Delegated to workspace/agents/<subagent-name>이 표시되고 그 뒤에 서브에이전트의 결과가 나오는지 확인합니다. 서브에이전트가 수행한 작업을 보려면 Control+T를 누릅니다.
-
파일을 기본 브랜치에 커밋하거나 머지합니다.
-
GitLab에서 새 Developer Flow 세션을 시작하여 서브에이전트를 사용합니다. 결과를 보려면 Developer Flow가 게시하는 링크에서 세션을 열거나, 왼쪽 사이드바에서 AI > Sessions를 선택합니다. Developer Flow가 작업을 위임하면 세션에 Delegated to subagent가 표시되고, 그 뒤에 서브에이전트의 결과와 함께 Returned to agent가 표시됩니다.
GitLab에서는 새 세션만 서브에이전트 구성의 변경 사항을 반영합니다. 기존 세션은 다시 시작하더라도 변경 사항을 반영하지 않습니다.
프로젝트에서 워크스페이스 서브에이전트 차단#
단일 프로젝트에 대해서는 워크스페이스 서브에이전트를 끌 수 없습니다. 서브에이전트 정의가 리포지터리에 들어가지 않도록 하려면 다음 방법 중 하나 또는 둘 다를 사용합니다.
- 파일이 실수로 커밋되지 않도록 프로젝트의
.gitignore파일에.agents/agents/를 추가합니다. - 정규식
^\.agents\/agents\/로 파일 이름으로 파일을 금지하는 푸시 규칙을 생성합니다. 그러면 GitLab이 해당 파일이 포함된 푸시를 거부합니다.
관련 주제#
문제 해결#
워크스페이스 서브에이전트가 예상대로 동작하지 않는 경우:
- 베타 및 실험 기능이 켜져 있는지 확인합니다.
- 파일 요구 사항에 맞는지 파일을 확인합니다. 요구 사항을 충족하지 않는 파일은 건너뜁니다.
- GitLab 세션의 경우 파일이 기본 브랜치에 있는지 확인합니다.
- 세션을 시작하지 못하면 세션 시작을 막는 오류를 확인합니다.