Tool Registry와 내장 도구 완벽 가이드

AI 에이전트 시스템에서 도구들을 체계적으로 관리하는 Tool Registry 패턴과 bash, edit, read, write, grep, glob, task 등 핵심 내장 도구들의 구조와 동작 원리를 살펴봅니다.

---

목차

1. tool_디렉토리_구조
2. ToolRegistry_패턴
3. bash_명령어_실행_도구
4. edit_파일_편집_도구
5. read_write_파일_입출력
6. grep_glob_검색_도구
7. task_서브에이전트_생성

---

1. tool 디렉토리 구조

김개발 씨는 AI 에이전트 프로젝트에 처음 투입되었습니다. 방대한 코드베이스를 열어본 순간, tool이라는 폴더가 눈에 들어왔습니다.

"도대체 이 많은 파일들은 뭘 하는 걸까?" 선배 박시니어 씨가 다가와 말했습니다. "거기가 바로 에이전트의 손과 발이야."

tool 디렉토리는 AI 에이전트가 실제 세상과 상호작용하는 모든 도구들이 모여있는 곳입니다. 마치 공구함에 드라이버, 망치, 톱이 정리되어 있는 것처럼, 파일 읽기, 쓰기, 검색, 명령어 실행 등 각 기능이 개별 파일로 분리되어 있습니다.

이 구조를 이해하면 에이전트가 어떻게 작업을 수행하는지 한눈에 파악할 수 있습니다.

다음 코드를 살펴봅시다.

// tool/ 디렉토리의 전형적인 구조
tool/
├── index.ts          // 모든 도구를 export하는 진입점
├── registry.ts       // 도구들을 등록하고 관리하는 레지스트리
├── bash.ts           // 셸 명령어 실행 도구
├── edit.ts           // 파일 편집 도구
├── read.ts           // 파일 읽기 도구
├── write.ts          // 파일 쓰기 도구
├── grep.ts           // 텍스트 검색 도구
├── glob.ts           // 파일 패턴 매칭 도구
├── task.ts           // 서브에이전트 생성 도구
└── types.ts          // 공통 타입 정의

김개발 씨는 입사한 지 일주일 된 주니어 개발자입니다. 오늘 처음으로 AI 에이전트 프로젝트의 코드를 분석하라는 과제를 받았습니다.

프로젝트 폴더를 열어보니 수십 개의 디렉토리가 나열되어 있었고, 그중 tool이라는 폴더가 유독 눈에 띄었습니다. "이게 다 뭐지?" 김개발 씨가 혼잣말을 하자, 옆자리의 박시니어 씨가 의자를 끌고 다가왔습니다.

"AI 에이전트가 뭔지 알아?" 김개발 씨가 고개를 끄덕이자 박시니어 씨가 설명을 이어갔습니다. "에이전트는 혼자서는 아무것도 못 해.

파일을 읽으려면 읽기 도구가 필요하고, 코드를 수정하려면 편집 도구가 필요하지. 그 모든 도구들이 바로 저 tool 폴더에 있어." 쉽게 비유하자면, tool 디렉토리는 마치 정비사의 공구함과 같습니다.

정비사가 자동차를 고칠 때 렌치, 드라이버, 플라이어 등 다양한 공구를 사용하듯이, AI 에이전트도 파일을 읽고, 쓰고, 검색하고, 명령어를 실행하는 다양한 도구를 사용합니다. 그리고 그 도구들이 체계적으로 정리된 곳이 바로 tool 디렉토리입니다.

이 디렉토리에서 가장 먼저 눈에 들어오는 것은 index.ts 파일입니다. 이 파일은 모든 도구들을 한곳에서 내보내는 역할을 합니다.

외부에서 도구를 사용하고 싶을 때 개별 파일을 일일이 import하지 않고, index.ts 하나만 참조하면 됩니다. 다음으로 중요한 것은 registry.ts 파일입니다.

이 파일은 모든 도구들을 등록하고 관리하는 중앙 관리소 역할을 합니다. 에이전트가 특정 도구를 찾을 때 이 레지스트리를 통해 접근합니다.

