AI 에이전트한테 툴을 어떻게 줄까?

AI 에이전트를 만들 때 가장 어려운 부분이 뭔지 알아요?

모델 선택? 프롬프트 엔지니어링? 파인튜닝?

다 중요하지만, Anthropic 팀이 꼽은 건 따로 있어요.

"에이전트의 액션 스페이스를 어떻게 구성하느냐"

쉽게 말하면, AI한테 어떤 툴을 줄지 설계하는 문제예요. Claude는 Tool Calling을 통해 행동하는데, bash 명령어부터 스킬, 코드 실행까지 방법이 워낙 다양해서 무엇을 얼마나 줄지가 생각보다 훨씬 복잡한 문제거든요.

툴이 너무 적으면 에이전트가 할 수 있는 게 없고, 너무 많으면 모델이 어떤 걸 써야 할지 혼란스러워 해요. Claude Code는 현재 약 20개의 툴을 가지고 있는데, Anthropic 팀은 지금도 "이게 다 필요한가?"라고 계속 자문한다고 해요.

오늘은 Anthropic이 Claude Code를 만들면서 실제로 시행착오를 거쳐 깨달은 툴 설계의 원칙들을 소개해 드릴게요.

수학 문제를 풀어야 한다면?

Anthropic 팀이 툴 설계를 이야기할 때 즐겨 쓰는 비유가 있어요.

어려운 수학 문제를 풀어야 한다고 상상해 보세요. 당신한테 어떤 도구를 줄게요?

종이와 연필만 있으면? 풀 수는 있어요. 하지만 복잡한 계산은 손으로 하나하나 해야 하고, 실수가 생기면 처음부터 다시예요.

계산기가 있으면? 훨씬 빠르고 정확해요. 근데 고급 기능은 쓸 줄 알아야 해요. 미적분 계산기가 있어도 어떻게 입력해야 하는지 모르면 그냥 비싼 덧셈 기계가 되는 거잖아요.

컴퓨터가 있으면? 가장 강력해요. Python으로 코드를 짜면 어떤 수학 문제든 풀 수 있어요. 하지만 코딩을 할 줄 알아야 하고, 어떤 라이브러리를 써야 하는지도 알아야 해요.

이게 바로 AI 에이전트 툴 설계의 핵심이에요.

모델의 실력에 맞는 툴을 줘야 한다.

툴이 아무리 강력해도 모델이 그걸 제대로 활용하지 못하면 의미가 없어요. 반대로 모델이 충분히 똑똑한데 너무 단순한 툴만 주면 능력을 발휘하지 못하죠.

그렇다면 모델의 실력을 어떻게 파악하냐고요? Anthropic의 답은 단순해요.

"주의 깊게 관찰하고, 출력을 읽고, 실험하세요. 에이전트처럼 보는 법을 배우세요."

교훈 1: 질문 하나 만드는 데 실패를 세 번 했다

Claude Code를 쓰다 보면 Claude가 중간에 "이렇게 할까요, 저렇게 할까요?"라고 물어보는 걸 본 적 있을 거예요. 이게 AskUserQuestion 툴인데, 이걸 만드는 과정이 생각보다 훨씬 험난했어요.

목표는 단순했어요. Claude가 유저한테 더 잘 질문할 수 있게 만들기. Claude는 텍스트로 질문을 던질 수 있지만, 그냥 긴 텍스트로 질문하면 유저 입장에서 답하기 귀찮잖아요. 소통의 효율을 높이고 싶었던 거예요.

첫 번째 시도: 기존 툴에 끼워넣기

가장 쉬운 방법부터 시도했어요. 이미 있던 ExitPlanTool(계획 완료 신호를 보내는 툴)에 질문 배열 파라미터를 추가한 거예요.

결과? 실패.

Claude가 혼란스러워했어요. 계획을 세워야 하는데 동시에 그 계획에 대한 질문도 해야 하니까요. "유저의 답변이 내 계획이랑 충돌하면 어떡하지? ExitPlanTool을 두 번 불러야 하나?" 모델 입장에서 논리적으로 말이 안 되는 구조였던 거예요.

두 번째 시도: 출력 형식을 바꾸기

그래서 다음엔 Claude의 출력 형식 자체를 수정하려고 했어요. 마크다운으로 질문 목록을 출력하게 하고, 그걸 파싱해서 UI로 보여주는 방식이었어요.

