GitHub Copilot 가이드: 커스텀 에이전트와 서브에이전트 오케스트레이션

InYourLeague 리서치 · 2026-09-05

핵심 답변

GitHub Copilot은 Copilot SDK 및 GitHub Copilot CLI를 통해 커스텀 에이전트와 서브에이전트 오케스트레이션을 지원하며, 개발자가 범위가 제한된 도구, 전용 시스템 프롬프트, 격리된 실행 컨텍스트를 갖춘 특화 에이전트를 정의할 수 있도록 합니다. 런타임은 의도 추론 또는 명시적 선택을 기반으로 임시 서브에이전트에 작업을 위임하고, 메인 컨텍스트를 깔끔하게 유지하면서 수명 주기 이벤트를 상위 세션으로 스트리밍합니다. 이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다.

핵심 정보 한눈에 보기

오류 유형과 검증

자주 묻는 질문

GitHub Copilot에서 서브에이전트 오케스트레이션을 사용하는 주요 아키텍처적 목적은 무엇인가요?

서브에이전트는 독립된 임시 컨텍스트 창에서 작업을 수행합니다. 이러한 구조는 특화된 지침과 도구 실행 결과가 상위 세션의 컨텍스트 창을 어지럽히지 않도록 방지하여, 메인 에이전트가 상위 수준의 계획 및 워크플로 조정에 집중할 수 있도록 지원합니다. 자세한 내용은 Copilot SDK 커스텀 에이전트 가이드를 참조하세요.

서브에이전트의 컨텍스트 격리가 파일 시스템 보안 샌드박스를 보장하나요?

아닙니다. 서브에이전트의 컨텍스트 격리와 허용된 도구 목록 제한은 대화 컨텍스트와 도구 호출 범위를 분리할 뿐이며, 파일 시스템 보안 샌드박스 경계를 형성하지는 않습니다. 컨텍스트 격리 자체를 보안 경계로 간주해서는 안 되며 권한 콜백 등을 통한 명시적 제어가 필요합니다.

CLI의 저장소 디렉터리와 사용자 디렉터리에 동일한 이름의 에이전트가 있으면 어느 것이 우선하나요?

사용자 홈 디렉터리(~/.copilot/agents/)와 저장소 디렉터리(.github/agents/)에 동일한 이름을 가진 커스텀 에이전트가 존재하는 경우, GitHub Copilot CLI는 사용자 홈 디렉터리의 에이전트 정의를 저장소 정의보다 우선하여 적용합니다. 상세 내용은 Copilot CLI 커스텀 에이전트 가이드에 기술되어 있습니다.

Copilot SDK에서 서브에이전트는 상위 세션에 설정된 스킬을 자동으로 상속받나요?

아닙니다. 서브에이전트는 상위 세션의 스킬을 상속받지 않습니다. 스킬은 에이전트별로 명시적으로 선택(opt-in)해야 하며, 에이전트 정의의 skills 배열에 사전 로드할 스킬 이름을 명시해야 세션의 skillDirectories로부터 시작 시점에 즉시 주입됩니다.

이 문서 항목에서 제품 고유의 선택 가능한 기본 모델 ID로 공식 검증된 것은 무엇인가요?

이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. Copilot SDK 예시 코드에 나타나는 gpt-5.4와 같은 식별자는 세션 설정 방식을 보여주는 예시일 뿐이며, 고정된 기본 모델이나 지원 모델 전체 목록으로 검증된 것이 아닙니다.

출처와 확인 날짜

• 공식 출처
• 공식 출처
• 최종 확인일: 2026-09-05

상세 가이드

GitHub Copilot 커스텀 에이전트의 아키텍처 개요

GitHub Copilot은 단일 세션 내에서 Copilot 런타임이 서브에이전트로 오케스트레이션할 수 있는 커스텀 에이전트 정의 기능을 제공합니다. 커스텀 에이전트는 Copilot SDK 세션에 연결되거나 GitHub Copilot CLI에서 에이전트 프로필로 로드되는 경량 에이전트 구성입니다. 사용자가 요청을 전달하면 런타임은 에이전트의 설명과 작업 의도를 분석하여 자체 시스템 프롬프트, 도구 제한, 선택적 MCP 서버를 갖춘 격리된 서브에이전트 컨텍스트를 자동으로 생성합니다. 이러한 격리된 실행 창은 세부적인 작업 데이터가 상위 세션의 컨텍스트 창을 어지럽히는 것을 방지하며, 메인 에이전트가 상위 수준의 계획 및 워크플로 조정에 집중할 수 있도록 지원합니다.