마치 회사의 인사팀이 모든 직원 정보를 관리하는 것과 비슷합니다. 나머지 파일들은 각각 하나의 도구를 담당합니다.

bash.ts는 터미널 명령어를 실행하고, edit.ts는 파일을 수정하며, read.ts와 write.ts는 파일을 읽고 씁니다. grep.ts와 glob.ts는 검색 기능을 제공하고, task.ts는 새로운 서브에이전트를 생성합니다.

이렇게 도구를 파일별로 분리하면 어떤 장점이 있을까요? 첫째, 유지보수가 쉬워집니다.

파일 읽기 기능에 버그가 생기면 read.ts만 수정하면 됩니다. 둘째, 확장이 용이합니다.

새로운 도구가 필요하면 새 파일을 추가하고 레지스트리에 등록하기만 하면 됩니다. 셋째, 테스트가 간편합니다.

각 도구를 독립적으로 테스트할 수 있습니다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"그러니까 이 폴더 구조만 이해하면 에이전트가 할 수 있는 모든 것을 알 수 있는 거네요?" 박시니어 씨가 미소 지으며 대답했습니다. "정확해.

이제 각 도구를 하나씩 살펴보자."

실전 팁

💡 - 새 도구를 추가할 때는 기존 도구 파일의 구조를 참고하여 일관성을 유지하세요

• types.ts에 공통 인터페이스를 정의하여 도구 간 타입 일관성을 확보하세요

---

2. ToolRegistry 패턴

김개발 씨는 각 도구 파일을 살펴보다가 의문이 들었습니다. "에이전트는 이 많은 도구들 중에서 어떻게 필요한 걸 찾아서 쓰지?" 박시니어 씨가 registry.ts 파일을 열며 말했습니다.

"바로 이 녀석이 그 비밀이야. Tool Registry라고 부르지."

Tool Registry는 모든 도구들을 중앙에서 등록하고 관리하는 패턴입니다. 마치 도서관의 사서가 모든 책의 위치를 알고 있어서 원하는 책을 바로 찾아주는 것처럼, 레지스트리는 에이전트가 필요한 도구를 즉시 찾아 실행할 수 있게 해줍니다.

이 패턴을 사용하면 도구의 추가, 삭제, 수정이 다른 코드에 영향을 주지 않습니다.

다음 코드를 살펴봅시다.

// Tool 인터페이스 정의
interface Tool {
  name: string;
  description: string;
  parameters: Record<string, ParameterSchema>;
  execute: (params: unknown) => Promise<ToolResult>;
}

// ToolRegistry 클래스
class ToolRegistry {
  private tools: Map<string, Tool> = new Map();

  // 도구 등록
  register(tool: Tool): void {
    this.tools.set(tool.name, tool);
  }

  // 이름으로 도구 조회
  get(name: string): Tool | undefined {
    return this.tools.get(name);
  }

  // 등록된 모든 도구 목록 반환
  list(): Tool[] {
    return Array.from(this.tools.values());
  }
}

도서관에 처음 가면 어떻게 해야 할까요? 원하는 책을 찾으려면 서가를 하나하나 돌아다녀야 할까요?

아닙니다. 검색 시스템이나 사서에게 물어보면 됩니다.

사서는 모든 책이 어디에 있는지 알고 있고, 원하는 책을 바로 찾아줍니다. Tool Registry가 바로 그 사서 역할을 합니다.

에이전트가 "파일을 읽고 싶어"라고 하면, 레지스트리는 즉시 read 도구를 찾아서 제공합니다. "명령어를 실행하고 싶어"라고 하면 bash 도구를 찾아줍니다.

에이전트는 도구가 어디에 있는지, 어떻게 구현되어 있는지 알 필요가 없습니다. 코드를 살펴보겠습니다.

먼저 Tool 인터페이스가 정의되어 있습니다. 모든 도구는 이 인터페이스를 따라야 합니다.

name은 도구의 이름, description은 설명, parameters는 매개변수 스키마, 그리고 execute는 실제 실행 함수입니다. ToolRegistry 클래스는 Map 자료구조를 사용하여 도구들을 저장합니다.

