LLM 도구(tool)란? 에이전트 하네스 Pi로 이해하는 툴 정의와 실행

핵심 메시지

• LLM 단독은 질문에 답만 할 수 있는 '병 속의 똑똑한 뇌'이며, 도구가 있어야 파일 읽기·수정·명령 실행 같은 실제 행동으로 외부 환경에 닿을 수 있다.
• 하네스는 도구·서브에이전트·컨텍스트·메모리·시스템 프롬프트를 아우르는 생태계이며, Claude Code나 공개 코드베이스를 가진 오픈소스 Pi가 그 예다.
• 현대 코딩 하네스는 read·write·edit·bash·grep·find·ls 7개 툴을 기본으로 탑재하며, 개발자가 직접 작성하지 않아도 된다.
• 툴 정의는 모델이 읽는 절반(이름·라벨·설명·파라미터)과 실제로 실행하는 절반(함수)으로 나뉘며, 모델은 실행 함수를 절대 보지 못한다.
• 설명문(description)이 곧 '모델의 진짜 API'라서, 길고 분명하게 작성해야 모델이 어떤 툴을 쓸지 헷갈려 환각하는 일을 줄일 수 있다.

쉽게 이해하기

영상은 '도구란 무엇인가'라는 세 단어짜리 면접 질문이 실제로는 여러 층위의 깊이를 가진다고 말한다. 먼저 하네스 개념을 짚는데, 하네스란 LLM을 둘러싼 생태계로 도구·서브에이전트·컨텍스트·메모리·시스템 프롬프트 관리를 모두 포함한다. Claude Code가 대표적인 하네스이며, 강연자는 약 7만 개의 스타를 가진 오픈소스 코딩 하네스 Pi를 예로 든다. Pi는 코드베이스가 전부 공개돼 있어 툴이 어떻게 정의·구현되는지 직접 확인할 수 있다는 점에서 교재로 삼았다.

핵심 비유는 '병 속의 뇌'다. 언어 모델은 질문에 답할 수는 있어도 스스로 외부 세계에 손을 뻗어 행동하지는 못한다. 도구를 붙이는 순간 비로소 파일을 읽고 수정하고, 명령을 실행하고, 검색을 하는 실제 기계가 된다. Pi를 비롯한 현대 코딩 하네스가 기본 제공하는 네이티브 툴은 read·write·edit·bash·grep·find·ls 일곱 가지로, 사실상 터미널에서 쓰는 동사(파일 열기·바꾸기·명령 실행·검색·목록)와 같다.

툴 정의는 두 절반으로 나뉜다. 첫 절반은 모델이 읽는 부분으로 이름·라벨·설명·파라미터를 담고, 둘째 절반은 실제로 실행되는 함수다. 강연자는 설명문이 '모델의 진짜 API'라고 강조한다. 모델은 실행 함수를 결코 보지 못하고 오직 설명만 보고 툴을 고르기 때문이다. 실제 read 툴의 설명은 텍스트·이미지 지원, 출력 잘림, 기본 2,000줄·이미지 50KB 한도, 그리고 큰 파일을 offset·limit으로 나눠 읽는 페이징까지 다섯 줄 안에 간결하게 담아낸다.

모델이 툴을 고른 뒤에는 실행 단계로 넘어간다. 실행에는 다섯 가지가 필요하다. 어떤 요청에 어떤 툴이 대응하는지 식별하는 tool call ID, 경로·offset·limit 같은 params, 사용자가 중단(Ctrl+C)하면 취소하는 abort용 signal, 실행 중 부분 결과를 UI로 흘려보내는 onUpdate 콜백, 그리고 모델의 이미지 지원 여부 등을 담은 context다. 툴 선택은 설명문에 좌우되는 비결정적 과정이지만, 실행은 결국 함수를 돌리는 완전히 결정론적인 과정이다.

결국 모든 에이전트는 사고 → 행동 → 관찰의 루프를 돌며, 행동을 담당하는 것이 바로 툴이다. 강연자는 execution mode(순차/병렬)나 render 관련 항목 같은 선택 필드도 짧게 소개한다. 마무리로는 기초 개념을 바닥부터 이해하고 최신 라이브러리의 실제 구현을 뜯어보며 배우라고 조언하며, 면접에서도 답을 툭 던지지 말고 Pi 같은 예시로 이야기를 풀어 대화를 이끌라고 권한다.

주요 인사이트

• 툴 설명문이 툴 선택의 유일한 근거이므로, 설명이 모호하면 모델이 어떤 툴을 쓸지 몰라 환각을 일으키는 주요 원인이 된다. 그래서 Pi의 내장 툴 설명은 짧지 않고 길고 지시적으로 작성돼 있다.
• read 툴의 페이징은 2,000줄에서 무작정 잘라내는 것이 아니라 offset을 옮겨 가며 청크 단위로 큰 파일 전체를 읽어 나가는 구조다.
• 툴 실행 자체는 그저 함수 호출이라 완전히 결정론적이며, 비결정성은 오직 '어떤 툴을 부를지' 고르는 설명문 기반의 선택 단계에만 존재한다.
• AI는 개념을 대신 형성해 주지 못하므로, 오래 앉아 한 곳을 파고드는 독립적 사고로 기초 개념과 패턴을 스스로 만들어야 한다는 것이 강연의 핵심 메시지다.

자주 묻는 질문

관련 AI 소식