레슨 1: '말만 하기'에서 '실행하기'로: 에이전트에 도구가 필요한 이유

학습 목표:

• 에이전트 안에서 '도구'가 실제로 무엇인지, 그리고 평범한 응답 텍스트 덩어리와 어떻게 다른지 말하기
• 도구 정의에 최소한 담겨야 하는 세 가지 알아보기
• 주어진 작업에 정말로 도구가 필요한지 판단하기

전제: 기본적인 프롬프트를 작성할 수 있고 Claude Code 같은 것을 써 본 적이 있다 | 다음: 레슨 2 >>

같은 문장을 두 번 묻는다

파일이 수십 개쯤 되는 프로젝트에서, 여러분이 에이전트에게 이렇게 말합니다.

"프로젝트에서 console.log를 전부 찾아 줘."

첫 번째 에이전트는 API에 연결된 채팅 상자일 뿐, 도구가 하나도 붙어 있지 않습니다. 응답은 이렇게 나옵니다.

파일 시스템에 직접 접근할 수는 없지만, 터미널에서 다음 명령을 실행하면 찾을 수 있습니다.

grep -rn "console.log" src/

이 명령은 src/ 아래의 모든 파일을 재귀적으로 검색해 console.log가 들어 있는 줄을 찾고, 파일 이름과 줄 번호를 출력합니다. 프로젝트에서 TypeScript를 쓴다면 검색 범위에 .ts/.tsx를 포함하는 것을 잊지 마세요.

틀린 말은 하나도 없습니다. 오히려 사려 깊습니다. 하지만 여러분이 요청한 것은 검색하는 방법에 대한 안내가 아니라 결과였습니다. 이 턴이 끝난 시점에도 프로젝트의 어느 파일에 실제로 console.log가 들어 있는지는 여전히 모릅니다. 직접 터미널을 열고 그 명령을 입력해야 합니다.

두 번째는 같은 문장을, 검색 도구가 연결된 에이전트에게 건넸습니다. 응답은 이렇게 나옵니다.

프로젝트를 검색해 console.log 7건을 찾았습니다.

• src/api/client.ts:42
• src/api/client.ts:88
• src/utils/logger.ts:12
• src/components/Cart.tsx:156
• src/components/Checkout.tsx:23
• src/hooks/useAuth.ts:67
• scripts/seed-db.js:5

src/utils/logger.ts:12의 것은 의도적으로 만든 로깅 래퍼로 보이고, 나머지 6건은 디버깅하다 남은 흔적으로 보입니다. 정리해 드릴까요?

두 번 모두 질문은 단어 하나까지 똑같았습니다. 같은 모델, 같은 프롬프트였습니다. 달랐던 것은 하나입니다. 두 번째 에이전트는 손에 든 것이 하나 더 있었습니다. 바로 도구입니다. 첫 번째 에이전트는 학습 과정에서 본 지식에 기대어 '아마 될 법한' 명령을 추측해 설명해 줄 수밖에 없었습니다. 두 번째 에이전트는 실제로 검색을 실행했고, 지금 이 순간 여러분의 프로젝트에 무엇이 있는지 확인한 뒤에야 입을 열었습니다.

이 레슨이 분명히 하려는 것이 바로 그것입니다. 도구가 무엇인지, 무엇이 에이전트를 '방법을 설명하는 존재'에서 '실제로 검색을 실행하는 존재'로 바꾸는지, 그리고 어떤 작업에는 도구가 아예 필요 없는지입니다.

도구는 호스트가 모델에게 건네는 메뉴판

먼저 직관 하나를 바로잡겠습니다. 그 7개 파일을 찾아낸 것은 모델이 아닙니다. 모델에게는 파일 시스템이 없습니다. 스스로 디렉터리를 열거나 정규식 매칭을 실행할 수 없습니다. 그 검색을 실제로 실행한 것은 에이전트를 구동하는 호스트 프로그램입니다. Claude Code일 수도 있고, 여러분이 직접 작성한 수십 줄짜리 Claude API 호출 스크립트일 수도 있습니다.

도구란 호스트 프로그램이 모델에게 '내가 너를 위해 해 줄 수 있는 일은 이런 것들이다'라고 알려 주는 목록입니다. 각 항목은 세 가지를 밝힙니다. 그 기능의 이름은 무엇인지, 언제 쓰는지, 어떤 파라미터를 넘겨야 하는지입니다. ¹

앞의 검색을 예로 들어 보겠습니다. 호스트가 요청에 실어 보내는 도구 목록은 대략 이런 모습입니다.

세 필드는 각자 맡은 일이 다릅니다. name은 모델이 이 도구를 고를 때 적어 넣는 식별자입니다. description은 이 도구가 무엇을 하고, 언제 써야 하며, 어떻게 동작하는지를 모델에게 알려 주는 텍스트 덩어리입니다. input_schema는 호출할 때 어떤 파라미터를 넘겨야 하고 각각의 타입이 무엇인지를 밝히는 JSON Schema입니다. ¹