Map을 사용하는 이유는 이름으로 빠르게 검색할 수 있기 때문입니다. 배열을 사용하면 매번 전체를 순회해야 하지만, Map은 O(1) 시간에 원하는 도구를 찾을 수 있습니다.

register 메서드는 새 도구를 레지스트리에 등록합니다. 도구 객체를 받아서 이름을 키로 Map에 저장합니다.

이렇게 등록된 도구는 언제든 꺼내서 사용할 수 있습니다. get 메서드는 이름으로 도구를 찾습니다.

에이전트가 특정 작업을 수행해야 할 때 이 메서드를 호출합니다. 만약 존재하지 않는 도구를 요청하면 undefined를 반환합니다.

list 메서드는 등록된 모든 도구의 목록을 반환합니다. 이 메서드는 에이전트가 사용 가능한 도구들을 파악하거나, 사용자에게 도구 목록을 보여줄 때 유용합니다.

이 패턴의 가장 큰 장점은 느슨한 결합입니다. 에이전트 코드는 개별 도구의 구현에 의존하지 않습니다.

레지스트리라는 중간 계층을 통해 도구에 접근하기 때문에, 도구가 변경되어도 에이전트 코드는 수정할 필요가 없습니다. 또 다른 장점은 동적 확장성입니다.

런타임에 새로운 도구를 추가하거나 기존 도구를 제거할 수 있습니다. 플러그인 시스템을 구현할 때 이 특성이 매우 유용합니다.

김개발 씨가 물었습니다. "그러면 에이전트가 어떤 도구를 쓸지는 누가 결정해요?" 박시니어 씨가 대답했습니다.

"AI 모델이 상황을 판단해서 적절한 도구를 선택해. 레지스트리는 단지 도구를 찾아주는 역할만 하지."

실전 팁

💡 - 도구 이름은 명확하고 직관적으로 지어서 AI 모델이 올바른 도구를 선택하도록 도우세요

• 레지스트리에 도구 유효성 검사 로직을 추가하면 잘못된 도구 등록을 방지할 수 있습니다

---

3. bash 명령어 실행 도구

김개발 씨가 질문했습니다. "에이전트가 npm install이나 git status 같은 명령어도 실행할 수 있어요?" 박시니어 씨가 bash.ts 파일을 열며 고개를 끄덕였습니다.

"당연하지. 이게 바로 에이전트의 가장 강력한 무기 중 하나야.

하지만 그만큼 조심해서 다뤄야 해."

bash 도구는 에이전트가 운영체제의 셸 명령어를 실행할 수 있게 해주는 도구입니다. npm, git, docker 등 개발에 필요한 모든 명령어를 실행할 수 있습니다.

마치 개발자가 터미널을 열고 명령어를 입력하는 것과 같습니다. 하지만 강력한 만큼 보안에 각별히 주의해야 합니다.

다음 코드를 살펴봅시다.

// bash.ts - 명령어 실행 도구
import { spawn } from 'child_process';

interface BashParams {
  command: string;
  timeout?: number;
  cwd?: string;
}

async function executeBash(params: BashParams): Promise<ToolResult> {
  const { command, timeout = 120000, cwd } = params;

  // 위험한 명령어 검사
  if (isDangerousCommand(command)) {
    return { error: 'This command is not allowed' };
  }

  return new Promise((resolve) => {
    const process = spawn('bash', ['-c', command], { cwd });
    let stdout = '', stderr = '';

    process.stdout.on('data', (data) => stdout += data);
    process.stderr.on('data', (data) => stderr += data);
    process.on('close', (code) => resolve({ stdout, stderr, code }));
  });
}

개발자에게 터미널은 마법의 지팡이와 같습니다. npm install 한 번이면 수백 개의 패키지가 설치되고, git push 한 번이면 코드가 전 세계로 배포됩니다.

AI 에이전트도 이 강력한 힘을 사용할 수 있어야 진정한 개발 도우미가 될 수 있습니다. bash 도구가 바로 그 역할을 합니다.

에이전트가 "npm install을 실행해줘"라고 요청받으면, bash 도구가 실제로 터미널에서 그 명령어를 실행하고 결과를 반환합니다. 코드를 살펴보면, 먼저 BashParams 인터페이스가 정의되어 있습니다.