이론적으로는 괜찮은 아이디어였는데, 실제로는 보장이 없었어요. Claude가 가끔 형식을 무시하거나, 옵션을 빼먹거나, 완전히 다른 구조로 쓰거나 했거든요. 불안정한 방식이었어요.

세 번째 시도: 아예 새 툴을 만들기

결국 AskUserQuestion이라는 전용 툴을 새로 만들었어요. Claude가 언제든 부를 수 있고, 특히 계획 모드에서 적극적으로 사용하도록 프롬프트한 거예요. 툴이 실행되면 모달창이 뜨고, 유저가 답변할 때까지 에이전트 루프가 멈춰요.

이 방법이 통했어요.

구조화된 출력을 강제할 수 있고, 유저한테 선택지를 주는 방식으로 소통이 자연스러워졌어요. 무엇보다 Claude가 이 툴 쓰는 걸 좋아했어요.

여기서 배운 핵심:

아무리 잘 설계된 툴이라도, 모델이 그 툴을 자연스럽게 쓰지 않으면 의미가 없다.

AskUserQuestion이 최종 형태냐고요? Anthropic은 "모르겠다"고 해요. 다음 예시에서 보듯이, 한 모델에서 잘 작동하는 방식이 다음 모델에선 최선이 아닐 수 있거든요.

교훈 2: 모델이 똑똑해지면, 예전 툴이 오히려 방해가 된다

Claude Code를 처음 출시했을 때, Claude한테는 Todo 리스트가 필요했어요.

복잡한 작업을 시작할 때 할 일을 목록으로 적고, 하나씩 체크하는 방식이었어요. TodoWrite 툴을 통해 Todos를 작성하거나 수정하고, 유저한테도 보여줬죠.

그래도 Claude가 할 일을 자주 잊어버려서, 5번 대화마다 자동으로 "지금 이걸 해야 해"라고 리마인더를 넣었어요.

초기에는 이게 꼭 필요했어요.

그런데 모델이 업그레이드되면서 상황이 바뀌었어요.

Claude가 더 이상 리마인더가 필요 없어진 거예요. 오히려 리마인더를 받으면 경직됐어요. "Todo 리스트에 있는 것만 해야 하나? 상황이 바뀌었는데 수정해도 되나?" 하고 헷갈려 했죠.

게다가 Opus 4.5부터 서브에이전트 활용이 크게 좋아졌는데, 문제가 생겼어요. 여러 서브에이전트가 하나의 Todo 리스트를 공유하는 게 어색했거든요. 서브에이전트 A가 Task 1을 하고 있는데, 서브에이전트 B가 같은 리스트를 보고 중복 작업을 하거나 충돌이 생기는 상황이었어요.

그래서 TodoWrite를 Task 툴로 교체했어요.

Todos는 "모델이 집중력을 유지하게 하는 것"에 초점이 맞춰져 있었다면, Tasks는 "에이전트들이 서로 소통하는 것"에 초점을 뒀어요. Tasks는 의존성을 설정할 수 있고, 서브에이전트끼리 업데이트를 공유하고, 상황에 따라 수정하거나 삭제할 수 있어요.

여기서 배운 핵심:

모델 능력이 올라가면, 예전에 필요했던 툴이 이제 발목을 잡을 수 있다.

툴을 한 번 만들고 끝이 아니에요. 모델이 발전할 때마다 "이 툴이 지금도 도움이 되는가, 아니면 오히려 제한이 되는가?"를 계속 점검해야 해요. 이게 비슷한 능력치를 가진 소수의 모델만 지원하는 게 편리한 이유이기도 해요. 일관된 기준으로 툴을 설계할 수 있거든요.

교훈 3: 가장 강력한 기능은 컨텍스트를 스스로 만드는 것

검색 툴 이야기를 안 할 수가 없어요. Claude Code에서 가장 극적으로 변한 영역이거든요.

처음엔 RAG를 썼어요

Claude Code 초기에는 RAG(Retrieval-Augmented Generation) 벡터 데이터베이스를 써서 Claude한테 컨텍스트를 제공했어요. 코드베이스를 인덱싱하고, 관련 내용을 찾아서 Claude한테 미리 넣어주는 방식이었죠.

속도도 빠르고 강력했어요. 근데 문제가 있었어요.

인덱싱 설정이 번거롭고, 다양한 환경에서 불안정하게 동작할 때가 있었어요. 무엇보다 Claude가 컨텍스트를 직접 찾는 게 아니라 주어지는 방식이었어요.

