서브 에이전트 (실험적 기능)

서브 에이전트는 기본 Gemini CLI 세션 내에서 작동하는 전문 에이전트입니다. 이들은 메인 에이전트의 컨텍스트나 도구 모음을 복잡하게 만들지 않고 깊이 있는 코드베이스 분석, 문서 조회 또는 도메인별 추론과 같은 구체적이고 복잡한 작업을 처리하도록 설계되었습니다.

참고: 서브 에이전트는 현재 실험적인 기능입니다.

사용자 지정 서브 에이전트를 사용하려면 settings.json에서 명시적으로 활성화해야 합니다:

{
  "experimental": { "enableAgents": true }
}

경고: 서브 에이전트는 현재 "YOLO 모드"에서 작동합니다. 즉, 각 단계에 대한 개별 사용자 확인 없이 도구를 실행할 수 있습니다. run_shell_command 또는 write_file과 같은 강력한 도구를 사용하여 에이전트를 정의할 때는 주의하십시오.

서브 에이전트란 무엇인가요?

서브 에이전트는 메인 Gemini 에이전트가 특정 작업을 위해 고용할 수 있는 "전문가"입니다.

• 집중된 컨텍스트: 각 서브 에이전트는 고유한 시스템 프롬프트와 페르소나를 가집니다.
• 전문화된 도구: 서브 에이전트는 제한되거나 전문화된 도구 세트를 가질 수 있습니다.
• 독립적인 컨텍스트 창: 서브 에이전트와의 상호 작용은 별도의 컨텍스트 루프에서 발생하여 메인 대화 기록의 토큰을 절약합니다.

서브 에이전트는 동일한 이름의 도구로 메인 에이전트에 노출됩니다. 메인 에이전트가 도구를 호출하면 작업이 서브 에이전트에게 위임됩니다. 서브 에이전트가 작업을 완료하면 결과를 메인 에이전트에게 다시 보고합니다.

내장 서브 에이전트

Gemini CLI는 다음과 같은 기본 서브 에이전트를 제공합니다:

코드베이스 조사자 (Codebase Investigator)

• 이름: codebase_investigator
• 목적: 코드베이스를 분석하고, 리버스 엔지니어링하며, 복잡한 종속성을 이해합니다.
• 사용 시기: "인증 시스템은 어떻게 작동하나요?", "AgentRegistry 클래스의 종속성을 맵으로 만들어주세요."
• 구성: 기본적으로 활성화되어 있습니다. settings.json에서 구성할 수 있습니다. 예(특정 모델 강제):

  {
    "experimental": {
      "codebaseInvestigatorSettings": {
        "enabled": true,
        "maxNumTurns": 20,
        "model": "gemini-2.5-pro"
      }
    }
  }

CLI 도움말 에이전트 (CLI Help Agent)

• 이름: cli_help
• 목적: Gemini CLI 자체, 명령, 구성 및 문서에 대한 전문 지식을 얻습니다.
• 사용 시기: "프록시는 어떻게 구성하나요?", "/rewind 명령은 무엇을 하나요?"
• 구성: 기본적으로 활성화되어 있습니다.

일반 에이전트 (Generalist Agent)

• 이름: generalist_agent
• 목적: 작업을 적절한 전문 서브 에이전트에게 라우팅합니다.
• 사용 시기: 라우팅을 위해 메인 에이전트가 암시적으로 사용합니다. 사용자가 직접 호출하지 않습니다.
• 구성: 기본적으로 활성화되어 있습니다. 특정 구성 옵션은 없습니다.

사용자 지정 서브 에이전트 만들기

자체 서브 에이전트를 만들어 특정 워크플로를 자동화하거나 특정 페르소나를 적용할 수 있습니다. 사용자 지정 서브 에이전트를 사용하려면 settings.json에서 활성화해야 합니다:

{
  "experimental": {
    "enableAgents": true
  }
}

에이전트 정의 파일

사용자 지정 에이전트는 YAML frontmatter가 있는 Markdown 파일(.md)로 정의됩니다. 다음 위치에 배치할 수 있습니다:

1. 프로젝트 수준: .gemini/agents/*.md (팀과 공유)
2. 사용자 수준: ~/.gemini/agents/*.md (개인 에이전트)

파일 형식

파일은 반드시 삼중 대시 ---로 묶인 YAML frontmatter로 시작해야 합니다. 마크다운 파일의 본문은 에이전트의 시스템 프롬프트가 됩니다.

예: .gemini/agents/security-auditor.md

---
name: security-auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
  - read_file
  - grep_search
model: gemini-2.5-pro
temperature: 0.2
max_turns: 10
---
 
You are a ruthless Security Auditor. Your job is to analyze code for potential
vulnerabilities.
 
Focus on:
 
1.  SQL Injection
2.  XSS (Cross-Site Scripting)
3.  Hardcoded credentials
4.  Unsafe file operations
 
When you find a vulnerability, explain it clearly and suggest a fix. Do not fix
it yourself; just report it.

구성 스키마

서브 에이전트 최적화

메인 에이전트의 시스템 프롬프트는 전문 서브 에이전트를 사용할 수 있을 때 이를 사용하도록 권장합니다. 에이전트의 설명을 기반으로 해당 에이전트가 관련 전문가인지 결정합니다. 설명을 업데이트하여 다음을 더 명확하게 표시하면 에이전트 사용의 신뢰성을 높일 수 있습니다:

• 전문 분야.
• 사용되어야 하는 시기.
• 몇 가지 예시 시나리오.

예를 들어, 다음 서브 에이전트 설명은 Git 작업에 대해 꽤 일관되게 호출되어야 합니다.

Git expert agent which should be used for all local and remote git operations. For example:

• Making commits
• Searching for regressions with bisect
• Interacting with source control and issues providers such as GitHub.

서브 에이전트를 더 튜닝해야 하는 경우, /model로 최적화할 모델을 선택한 다음, 모델에게 특정 프롬프트와 지정된 설명에 대해 왜 서브 에이전트가 호출되지 않았다고 생각하는지 물어볼 수 있습니다.

원격 서브 에이전트 (Agent2Agent) (실험적 기능)

Gemini CLI는 Agent-to-Agent (A2A) 프로토콜을 사용하여 원격 서브 에이전트에 작업을 위임할 수도 있습니다.

참고: 원격 서브 에이전트는 현재 실험적인 기능입니다.

자세한 구성 및 사용 지침은 원격 서브 에이전트 문서를 참조하세요.

확장 서브 에이전트

확장은 서브 에이전트를 번들로 묶어 배포할 수 있습니다. 확장 내에 에이전트를 패키징하는 방법에 대한 자세한 내용은 확장 문서를 참조하세요.