command는 실행할 명령어, timeout은 최대 대기 시간, cwd는 명령어를 실행할 디렉토리입니다. timeout을 설정하는 이유는 무한 루프나 장시간 실행되는 명령어로부터 시스템을 보호하기 위해서입니다.

가장 중요한 부분은 isDangerousCommand 검사입니다. rm -rf /, sudo, shutdown 같은 위험한 명령어는 실행 전에 차단됩니다.

이 검사가 없다면 악의적인 프롬프트로 시스템 전체가 파괴될 수 있습니다. 명령어 실행에는 Node.js의 spawn 함수를 사용합니다.

exec 대신 spawn을 사용하는 이유는 더 세밀한 제어가 가능하기 때문입니다. stdout과 stderr를 실시간으로 스트리밍 받을 수 있고, 프로세스를 중간에 종료시킬 수도 있습니다.

실행 결과로는 stdout, stderr, exit code가 반환됩니다. stdout은 정상 출력, stderr는 에러 출력, exit code는 명령어의 성공 여부를 나타냅니다.

exit code가 0이면 성공, 그 외의 값이면 실패입니다. 실무에서는 이 도구로 빌드, 테스트, 배포 등 다양한 작업을 자동화할 수 있습니다.

"테스트를 실행해줘"라고 하면 npm test를 실행하고, 실패한 테스트가 있으면 그 결과를 분석해서 수정 방향을 제안할 수 있습니다. 하지만 주의할 점이 있습니다.

bash 도구는 양날의 검입니다. 잘못 사용하면 시스템에 치명적인 손상을 줄 수 있습니다.

따라서 실행 가능한 명령어를 화이트리스트로 관리하거나, 샌드박스 환경에서 실행하는 것이 안전합니다. 김개발 씨가 걱정스러운 표정으로 물었습니다.

"그럼 혹시 에이전트가 이상한 명령어를 실행하면 어떻게 해요?" 박시니어 씨가 대답했습니다. "그래서 우리는 모든 명령어를 로그로 남기고, 위험한 명령어는 사용자 승인을 받도록 설계했어."

실전 팁

💡 - 민감한 명령어는 반드시 사용자 승인 단계를 추가하세요

• 명령어 실행 로그를 남겨서 문제 발생 시 추적할 수 있게 하세요

---

4. edit 파일 편집 도구

"에이전트가 직접 코드를 수정할 수도 있어요?" 김개발 씨의 눈이 반짝였습니다. 박시니어 씨가 edit.ts를 열며 말했습니다.

"이게 바로 AI 코딩 어시스턴트의 핵심이야. 단순히 코드를 제안하는 게 아니라, 실제로 파일을 수정할 수 있지."

edit 도구는 파일의 특정 부분을 찾아서 수정하는 도구입니다. 전체 파일을 덮어쓰는 대신, 변경이 필요한 부분만 정밀하게 수정합니다.

마치 외과 의사가 필요한 부위만 정확히 수술하는 것처럼, 코드의 다른 부분은 건드리지 않고 원하는 곳만 수정할 수 있습니다. 이 방식은 실수로 인한 코드 손실을 방지합니다.

다음 코드를 살펴봅시다.

// edit.ts - 파일 편집 도구
interface EditParams {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
}

async function executeEdit(params: EditParams): Promise<ToolResult> {
  const { file_path, old_string, new_string, replace_all = false } = params;

  // 파일 내용 읽기
  const content = await fs.readFile(file_path, 'utf-8');

  // old_string이 파일에 존재하는지 확인
  if (!content.includes(old_string)) {
    return { error: 'old_string not found in file' };
  }

  // 문자열 치환
  const newContent = replace_all
    ? content.replaceAll(old_string, new_string)
    : content.replace(old_string, new_string);

  // 변경된 내용 저장
  await fs.writeFile(file_path, newContent, 'utf-8');
  return { success: true, message: 'File edited successfully' };
}

문서 작성 프로그램에서 찾기-바꾸기 기능을 사용해 본 적이 있으신가요? "Apple"을 모두 "Orange"로 바꾸고 싶을 때, 일일이 찾아서 수정하는 대신 한 번에 모두 바꿀 수 있는 그 기능 말입니다.

