Gemini CLI 코어: Tools API

Gemini CLI 코어(packages/core)는 도구를 정의, 등록 및 실행하기 위한 강력한 시스템을 갖추고 있습니다. 이러한 도구를 통해 Gemini 모델의 기능을 확장하여 로컬 환경과 상호 작용하고, 웹 콘텐츠를 가져오고, 단순한 텍스트 생성을 넘어 다양한 작업을 수행할 수 있습니다.

핵심 개념 (Core concepts)

도구 (tools.ts): 모든 도구의 계약을 정의하는 인터페이스 및 기본 클래스(BaseTool)입니다. 각 도구에는 다음이 있어야 합니다:
- name: 고유한 내부 이름 (Gemini API 호출에 사용됨).
- displayName: 사용자 친화적인 이름.
- description: 도구가 수행하는 작업에 대한 명확한 설명 (Gemini 모델에 제공됨).
- parameterSchema: 도구가 허용하는 매개변수를 정의하는 JSON 스키마. 이는 Gemini 모델이 도구를 올바르게 호출하는 방법을 이해하는 데 중요합니다.
- validateToolParams(): 들어오는 매개변수를 유효성 검사하는 메서드.
- getDescription(): 실행 전 특정 매개변수로 도구가 무엇을 할 것인지 사람이 읽을 수 있는 설명을 제공하는 메서드.
- shouldConfirmExecute(): 실행 전 사용자 확인이 필요한지(예: 잠재적으로 파괴적인 작업의 경우) 결정하는 메서드.
- execute(): 도구의 작업을 수행하고 ToolResult를 반환하는 핵심 메서드.
ToolResult (tools.ts): 도구 실행 결과의 구조를 정의하는 인터페이스:
- llmContent: 문맥을 위해 LLM으로 다시 전송되는 기록에 포함될 사실적 콘텐츠. 단순 문자열이거나 풍부한 콘텐츠를 위한 PartListUnion(Part 객체와 문자열의 배열)일 수 있습니다.
- returnDisplay: CLI에 표시하기 위한 사용자 친화적인 문자열(주로 Markdown) 또는 특수 객체(FileDiff 등).
풍부한 콘텐츠 반환: 도구는 단순 텍스트 반환에만 국한되지 않습니다. llmContent는 PartListUnion이 될 수 있으며, 이는 Part 객체(이미지, 오디오 등)와 string의 혼합을 포함할 수 있는 배열입니다. 이를 통해 단일 도구 실행으로 여러 개의 풍부한 콘텐츠 조각을 반환할 수 있습니다.
도구 레지스트리 (tool-registry.ts): 다음을 담당하는 클래스(ToolRegistry):
- 도구 등록: 사용 가능한 모든 내장 도구(예: ReadFileTool, ShellTool)의 컬렉션을 보유합니다.
- 도구 검색: 도구를 동적으로 검색할 수도 있습니다:
  - 명령 기반 검색: 설정에서 tools.discoveryCommand가 구성된 경우 이 명령이 실행됩니다. 이 명령은 사용자 정의 도구를 설명하는 JSON을 출력해야 하며, 이는 DiscoveredTool 인스턴스로 등록됩니다.
  - MCP 기반 검색: mcp.serverCommand가 구성된 경우, 레지스트리는 Model Context Protocol (MCP) 서버에 연결하여 도구를 나열하고 등록할 수 있습니다(DiscoveredMCPTool).
- 스키마 제공: 등록된 모든 도구의 FunctionDeclaration 스키마를 Gemini 모델에 노출하여 어떤 도구를 사용할 수 있고 어떻게 사용하는지 알 수 있게 합니다.
- 도구 검색: 코어가 실행할 특정 도구를 이름으로 가져올 수 있게 합니다.

내장 도구 (Built-in tools)

코어에는 주로 packages/core/src/tools/에 위치한 사전 정의된 도구 모음이 함께 제공됩니다. 여기에는 다음이 포함됩니다:

파일 시스템 도구:
- LSTool (ls.ts): 디렉터리 내용을 나열합니다.
- ReadFileTool (read-file.ts): 단일 파일의 내용을 읽습니다.
- WriteFileTool (write-file.ts): 파일에 내용을 씁니다.
- GrepTool (grep.ts): 파일에서 패턴을 검색합니다.
- GlobTool (glob.ts): glob 패턴과 일치하는 파일을 찾습니다.
- EditTool (edit.ts): 파일 내용을 제자리에서 수정합니다 (종종 확인 필요).
- ReadManyFilesTool (read-many-files.ts): 여러 파일 또는 glob 패턴의 내용을 읽고 연결합니다 (CLI의 @ 명령에서 사용됨).
실행 도구:
- ShellTool (shell.ts): 임의의 쉘 명령을 실행합니다 (신중한 샌드박싱 및 사용자 확인 필요).
웹 도구:
- WebFetchTool (web-fetch.ts): URL에서 콘텐츠를 가져옵니다.
- WebSearchTool (web-search.ts): 웹 검색을 수행합니다.
메모리 도구:
- MemoryTool (memoryTool.ts): AI의 메모리와 상호 작용합니다.

이러한 각 도구는 BaseTool을 확장하고 특정 기능을 위한 필수 메서드를 구현합니다.

도구 실행 흐름 (Tool execution flow)

모델 요청: Gemini 모델은 사용자의 프롬프트와 제공된 도구 스키마에 따라 도구를 사용하기로 결정하고, 도구 이름과 인수를 지정하여 응답에 FunctionCall 부분을 반환합니다.
코어 요청 수신: 코어는 이 FunctionCall을 파싱합니다.
도구 검색: ToolRegistry에서 요청된 도구를 조회합니다.
매개변수 유효성 검사: 도구의 validateToolParams() 메서드가 호출됩니다.
확인 (필요한 경우):
- 도구의 shouldConfirmExecute() 메서드가 호출됩니다.
- 확인을 위한 세부 정보를 반환하면 코어는 이를 CLI로 다시 전달하고 CLI는 사용자에게 메시지를 표시합니다.
- 사용자의 결정(예: 진행, 취소)이 코어로 다시 전송됩니다.
실행: 유효성이 확인되고 확인되었으면 (또는 확인이 필요 없는 경우), 코어는 제공된 인수와 AbortSignal(잠재적 취소용)을 사용하여 도구의 execute() 메서드를 호출합니다.
결과 처리: execute()에서 반환된 ToolResult를 코어가 수신합니다.
모델에 응답: ToolResult의 llmContent가 FunctionResponse로 패키징되어 Gemini 모델로 다시 전송되어 사용자 대상 응답을 계속 생성할 수 있게 합니다.
사용자에게 표시: ToolResult의 returnDisplay가 CLI로 전송되어 사용자에게 도구가 수행한 작업을 보여줍니다.

사용자 정의 도구로 확장 (Extending with custom tools)

일반적인 최종 사용자를 위해 제공된 파일에 사용자가 직접 프로그래밍 방식으로 새 도구를 등록하는 기본 워크플로가 명시적으로 자세히 설명되어 있지는 않지만, 아키텍처는 다음을 통해 확장을 지원합니다:

명령 기반 검색: 고급 사용자 또는 프로젝트 관리자는 settings.json에 tools.discoveryCommand를 정의할 수 있습니다. 이 명령은 Gemini CLI 코어에서 실행될 때 FunctionDeclaration 객체의 JSON 배열을 출력해야 합니다. 그러면 코어는 이것들을 DiscoveredTool 인스턴스로 사용할 수 있게 만듭니다. 해당되는 tools.callCommand는 이러한 사용자 정의 도구를 실제로 실행하는 역할을 담당합니다.
MCP 서버: 더 복잡한 시나리오의 경우, 하나 이상의 MCP 서버를 설정하고 settings.json의 mcpServers 설정을 통해 구성할 수 있습니다. 그러면 Gemini CLI 코어는 이러한 서버에서 노출된 도구를 검색하고 사용할 수 있습니다. 언급했듯이 여러 MCP 서버가 있는 경우 도구 이름에는 구성의 서버 이름이 접두사로 붙습니다 (예: serverAlias__actualToolName).

이 도구 시스템은 Gemini 모델의 기능을 강화할 수 있는 유연하고 강력한 방법을 제공하여 Gemini CLI를 광범위한 작업에 사용할 수 있는 다재다능한 비서로 만듭니다.

정책 엔진 자주 묻는 질문 (FAQ)