사용자 지정 에이전트 구성

이 참조 문서에서는 에 대한 사용자 지정 에이전트자세한 구성 정보를 제공합니다. 만드는 사용자 지정 에이전트방법에 대한 일반적인 내용은 에 대한 사용자 지정 에이전트 만들기 Copilot 클라우드 에이전트을 참조하세요.

YAML 프런트매터 속성

다음 표는 에이전트 프로필와 GitHub.com, 코파일럿 CLI, 그리고 달리 명시되지 않은 경우에 지원되는 IDE에서 구성할 수 있는 속성을 설명합니다. 환경별 동작은 속성 설명에 나와 있습니다. 구성 파일의 이름(빼기 .md 또는 .agent.md)은 가장 낮은 수준의 구성이 우선적으로 적용되도록 수준 간 중복 제거에 사용됩니다.

          사용자 지정 에이전트의 표시 이름입니다. Optional. |

YAML 프런트매터 아래의 Markdown 콘텐츠에서 에이전트의 동작, 전문 지식 및 지침을 정의합니다. 프롬프트는 최대 30,000자일 수 있습니다.

          VS Code 및 기타 IDE의 사용자 지정 에이전트에서 `argument-hint` 및 `handoffs` 속성은 현재 GitHub.com에서 Copilot 클라우드 에이전트에 대해 지원되지 않습니다. 호환성을 보장하기 위해 무시됩니다.

• 파일 구조에 대한 사용자 지정 에이전트 자세한 내용은 VS CodeVS Code의 사용자 지정 에이전트를 VS Code 문서에서 참조하세요.

Tools

이 속성은 사용자 지정 에이전트tools MCP 서버의 도구를 포함하여 에이전트에서 사용할 수 있는 도구를 제어합니다.

          사용자 지정 에이전트 해당 및/또는 리포지토리 설정 모두에서 에이전트 프로필 구성된 MCP 서버 도구에 액세스할 수 있습니다. 리포지토리에서 클라우드 에이전트에 대한 MCP 서버를 구성하는 방법에 대한 자세한 내용은 [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp)을 참조하세요.

다음 방법을 통해 tools을 구성할 수 있습니다.

•         **사용 가능한 모든 도구 사용**: `tools` 속성을 완전히 생략하거나 `tools: ["*"]`를 사용하여 사용 가능한 모든 도구를 활성화할 수 있습니다. 
          에이전트 프로필 및 리포지토리 설정에 구성된 모든 MCP 서버 도구가 포함됩니다.
  