edit 도구는 바로 그 찾기-바꾸기 기능을 프로그래밍 방식으로 구현한 것입니다. 하지만 단순한 텍스트 에디터보다 훨씬 더 정교합니다.

코드의 구조를 이해하고, 정확한 위치에 정확한 수정을 가합니다. 왜 전체 파일을 덮어쓰지 않고 이런 방식을 사용할까요?

몇 가지 중요한 이유가 있습니다. 첫째, 안전성입니다.

전체 파일을 덮어쓰면 실수로 다른 부분이 변경될 위험이 있습니다. 특히 AI가 파일의 일부만 기억하고 있을 때, 나머지 부분이 사라질 수 있습니다.

edit 도구는 지정한 부분만 변경하므로 이런 위험이 없습니다. 둘째, 정밀성입니다.

1000줄짜리 파일에서 딱 한 줄만 수정하고 싶을 때, 전체를 다시 쓰는 것은 비효율적입니다. edit 도구는 정확히 그 한 줄만 찾아서 수정합니다.

코드를 보면, 먼저 old_string이 파일에 존재하는지 확인합니다. 이 검사가 중요한 이유는, 존재하지 않는 문자열을 바꾸려고 하면 의도치 않은 결과가 발생할 수 있기 때문입니다.

replace_all 옵션은 같은 문자열이 여러 번 나올 때 모두 바꿀지, 첫 번째만 바꿀지를 결정합니다. 변수명을 리팩토링할 때는 replace_all을 true로 설정하고, 특정 위치만 수정할 때는 false로 설정합니다.

실무에서 한 가지 주의할 점이 있습니다. old_string이 고유해야 한다는 것입니다.

만약 같은 문자열이 파일에 여러 번 나타나고 replace_all이 false라면, 의도하지 않은 곳이 수정될 수 있습니다. 따라서 old_string에는 충분한 컨텍스트를 포함시켜야 합니다.

김개발 씨가 감탄했습니다. "와, 이거 정말 편하겠네요.

에이전트한테 버그 고쳐달라고 하면 직접 코드를 수정해주는 거잖아요." 박시니어 씨가 고개를 끄덕였습니다. "맞아.

하지만 항상 변경 사항을 검토하는 습관을 들여야 해. AI도 실수할 수 있거든."

실전 팁

💡 - old_string은 수정하려는 부분을 고유하게 식별할 수 있도록 충분한 컨텍스트를 포함하세요

• 중요한 파일을 수정하기 전에는 git으로 백업해두는 것이 안전합니다

---

5. read write 파일 입출력

"파일을 수정하려면 먼저 읽을 수 있어야 하잖아요?" 김개발 씨의 질문에 박시니어 씨가 read.ts와 write.ts 파일을 나란히 열었습니다. "맞아.

이 두 도구가 가장 기본이면서도 가장 많이 사용되는 도구야. edit 도구도 내부적으로는 이것들을 사용하지."

read 도구와 write 도구는 파일 시스템과 상호작용하는 가장 기본적인 도구들입니다. read는 파일의 내용을 읽어서 에이전트에게 전달하고, write는 에이전트가 생성한 내용을 파일로 저장합니다.

마치 눈으로 문서를 읽고 손으로 문서를 작성하는 것처럼, 에이전트가 코드베이스를 이해하고 수정하는 데 필수적인 도구입니다.

다음 코드를 살펴봅시다.

// read.ts - 파일 읽기 도구
interface ReadParams {
  file_path: string;
  offset?: number;   // 시작 줄 번호
  limit?: number;    // 읽을 줄 수
}

async function executeRead(params: ReadParams): Promise<ToolResult> {
  const { file_path, offset = 0, limit = 2000 } = params;
  const content = await fs.readFile(file_path, 'utf-8');
  const lines = content.split('\n');

  // 줄 번호와 함께 반환
  const result = lines
    .slice(offset, offset + limit)
    .map((line, i) => `${offset + i + 1}\t${line}`)
    .join('\n');

  return { content: result, totalLines: lines.length };
}

