GitLab Duo 에이전트 플랫폼 개발을 위한 에이전트 상호작용 패턴
이 가이드는 GitLab 내 에이전트 및 플로우를 위한 상호작용 패턴과 규칙을 설명합니다. 이 가이드는 GitLab이 관리하는 에이전트와 플로우를 대상으로 합니다. 동작 패턴: 플로우 또는 에이전트가 이슈 또는 MR 작업을 시작할 때, 활동을 알리기 위해 초기 코멘트를 작성합니다.
이 가이드는 GitLab 내 에이전트 및 플로우를 위한 상호작용 패턴과 규칙을 설명합니다. 이 패턴들은 인프라 부하를 관리하고 높은 수준의 사용자 경험을 유지하면서 일관되고 사용자 친화적인 동작을 보장합니다.
이 가이드는 GitLab이 관리하는 에이전트와 플로우를 대상으로 합니다. AI 카탈로그에서 생성된 커스텀 에이전트에도 이 패턴이 적용되어야 합니다.
핵심 사용자 경험 원칙#
- 알림 소음 최소화: 에이전트는 사용자에게 알림과 코멘트로 부담을 주지 않으면서 필요한 업데이트를 제공해야 합니다.
- 투명성 유지: 사용자는 에이전트의 진행 상황을 추적하고 어떤 조치가 취해지고 있는지 이해할 수 있어야 합니다.
- 인프라 제약 존중: 에이전트 동작은 확장성을 고려하여 설계되어야 하며, 과도한 데이터베이스 부하를 발생시키는 패턴을 피해야 합니다.
- 인간 감독 허용: 사용자는 에이전트 작업을 검토하고, 승인하거나, 개입하기 위한 명확한 진입점이 필요합니다.
상호작용 패턴#
코멘트 관리#
이슈 또는 MR에 최초 코멘트: 초기 코멘트 작성#
동작 패턴: 플로우 또는 에이전트가 이슈 또는 MR 작업을 시작할 때, 활동을 알리기 위해 초기 코멘트를 작성합니다.
- 에이전트 활동을 해당 항목의 모든 협력자에게 표시합니다
- 세션 UI를 넘어서는 영구적인 기록을 제공합니다
- 진행 상황 업데이트로 갱신할 수 있는 코멘트를 만듭니다
리소스:
- To do: 예시 템플릿 추가
- To do: 프롬프트에 예시 방법 추가
- To do: 스크린샷(디자인) 추가
세션 진행 중 업데이트 추가: 동일한 코멘트에서 작업#
동작 패턴: 에이전트가 작업을 활발히 진행하는 동안, 새 코멘트를 여러 개 만들기보다 하나의 코멘트를 업데이트해야 합니다.
- 데이터베이스 부하와 알림 스팸을 줄입니다
- 에이전트 진행 상황의 명확하고 통합된 보기를 제공합니다
- AI 생성 콘텐츠로 이슈와 MR이 복잡해지는 것을 방지합니다
리소스:
- To do: 예시 템플릿 추가
- To do: 프롬프트에 예시 방법 추가
- To do: 스크린샷(디자인) 추가
플로우 완료 또는 검토 필요 시 업데이트 추가: 새 코멘트 추가#
동작 패턴: 에이전트가 작업을 완료하거나 인간 검토 및 후속 조치가 필요한 경우, 요약과 다음 단계가 포함된 새 코멘트를 작성하고 관련 사용자를 언급합니다.
- 언급이 포함된 새 코멘트는 사용자에게 할 일이나 이메일을 생성하여 익숙한 알림 패턴으로 참여를 유도합니다
- "에이전트 작업 중"에서 "인간 조치 필요"로의 명확한 전환을 신호합니다
- 업데이트된 내용에서 중요한 이정표가 사라지지 않도록 보장합니다
리소스:
- To do: 예시 템플릿 추가
- To do: 프롬프트에 예시 방법 추가
- To do: 스크린샷(디자인) 추가
플로우 완료 시: 항상 최종 요약 제공#
동작 패턴: 플로우가 완료되면(성공 또는 오류와 함께), 항상 작업 항목에 요약 코멘트를 게시합니다.
리소스:
- To do: 성공과 실패에 대한 예시 템플릿 추가
- To do: 프롬프트에 예시 방법 추가
- To do: 성공과 실패에 대한 스크린샷(디자인) 추가
사용자 언급#
동작 패턴: 에이전트는 불필요한 소음을 만들지 않도록 주의하면서 협력하는 팀원들에게 중요한 정보를 전달하는 방식으로 인간처럼 언급을 사용합니다.
- 초기 코멘트에서 플로우를 시작한 사용자를 언급합니다
- 검토 또는 승인 요청 시 응답이 필요한 사용자를 언급합니다
- 진행 중 업데이트에서는 언급을 피합니다
근거:
- 에이전트가 시작했음을 트리거한 사용자에게 알립니다
- 인간 조치가 필요할 때만 할 일을 생성합니다
- 진행 중 업데이트로 인한 알림 피로를 방지합니다
AI 패널의 세션 탭 사용#
동작 패턴: 에이전트는 상세하고 실시간 진행 추적을 위해 세션 섹션을 활용하고, 코멘트는 이정표 알림과 요약을 위해 사용해야 합니다. 사용자가 모든 플로우를 위해 세션 탭을 들어갈 필요가 없어야 합니다. 세션 탭은 문제 해결 및 기타 심층 분석 활동에 사용되며, 세션과 관련된 작업 항목이나 MR을 더 이상 보고 있지 않을 때 세션을 비동기적으로 관리하는 데 사용됩니다.
세션 탭에 표시할 콘텐츠:
- 상세한 단계별 진행 상황
- 도구 호출 및 응답
- 추론 및 의사결정 과정
- 실시간 상태 업데이트
작업 항목 및 MR 코멘트에 표시할 콘텐츠:
- 에이전트 작업 시작
- 주요 이정표 업데이트 (필요한 경우)
- 인간 개입이 필요한 후속 요청
- 최종 요약
모범 사례 요약#
개발을 위한 지침#
- 코멘트 ID 사용: 초기 코멘트 ID를 저장하고 새 코멘트를 만들기보다 업데이트합니다
- 타임스탬프 업데이트: 진행 중 업데이트에 항상 타임스탬프를 포함합니다
- 명확한 상태 전환: "작업 중"에서 "검토 필요"로 전환할 때 명확히 표시합니다
- 우아한 실패 처리: 오류 발생 시에도 항상 요약 코멘트를 게시합니다
- 세션 링크: 더 많은 정보를 원하는 사용자를 위해 전체 세션 세부 정보 링크를 포함합니다
프롬프트 엔지니어링을 위한 지침#
단일 에이전트의 프롬프트에서 이것이 어떻게 보일 수 있는지 예시입니다:
COMMENT BEHAVIOR:
* Create ONE initial status comment when you start
* Update that same comment with your progress
* Create a NEW comment when you complete or need review
* Always mention users in completion/review comments
* Never mention users in progress updates
FINAL SUMMARY:
* Always post a final summary when done
* Include what you did, results, and next steps
* Link to the full session details
인프라 고려사항을 위한 지침#
이 패턴은 다음을 통해 부하 관리에 도움을 줍니다:
- 업데이트 대 생성: 데이터베이스 쓰기 및 알림 양을 줄입니다
- 통합 상태: 활성 세션당 많은 코멘트 대신 하나의 코멘트
- 선택적 언급: 의미 있는 순간에만 할 일 항목 생성을 줄입니다
- 세부 정보를 위한 세션 UI: 상세 로그를 기본 작업 항목에서 제외합니다
기타 고려사항#
에이전트 플랫폼이 발전함에 따라 다음 사항을 해결해야 할 수 있습니다:
- 접힐 수 있는 진행 상황: 요약을 유지하면서 상세 진행 상황을 숨기는 UI 패턴
- 멀티 에이전트 조율: 여러 에이전트가 동일한 항목에서 작업할 때 에이전트 간의 소통 방법
- 사용자 선호도: 사용자가 알림 수준을 커스터마이즈할 수 있도록 허용
- 향상된 세션 링크: 코멘트에서 세션 세부 정보를 더 쉽게 찾을 수 있도록 만들기
- 아직 생각하지 못한 많은 것들.
이 패턴을 확장하거나 새로운 패턴을 도입하는 데 도움이 필요하면 제품 디자인 팀과 에이전트 파운데이션 팀에 연락하여, 함께 새로운 패턴을 설계하고 향후 사용을 위해 이 문서에 추가할 수 있습니다.