Grep 툴 하나로 판이 바뀌었어요

그래서 Claude한테 Grep 툴을 줬어요. 웹에서 검색할 수 있다면, 코드베이스도 직접 검색하면 되잖아요.

Claude가 스스로 파일을 탐색하고, 필요한 컨텍스트를 직접 구성하기 시작했어요.

이게 엄청난 변화였어요. 모델이 점점 똑똑해질수록, 올바른 툴만 주어지면 컨텍스트를 스스로 쌓는 능력이 비약적으로 좋아지더라고요.

Progressive Disclosure: 파일이 파일을 부른다

그 다음 단계가 Progressive Disclosure예요. Agent Skills를 도입하면서 공식화된 개념인데, 에이전트가 탐색을 통해 점진적으로 관련 컨텍스트를 발견하는 방식이에요.

구체적으로 어떻게 동작하냐면,

Claude가 스킬 파일을 읽어요 → 그 파일 안에 다른 파일들이 참조되어 있어요 → Claude가 그 파일들을 재귀적으로 읽어요 → 필요한 컨텍스트를 찾아낼 때까지 반복해요.

API 사용법이나 데이터베이스 쿼리 방법을 알려주는 스킬 파일처럼, 사실상 검색 능력을 확장하는 용도로 많이 써요.

1년 사이에 어떻게 변했냐고요?

처음엔 Claude가 컨텍스트를 스스로 만드는 능력이 거의 없었어요. 지금은 여러 레이어의 파일을 중첩 탐색해서 정확히 필요한 컨텍스트를 찾아내요.

Progressive Disclosure는 이제 툴을 추가하지 않고 새 기능을 넣는 표준 방법이 됐어요.

교훈 4: 툴을 추가하지 않고도 기능을 늘릴 수 있다

Claude Code 팀이 직면한 문제가 하나 있었어요.

Claude가 자기 자신에 대해서 잘 몰랐어요. "MCP 서버 어떻게 추가해?" "슬래시 커맨드가 뭐야?" 같은 질문에 제대로 답을 못 했거든요.

가장 쉬운 해결책은 시스템 프롬프트에 Claude Code 사용 가이드를 다 넣는 거예요. 근데 문제가 있어요. 유저가 자기 자신에 대해 묻는 건 드문 일이에요. 대부분은 그냥 코딩을 시켜요. 그러면 항상 존재하는 사용 가이드는 무거운 컨텍스트 낭비가 되고, 오히려 Claude의 주 업무인 코딩에 방해가 돼요.

그래서 다른 방법을 썼어요.

문서 링크를 주고 Claude가 직접 찾아보게 했어요. 처음엔 그럴듯해 보였는데, 또 문제가 생겼어요. 정확한 답 하나를 찾으면 되는데, Claude가 너무 많은 결과를 컨텍스트에 불러왔어요.

그래서 최종적으로는 Claude Code Guide 서브에이전트를 만들었어요.

유저가 Claude 자신에 대한 질문을 하면, 메인 Claude가 이 서브에이전트를 호출해요. 서브에이전트는 문서를 효율적으로 검색하는 방법에 대한 상세한 지침을 갖고 있고, 필요한 답만 돌려줘요.

완벽하진 않아요. 가끔 설정 관련 질문에서 헷갈리기도 하고요. 그래도 예전보다는 훨씬 나아졌어요.

핵심은 이거예요.

툴 20개에서 21번째 툴을 추가하는 대신, 서브에이전트와 Progressive Disclosure로 기능을 확장했다.

툴이 하나 늘어날 때마다 모델이 매번 "이걸 써야 하나, 저걸 써야 하나"를 고민해야 해요. 불필요한 툴은 오히려 노이즈가 될 수 있어요.

결국, 예술이지 공식이 아니다

엄격한 규칙을 기대했다면 미안해요. Anthropic도 그런 건 없다고 해요.

Claude Code 팀이 1년 동안 배운 건 이거예요.

그리고 이 모든 걸 알려면 한 가지가 필요해요.

에이전트처럼 보는 법을 배우는 것.

자주 실험하고, 출력을 꼼꼼히 읽고, 새로운 시도를 해보는 것. 그게 전부예요.

아직도 정답은 없어요. Anthropic도 지금도 계속 실험 중이고요.

그래서 AI 에이전트 개발이 어렵지만 또 흥미로운 이유가 아닐까요.