// write.ts - 파일 쓰기 도구
async function executeWrite(params: WriteParams): Promise<ToolResult> {
  await fs.writeFile(params.file_path, params.content, 'utf-8');
  return { success: true };
}

프로그래밍의 가장 기본은 무엇일까요? 화려한 알고리즘도, 복잡한 아키텍처도 아닙니다.

바로 파일을 읽고 쓰는 것입니다. 코드를 작성한다는 것은 결국 텍스트 파일을 만드는 것이고, 코드를 분석한다는 것은 텍스트 파일을 읽는 것입니다.

AI 에이전트도 마찬가지입니다. 코드를 이해하려면 먼저 파일을 읽어야 하고, 코드를 생성했다면 파일로 저장해야 합니다.

read 도구와 write 도구가 바로 이 역할을 담당합니다. read 도구의 코드를 살펴보면, 흥미로운 기능들이 있습니다.

먼저 offset과 limit 매개변수입니다. 왜 이것이 필요할까요?

실제 프로젝트에는 수천 줄짜리 파일도 흔합니다. 이런 파일을 한 번에 모두 읽어서 AI에게 전달하면 두 가지 문제가 생깁니다.

첫째, AI의 컨텍스트 윈도우를 낭비합니다. 둘째, 응답 시간이 느려집니다.

offset과 limit을 사용하면 필요한 부분만 선택적으로 읽을 수 있습니다. 또 한 가지 주목할 점은 줄 번호입니다.

각 줄 앞에 번호를 붙여서 반환합니다. 이렇게 하면 에이전트가 "42번째 줄의 버그를 수정하겠습니다"라고 정확하게 위치를 지정할 수 있습니다.

write 도구는 상대적으로 단순합니다. 파일 경로와 내용을 받아서 저장하면 됩니다.

하지만 중요한 규칙이 하나 있습니다. 기존 파일을 덮어쓰기 전에는 반드시 먼저 read로 읽어야 합니다.

이 규칙이 없으면 에이전트가 파일의 전체 내용을 모르는 상태에서 일부만 기억해서 저장할 수 있고, 그러면 나머지 내용이 사라집니다. read와 write는 단순해 보이지만, 에이전트 시스템에서 가장 많이 호출되는 도구입니다.

코드 분석, 버그 수정, 새 기능 추가, 리팩토링 등 모든 작업의 시작과 끝에 이 도구들이 있습니다. 김개발 씨가 물었습니다.

"그런데 이미지 파일이나 바이너리 파일도 읽을 수 있어요?" 박시니어 씨가 대답했습니다. "좋은 질문이야.

최신 버전에서는 이미지 파일도 읽어서 AI에게 시각 정보로 전달할 수 있어. 멀티모달 AI의 장점이지."

실전 팁

💡 - 대용량 파일을 읽을 때는 offset과 limit을 활용하여 필요한 부분만 읽으세요

• write 전에는 항상 read를 먼저 실행하여 기존 내용을 확인하는 습관을 들이세요

---

6. grep glob 검색 도구

김개발 씨가 난감한 표정을 지었습니다. "수천 개의 파일 중에서 특정 함수가 어디에 정의되어 있는지 어떻게 찾죠?" 박시니어 씨가 grep.ts와 glob.ts를 열며 미소 지었습니다.

"바로 이 두 검색 도구가 해결해줘. grep은 내용으로, glob은 이름으로 파일을 찾지."

grep 도구는 파일 내용에서 특정 패턴을 검색하고, glob 도구는 파일 이름 패턴으로 파일을 찾습니다. grep은 "이 함수를 호출하는 곳이 어디지?"라는 질문에, glob은 "테스트 파일들은 어디 있지?"라는 질문에 답합니다.

마치 탐정이 단서를 찾듯이, 이 도구들은 방대한 코드베이스에서 원하는 정보를 빠르게 찾아냅니다.

다음 코드를 살펴봅시다.

// grep.ts - 내용 검색 도구
interface GrepParams {
  pattern: string;      // 검색할 정규식 패턴
  path?: string;        // 검색 경로
  glob?: string;        // 파일 필터 (예: "*.ts")
  output_mode?: 'content' | 'files_with_matches' | 'count';
}