•         **특정 도구 사용**: 특정 도구 이름 또는 별칭 목록(예 `tools: ["read", "edit", "search"]`: 해당 도구만 사용하도록 설정)을 제공합니다. 사용 가능한 도구 별칭은 아래 [의 도구 별칭을 참조하세요](#tool-aliases) .
  

  • 리포지토리에 MCP 서버가 구성된 경우 해당 서버의 특정 도구만 사용할 수 있도록 선택할 수 있습니다 사용자 지정 에이전트. 특정 MCP 서버의 도구 이름 앞에 서버 이름이 접두사로 사용될 수 있고, 그 뒤에 /가 추가됩니다. 예: some-mcp-server/some-tool.
  • 를 사용하여 특정 MCP 서버의 모든 도구를 명시적으로 사용하도록 설정할 수도 있습니다 some-mcp-server/*.
  • 확장의 VS Code 도구는 다음과 같이 azure.some-extension/some-tool확장 이름을 프록시로 사용할 수 있습니다.

•         **모든 도구 사용 안 함**: 빈 목록(`tools: []`)을 사용하여 에이전트에 대한 모든 도구를 사용하지 않도록 설정합니다.
  

인식할 수 없는 모든 도구 이름은 무시되므로 문제 없이 제품별 도구를 지정할 에이전트 프로필 수 있습니다.

도구 별칭

다음 도구 별칭을 사용할 수 있습니다 사용자 지정 에이전트. 모든 별칭은 대/소문자를 구분하지 않습니다.

| 기본 별칭 | 호환되는 별칭 | 클라우드 에이전트 매핑 | 목적 | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | shell, Bash, powershell | 셸 도구: bash 또는 powershell | 운영 체제에 적합한 셸에서 명령을 실행합니다. | | read | Read, NotebookRead | view | 파일 내용을 읽습니다. | | edit | Edit, MultiEdit, , Write, NotebookEdit | 편집 도구: 예: str_replace``str_replace_editor | LLM 편집 허용. 정확한 인수는 다를 수 있습니다. | | search | Grep, Glob | search | 파일에서 파일 또는 텍스트를 검색합니다. | | agent | custom-agent, Task | "사용자 지정 에이전트" 도구 | 작업을 수행하기 위해 다른 사용자 지정 에이전트 호출을 허용합니다. | | web | WebSearch, WebFetch | 현재는 적용할 수 없습니다 클라우드 에이전트. | URL에서 콘텐츠를 가져오고 웹 검색을 수행할 수 있습니다. | | todo | TodoWrite | 현재는 적용할 수 없습니다 클라우드 에이전트. | 구조화된 작업 목록을 만들고 관리합니다. 현재는 클라우드 에이전트 에서 지원되지 않지만, VS Code에서 지원된다. |

"즉시 사용 가능한" MCP 서버의 도구 이름

다음 MCP 서버는 Copilot 클라우드 에이전트에서 기본적으로 사용할 수 있으며, 네임스페이스를 사용하여 참조할 수 있습니다.

          `github/*`에는 모든 항목이 포함되어 있거나, MCP 서버 설명서에서 값 `github/<tool name>`를 참조하려면 `<tool name>`을 참고하십시오. |

| playwright | 모든 극작가 도구는 기본적으로 사용할 수 있지만 서버는 localhost에만 액세스하도록 구성됩니다. playwright/*에는 모든 항목이 포함되어 있거나, MCP 서버 설명서에서 값 playwright/<tool name>를 참조하려면 <tool name>을 참고하십시오. 기본적으로 액세스 권한이 있는 토큰은 소스 코드 리포지토리로 범위가 지정됩니다. |

MCP 서버 구성 세부 정보

다음 샘플 에이전트 프로필 에서는 MCP 서버와 비밀이 구성된 에이전트를 보여줍니다. 또한 YAML 프런트매터의 속성에서 MCP 서버의 tools 도구 하나만 사용하도록 설정되었습니다.

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Prompt with suggestions for behavior and output

의 mcp-servers 속성은 에이전트 프로필에서 MCP 서버 구성을 위해 사용되는 JSON 구성 형식에 대한 YAML 표현입니다. Copilot 클라우드 에이전트

대부분의 하위 속성은 JSON 표현과 동일합니다. 다음 섹션에서는 Copilot 클라우드 에이전트 에서 사용자 지정 에이전트 관련된 MCP 구성의 초기 구현에서의 변경 사항을 설명합니다. JSON 구성 형식에 대한 자세한 내용은 MCP(모델 컨텍스트 프로토콜)를 사용하여 GitHub Copilot 클라우드 에이전트 확장을 참조하세요.

MCP 서버 유형

호환성을 위해 Claude Code의 stdio 유형과 VS Code이 클라우드 에이전트의 local 유형에 매핑됩니다.

MCP 서버 환경 변수 및 비밀

          사용자 지정 에이전트 MCP 구성은 기존 리포지토리 수준 MCP 구성과 동일한 환경 변수 및 비밀 대체 기능을 지원합니다. 리포지토리 수준 구성과 마찬가지로 비밀 및 변수는 리포지토리 설정의 "부조종사" 환경에서 가져올 수 있습니다. 이러한 값을 참조하는 구문은 GitHub Actions 및 Claude Code에서 사용되는 일반적인 패턴을 지원하도록 확장되었습니다.

리포지토리 수준 MCP JSON 구성과 사용자 지정 에이전트 YAML 구성 모두 다음 구문 패턴을 지원합니다.

•         `$COPILOT_MCP_ENV_VAR_VALUE` - 환경 변수 및 헤더
  

•         `${COPILOT_MCP_ENV_VAR_VALUE}` - 환경 변수 및 헤더(Claude Code 구문)
  

•         `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - 환경 변수 및 헤더(기본값)
  

YAML 구성은 사용자 지정 에이전트 다음과 같은 추가 구문 패턴을 지원합니다.

•         `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - 환경 변수 및 헤더
  

•         `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - 환경 변수 및 헤더
  

예제 에이전트 프로필 구성

다음 예제에서는 테스트를 작성하거나 프로젝트 구현을 계획하는 일반적인 작업에 대해 에이전트 프로필가 어떻게 나타날 수 있는지를 보여줍니다. 추가 영감을 얻으려면 맞춤화 라이브러리의 사용자 지정 에이전트 예제를 참조하세요. awesome-copilot 커뮤니티 컬렉션에서 보다 구체적인 예제를 찾을 수 있습니다.

테스트 전문가

이 예제에서는 속성을 생략 tools 하여 모든 도구를 사용하도록 설정합니다.

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

구현 플래너

이 예제에서는 도구의 하위 집합만 사용하도록 설정합니다.

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

처리 중 사용자 지정 에이전트

          사용자 지정 에이전트 이름

명명 충돌이 있을 경우 가장 낮은 수준의 구성이 상위 수준 구성을 우선합니다. 즉, 리포지토리 수준 에이전트가 조직 수준 에이전트보다 우선시되고, 조직 수준 에이전트가 엔터프라이즈 수준 에이전트를 무효화합니다.

버전 관리

          사용자 지정 에이전트 버전 관리는 에이전트 프로필 파일의 Git 커밋 SHA를 기반으로 합니다. 이렇게 하면 필요에 따라 다른 버전의 사용자 지정 에이전트 분기 또는 태그를 만들 수 있습니다. 
          사용자 지정 에이전트를 작업에 할당하면, 사용자 지정 에이전트는 해당 리포지토리 및 분기에 대한 최신 버전 에이전트 프로필를 사용하여 인스턴스화됩니다. 에이전트가 풀 리퀘스트를 생성할 때 풀 리퀘스트 내의 사용자 지정 에이전트 상호 작용은 일관성을 위해 동일한 버전을 사용합니다.

도구 가공

이 tools 목록은 MCP 서버에서 기본 제공 또는 원본으로 사용하든 에이전트에서 사용할 수 있는 도구 집합을 필터링합니다. 도구를 에이전트 프로필에서 구성할 때 동작은 설정에 따라 결정됩니다.

• 도구가 지정되지 않은 경우 사용 가능한 모든 도구가 사용하도록 설정됩니다.
• 빈 도구 목록(tools: [])은 모든 도구를 사용하지 않도록 설정합니다.
• 특정 목록(tools: [...])을 사용하면 이러한 도구만 사용할 수 있습니다.

MCP 서버 구성

MCP 서버 구성의 경우 적절한 재정의 동작을 보장하는 특정 처리 순서가 있습니다. 즉, MCP와 같은 GitHub 기본 MCP 구성이 먼저 처리되고 MCP 사용자 지정 에이전트 구성과 마지막으로 리포지토리 설정을 통해 지정된 MCP 구성이 수행됩니다. 이렇게 하면 각 수준이 이전 수준의 설정을 적절하게 재정의할 수 있습니다.

추가 읽기

•         [AUTOTITLE](/copilot/how-tos/copilot-cli)
  

•         [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)