모델은 여러분의 파일 시스템을 한 번도 본 적이 없지만, 이 목록은 봤습니다. description에서 이 도구가 "프로젝트 소스 디렉터리를 검색해… 파일 경로와 줄 번호를 반환한다"는 것을 읽고, 여러분의 요청인 "프로젝트에서 console.log를 전부 찾아 줘"를 보고, 둘을 맞춰 본 뒤, 이 도구를 고르고 pattern에 console\.log를 넘기기로 결정합니다. 이 단계는 모델의 몫입니다. 도구를 고르고 파라미터를 채우는 일이며, 이것이야말로 언어 모델이 가장 잘하는 일입니다. 의도를 읽고 알맞은 선택지에 대응시키는 것 말입니다.

그런데 고르고 난 다음에는요? 실제로 파일을 읽으러 가는 것은 누구일까요?

모델은 제안만 하고, 일은 호스트가 한다

여기 이 레슨에서 가장 중요한 문장 하나가 있습니다. 모델은 무엇도 스스로 실행하지 않습니다. '어떤 도구를 호출하고 싶고 어떤 파라미터를 넘길지'를 구조화된 데이터 덩어리로 포장해 호스트 프로그램에 돌려줄 뿐이고, 실제로 파일을 열고 명령을 실행하고 요청을 보내는 코드는 호스트 프로그램 자신의 것입니다. ²

앞의 검색에서 전체 흐름은 이렇게 흘러갑니다.

1. 모델이 여러분의 질문과 search_files 도구 목록을 보고, {"pattern": "console\\.log"}로 호출하기로 결정합니다. 그 결정을 이번 턴 응답의 내용으로 포장합니다. 응답에는 검색 결과가 들어 있지 않다는 점에 주목하세요. 모델에게는 검색 결과가 없기 때문입니다. 모델은 요청을 했을 뿐입니다.
2. 호스트 프로그램(Claude Code, 또는 여러분이 작성한 스크립트)이 그 데이터를 받아 '이건 도구 호출이구나'라고 판단하고, 직접 실행하러 갑니다. 실제로 디스크에서 검색을 돌려 그 7건의 일치를 얻습니다.
3. 호스트 프로그램이 검색 결과를 대화 이력에 다시 넣고 모델에게 한 번 더 묻습니다. "이 호출의 결과는 이것입니다. 계속하세요."
4. 이제서야 모델은 진짜 검색 결과를 처음으로 보고, 그것을 바탕으로 여러분이 본 그 응답을 씁니다.

OpenAI 문서는 이것을 "a multi-step conversation between your application and a model"(애플리케이션과 모델 사이의 여러 단계에 걸친 대화)이라고 부릅니다. 모델이 함수를 호출하면 그것을 실행하고 결과를 돌려줄 책임은 모델 쪽이 아니라 여러분의 애플리케이션 쪽에 있다는 것입니다. ³ Anthropic은 더 단도직입적으로 말합니다. "The model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation."(모델은 스스로 아무것도 실행하지 않는다. 구조화된 요청을 내보내면, 여러분의 코드 또는 Anthropic의 서버가 그 작업을 실행하고, 결과가 대화로 흘러 들어온다.) ²

덧붙일 것이 있습니다. '누가 실행하는가'는 한 겹 더 나뉩니다. 문서는 여러분의 프로그램이 직접 실행해야 하는 도구를 "client tools"라고 부르고, Anthropic 자체 서버가 대신 실행해 주는 도구(예를 들어 웹 검색)를 "server tools"라고 부릅니다. ⁴ 어느 쪽이든 모델 쪽의 동작은 달라지지 않습니다. 여전히 제안만 할 뿐 행동하지 않습니다. 유일한 차이는 그 제안을 실제 행동으로 바꾸는 주체가 누구냐입니다.

여러분이 쓰고 있는 Claude Code가 이것을 구체적으로 보여 줍니다. Claude Code는 바로 이런 종류의 호스트 프로그램이며, 파일 읽기, 파일 쓰기, 터미널 명령 실행, 코드 검색 같은 도구 세트를 내장하고 있습니다. 모델이 어느 것을 쓸지 결정할 때마다, 없던 기능을 허공에서 만들어 내는 것이 아니라 이 고정된 목록에서 고르고 있는 것입니다. ⁵ 이 목록이 어디에서 오고 각 항목이 어떻게 생겼는지는 레슨 3에서 하나씩 살펴보겠습니다.

모든 작업에 도구가 필요하지는 않다