async function executeGrep(params: GrepParams): Promise<ToolResult> {
  const args = ['--json', params.pattern];
  if (params.glob) args.push('--glob', params.glob);
  if (params.path) args.push(params.path);

  const result = await runRipgrep(args);
  return { matches: result };
}

// glob.ts - 파일명 검색 도구
interface GlobParams {
  pattern: string;  // 예: "**/*.test.ts"
  path?: string;
}

async function executeGlob(params: GlobParams): Promise<ToolResult> {
  const files = await fastGlob(params.pattern, { cwd: params.path });
  return { files: files.sort(byModificationTime) };
}

새 프로젝트에 투입되었을 때 가장 막막한 순간은 언제일까요? 바로 "이 코드가 어디 있지?"라는 질문에 답을 못 할 때입니다.

수백 개의 파일, 수만 줄의 코드 속에서 원하는 것을 찾는 것은 건초 더미에서 바늘 찾기와 같습니다. grep 도구와 glob 도구는 이 문제를 해결합니다.

두 도구는 비슷해 보이지만 용도가 다릅니다. grep은 파일 내용을 검색합니다.

"getUserById라는 함수가 어디서 호출되지?"라는 질문에 답합니다. 정규식을 지원하므로 복잡한 패턴도 검색할 수 있습니다.

예를 들어 "user.*Error"로 검색하면 userNotFoundError, userValidationError 등을 모두 찾을 수 있습니다. glob은 파일 이름을 검색합니다.

"테스트 파일들은 어디 있지?"라는 질문에 답합니다. 패턴 문법이 직관적입니다.

"**/*.test.ts"는 모든 하위 폴더에서 .test.ts로 끝나는 파일을 찾습니다. grep의 코드를 보면 내부적으로 ripgrep을 사용합니다.

ripgrep은 기존의 grep보다 훨씬 빠른 검색 도구입니다. 수십만 개의 파일도 순식간에 검색할 수 있습니다.

output_mode 매개변수는 결과 형식을 결정합니다. 'content'는 매칭된 줄의 내용을, 'files_with_matches'는 파일 경로만을, 'count'는 매칭 횟수를 반환합니다.

상황에 따라 적절한 모드를 선택하면 됩니다. glob의 코드에서 주목할 점은 결과를 수정 시간 순으로 정렬한다는 것입니다.

최근에 수정된 파일이 먼저 나옵니다. 보통 최근에 수정된 파일이 현재 작업과 관련 있을 가능성이 높기 때문입니다.

이 두 도구는 함께 사용할 때 더욱 강력해집니다. 먼저 glob으로 특정 유형의 파일을 찾고, 그 파일들 안에서 grep으로 내용을 검색하는 식입니다.

예를 들어 "모든 TypeScript 파일에서 deprecated된 API를 찾아줘"라는 요청을 처리할 수 있습니다. 김개발 씨가 감탄했습니다.

"이거 있으면 새 프로젝트 파악하는 시간이 확 줄겠네요!" 박시니어 씨가 동의했습니다. "맞아.

에이전트가 코드베이스를 이해하는 첫 번째 단계가 바로 이 검색 도구들을 활용하는 거야."

실전 팁

💡 - grep에서 정규식 특수문자를 사용할 때는 이스케이프 처리를 잊지 마세요

• glob 패턴에서 **는 모든 하위 디렉토리, *는 현재 디렉토리만 의미합니다

---

7. task 서브에이전트 생성

"잠깐, 에이전트가 다른 에이전트를 만들 수도 있어요?" 김개발 씨의 질문에 박시니어 씨가 task.ts를 열며 고개를 끄덕였습니다. "이게 바로 에이전트 시스템의 꽃이야.

복잡한 작업을 여러 전문 에이전트에게 분산시킬 수 있거든."

task 도구는 새로운 서브에이전트를 생성하여 복잡한 작업을 위임하는 도구입니다. 마치 팀장이 팀원들에게 업무를 분배하는 것처럼, 메인 에이전트가 특정 작업을 전문 서브에이전트에게 맡깁니다.

코드 탐색, 계획 수립, 코드 리뷰 등 각 분야의 전문가 에이전트가 협력하여 더 나은 결과를 만들어냅니다.