작업 디렉터리, 도구 허용 목록, 또는 대화 컨텍스트 격리 자체는 파일 시스템 샌드박스나 보안 경계를 입증하지 않습니다. 공식 문서는 컨텍스트 분리와 도구 접근 제한을 명시하고 있지만, 이러한 동작이 별도의 파일 시스템 보안 샌드박스 경계를 보증하는 것은 아닙니다. 또한 이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. SDK 예제에 등장하는 모델 식별자(예: 세션 설정 예시인 gpt-5.4)는 설정 옵션을 보여주는 예시일 뿐이며 고정된 기본값이나 전체 지원 모델 목록을 의미하지 않습니다.

커스텀 에이전트 구성 요소 참조

Copilot SDK에서는 세션을 초기화할 때 customAgents 속성으로 에이전트를 전달하거나 agent 속성을 통해 사전 선택할 수 있습니다. GitHub Copilot CLI에서는 .agent.md 확장자를 가진 마크다운 파일로 저장되며, 저장소 수준(.github/agents/) 또는 사용자 홈 디렉터리(~/.copilot/agents/)에 배치됩니다. 두 위치에 동일한 이름의 에이전트가 존재하는 경우 사용자 홈 디렉터리의 설정이 저장소 설정보다 우선 적용됩니다.

단계별 구현 절차

1. 에이전트 프로필 정의: Copilot SDK에서는 customAgents 배열 내에 name, description, prompt, 명시적 tools(예: ["grep", "glob", "view"])를 선언합니다. CLI에서는 /agent를 입력하고 프로젝트 또는 사용자 범위를 선택한 후, 수동 작성 또는 대화형 Copilot 안내를 통해 <name>.agent.md 파일을 생성합니다.
2. 도구 및 컨텍스트 범위 구성: 읽기 전용 작업의 경우 쓰기/수정 도구를 제외하고, 외부 연동이 필요한 경우 MCP 서버를 연결하며, 세션 수준 skillDirectories에서 사전 주입할 skills를 지정합니다.
3. 세션 사전 선택 또는 추론 활성화: SDK 세션 구성에서 agent: "<name>"을 설정하여 세션 시작과 동시에 활성화하거나(이는 session.rpc.agent.select() 호출과 동일), infer: true를 유지하여 런타임 자동 라우팅을 허용합니다.
4. 서브에이전트 위임 실행: 상위 세션에 프롬프트를 전송하면 런타임이 의도를 분석하고, 일치하는 에이전트를 선택하여 격리된 서브에이전트 환경을 실행하며, 수명 주기 이벤트(subagent.started, subagent.completed)를 부모 세션에 전달하고 결과를 통합합니다.
5. 핸드오프 검토 수행: CLI 대화형 생성 과정에서 제공되는 Review content 옵션을 사용하여 생성된 에이전트 프로필을 기본 편집기에서 검토 및 수정한 뒤 등록을 완료합니다.

배포 전 체크리스트

• 에이전트 식별자 이름이 소문자와 하이픈으로만 구성되어 일관성을 유지하는가?
• 런타임 추론 매칭을 돕기 위해 전문 영역, 제약 조건 및 트리거 단어(예: seccheck)가 설명에 구체적으로 명시되었는가?
• 불필요하거나 위험한 도구 접근을 방지하기 위해 도구 허용 목록(tools)을 제한적으로 정의했는가?
• 서브에이전트는 상위 세션의 스킬을 상속받지 않으므로 필요한 스킬을 skills 배열에 명시적으로 추가했는가?
• ~/.copilot/agents/와 .github/agents/ 간의 이름 충돌로 인해 저장소 수준 설정이 의도치 않게 무시되지 않는지 확인했는가?
• 상위 세션으로 스트리밍되는 수명 주기 이벤트를 모니터링하여 서브에이전트 진행 상황과 핸드오프 결과를 검토할 수 있는가?

추가 정보는 Copilot SDK 커스텀 에이전트 공식 문서 및 Copilot CLI 커스텀 에이전트 생성 가이드에서 확인할 수 있습니다.