그 과정을 보고 나면 반대쪽 극단으로 기울기 쉽습니다. 도구가 이렇게 쓸모 있다면, 에이전트에게 무엇이든 도구를 붙여 주면 되지 않을까요? 그러지 마세요. 판별법은 간단합니다. 스스로 이 질문 하나를 던져 보면 됩니다. 이 작업에 필요한 정보나 행동을 모델이 이미 손에 쥐고 있는가?

어떤 작업은 바깥 세계와 접촉하지 않고도 모델이 혼자 해냅니다.

• 문단을 더 간결하게 다시 쓰기
• 회의록 묶음을 요약하기
• Python 코드 한 덩어리를 같은 로직의 JavaScript로 옮기기
• 여러분이 설명한 요구사항만 보고 새 코드를 바로 작성하기(프로젝트의 기존 파일을 건드리기 전 단계)

이런 작업이 기대는 지식은 모델이 학습 과정에서 비슷한 예시를 충분히 본 것들이고, 언어 능력만으로 마무리됩니다. 이런 작업에 도구를 억지로 붙이면 모델은 매번 '이번 라운드에 호출할까 말까'를 판단해야 합니다. 판단이 하나 늘어난다는 것은 잘못 고를 기회가 하나 늘어난다는 뜻입니다. 순전한 낭비입니다.

반면 어떤 작업은 아무리 영리해도 모델이 해낼 수 없습니다. 부족한 것이 능력이 아니라 정보이기 때문입니다.

• "지금 내 프로젝트에 console.log가 몇 개 있나" — 모델의 지식은 학습 시점에서 멈춰 있고, 지금 이 순간 여러분의 디스크에 있는 파일 내용은 전혀 알지 못합니다
• "방금 그 명령이 뭐라고 출력했나" — 명령은 아직 실행되지 않았고, 출력은 존재하지도 않으며, 모델이 미리 알 수는 없습니다
• "이 엔드포인트가 지금 무엇을 반환하나" — 그것은 지금 이 순간 서버가 주는 응답이고, 모델이 학습에서 본 어떤 예시와도 관계가 없습니다

이런 작업은 프롬프트를 아무리 상세하게, 아무리 유도적으로 써도 모델이 진짜 답을 만들어 낼 수 없습니다. 애초에 데이터를 손에 쥐고 있지 않기 때문입니다. 유일한 방법은 호스트 프로그램이 대신 가져올 수 있도록 통로를 주는 것이고, 그것이 도구가 존재하는 이유입니다.

그 다섯 가지 도구가 어떻게 생겼는지 — 읽기, 쓰기, 명령 실행, 검색, 외부 서비스 호출 — 는 레슨 3에서 하나씩 뜯어보겠습니다. 이 레슨에서 붙잡아 둘 것은 '이 작업에 도구가 필요한가'라는 질문을 던지는 법 하나뿐입니다.

정리

• 도구는 호스트 프로그램이 모델에게 노출하는, 호출 가능한 기능의 목록이고, 각 항목은 최소한 name, description, input_schema를 밝히며, 모델은 이것으로 호출 여부와 넘길 값을 판단한다 ¹
• 모델은 제안만 할 뿐, 스스로 실행하지 않는다. '어떤 도구를 호출하고 어떤 파라미터를 넘길지'를 구조화된 데이터로 포장해 호스트 프로그램에 돌려주고, 실제로 파일을 열고 명령을 실행하고 요청을 보내는 코드는 호스트 프로그램 자신의 것이다 ^{3 2}
• 결과는 한 번의 왕복을 거친다. 호스트가 실행을 마친 뒤 결과를 대화에 다시 넣어야 비로소 모델이 진짜 결과를 보고 최종 응답을 쓴다 — 그 단계의 전체 왕복이 다음 레슨의 주제다
• 어떤 작업에 도구가 필요한지 판단하려면 질문 하나면 충분하다. 이 작업에 필요한 정보나 행동을 모델이 이미 손에 쥐고 있는가? 아니라면 도구가 필요하고, 쥐고 있다면 붙이는 것이 낭비다
• 같은 질문이라도 도구가 있고 없고에 따라 결과가 완전히 달라진다. 도구가 없으면 에이전트는 학습에서 얻은 일반 지식에 기대어 방법을 설명해 주는 데 그치고, 도구가 있으면 지금 여러분의 프로젝트가 어떤 모습인지 실제로 만져 볼 수 있다

레슨 2: 도구 호출 한 번의 전체 왕복 >>

Footnotes

1. Define tools — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools ↩ ↩² ↩³

2. How tool use works — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works ↩ ↩² ↩³

3. Function calling — OpenAI API Guides — https://developers.openai.com/api/docs/guides/function-calling ↩ ↩²

4. Tool use with Claude — Overview — https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview ↩

5. Tools reference — Claude Code Docs — https://code.claude.com/docs/en/tools-reference ↩