다음 코드를 살펴봅시다.

// task.ts - 서브에이전트 생성 도구
interface TaskParams {
  prompt: string;           // 서브에이전트에게 전달할 작업 지시
  description: string;      // 작업에 대한 짧은 설명
  subagent_type: 'Explore' | 'Plan' | 'general-purpose';
  model?: 'sonnet' | 'opus' | 'haiku';  // 사용할 모델
}

async function executeTask(params: TaskParams): Promise<ToolResult> {
  const { prompt, subagent_type, model } = params;

  // 서브에이전트 유형별 도구 설정
  const tools = getToolsForSubagent(subagent_type);

  // 새 에이전트 세션 생성
  const agent = await createAgent({
    type: subagent_type,
    tools,
    model: model || 'sonnet',
  });

  // 작업 실행 및 결과 수집
  const result = await agent.run(prompt);
  return { agentResult: result };
}

function getToolsForSubagent(type: string): Tool[] {
  switch (type) {
    case 'Explore': return [read, grep, glob];
    case 'Plan': return [read, grep, glob, write];
    default: return getAllTools();
  }
}

회사에서 큰 프로젝트를 진행할 때 한 사람이 모든 일을 처리하나요? 아닙니다.

팀장은 기획자에게 기획을, 디자이너에게 디자인을, 개발자에게 개발을 맡깁니다. 각 분야의 전문가가 자신의 역할을 수행하고, 그 결과물이 모여 하나의 프로젝트가 완성됩니다.

task 도구는 바로 이런 업무 분배를 AI 에이전트 세계에서 구현합니다. 메인 에이전트가 팀장이라면, 서브에이전트들은 각 분야의 전문가 팀원입니다.

현재 시스템에는 여러 유형의 서브에이전트가 있습니다. Explore 에이전트는 코드베이스 탐색 전문가입니다.

파일을 빠르게 훑어보고, 구조를 파악하고, 원하는 코드를 찾아냅니다. Plan 에이전트는 구현 계획 수립 전문가입니다.

복잡한 요구사항을 분석하고, 단계별 실행 계획을 세웁니다. general-purpose 에이전트는 범용 작업을 처리합니다.

코드를 보면, 서브에이전트 유형에 따라 사용 가능한 도구가 다릅니다. Explore 에이전트는 read, grep, glob만 사용합니다.

파일을 읽고 검색하는 것이 주 업무이기 때문입니다. Plan 에이전트는 여기에 write가 추가됩니다.

계획을 파일로 저장해야 하기 때문입니다. 이렇게 도구를 제한하는 이유가 있습니다.

첫째, 보안입니다. 탐색만 하는 에이전트에게 bash 도구를 주면 불필요한 위험이 생깁니다.

둘째, 집중입니다. 도구가 적을수록 에이전트가 본연의 임무에 집중할 수 있습니다.

model 매개변수도 중요합니다. 단순한 작업에는 가벼운 haiku 모델을, 복잡한 작업에는 강력한 opus 모델을 선택할 수 있습니다.

비용과 성능의 균형을 맞출 수 있습니다. 서브에이전트의 가장 큰 장점은 병렬 처리입니다.

여러 서브에이전트를 동시에 실행하여 작업 시간을 단축할 수 있습니다. 예를 들어 "프론트엔드와 백엔드 코드를 동시에 분석해줘"라는 요청이 들어오면, 두 개의 Explore 에이전트를 병렬로 실행합니다.

김개발 씨가 흥분한 목소리로 말했습니다. "이거 완전 개미 군단 같네요!

하나의 명령에 여러 에이전트가 움직이는 거잖아요." 박시니어 씨가 웃으며 대답했습니다. "맞아.

그래서 이런 시스템을 멀티 에이전트 시스템이라고 부르지. 앞으로 이 분야가 더 발전할 거야."

실전 팁

💡 - 단순한 작업에는 haiku 모델로 비용을 절약하고, 복잡한 추론이 필요한 작업에만 opus를 사용하세요

• 서브에이전트에게 전달하는 prompt는 명확하고 구체적으로 작성하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!