도구 인터페이스 설계

지난 장에서 우리는 에이전트가 어디에서 일하는가를 보았다. 이제 한 걸음 더 들어가 보자. 작업장이 준비되었다고 해서 바로 일이 잘되는 것은 아니다. 망치 손잡이가 미끄럽고, 드라이버 규격이 뒤섞여 있고, 버튼 이름이 죄다 비슷하면 숙련공도 실수한다. 하물며 언어 모델이라면 더 말할 것도 없다.

에이전트에게 도구를 준다는 것은 단순히 기능을 붙이는 일이 아니다. 모델이 행동할 수 있는 문법을 설계하는 일이다. 그래서 도구 인터페이스는 부가 기능이 아니라 성능 그 자체에 가깝다. 프롬프트가 아무리 좋아도, 도구가 애매하면 에이전트는 머뭇거리거나 엉뚱한 버튼을 누른다.

도구 인터페이스가 곧 성능인 이유

많은 팀이 에이전트 성능을 모델 탓으로만 돌린다. 그런데 실제 운영에서는 종종 다른 장면이 벌어진다. 모델은 꽤 괜찮은데, 도구 이름이 모호해서 잘못 고른다. 필요한 인자가 너무 복잡해서 호출을 포기한다. 결과가 제각각이라 다음 단계가 흔들린다. 결국 문제는 추론이 아니라 인터페이스다.

좋은 도구는 세 가지 특징을 가진다. 무엇을 하는지 분명하고, 입력이 단순하며, 출력이 예측 가능하다. 이 세 가지가 갖춰질수록 모델은 더 쉽게 고르고, 더 안정적으로 호출하고, 더 자연스럽게 결과를 조합한다.¹ 에이전트 시스템 관점에서도 도구 스키마, 실행 로직, 메시지 처리, 검증은 핵심 구성 요소로 다뤄진다.²

쉽게 말해 이렇다. 같은 재능의 직원에게도 "알아서 처리해"라고 말하는 것보다 "이 양식에 고객 ID를 넣고 조회 버튼을 누른 뒤, 상태와 금액만 가져와"라고 말하는 편이 훨씬 덜 흔들린다. 모델도 마찬가지다.

모델은 도구를 실행하지 않고, 실행을 제안한다

여기서 꼭 분리해서 봐야 할 점이 있다. 모델은 도구를 직접 실행하는 존재가 아니다. 보통은 어떤 도구를 어떤 인자로 호출할지 제안하고, 실제 실행은 애플리케이션 서버나 하네스가 담당한다.³⁴

이 구분이 중요한 이유는 아주 현실적이다. 모델이 JSON을 예쁘게 만들었다고 해서 그 요청이 곧바로 안전하거나 올바른 것은 아니다. 형식은 맞지만 권한이 없을 수 있고, 스키마는 맞지만 비즈니스 규칙에는 어긋날 수 있다. 그래서 좋은 도구 인터페이스는 단순히 "모델이 부르기 쉬운 함수"가 아니라, 모델이 제안하고 시스템이 검증할 수 있는 계약서여야 한다.

즉, 도구 설계의 핵심은 똑똑한 모델을 더 믿는 데 있지 않다. 오히려 모델이 흔들려도 시스템이 버틸 수 있게 만드는 데 있다.

도구는 다 같은 도구가 아니다

에이전트가 쓰는 도구는 겉으로는 모두 "툴"이지만 성격이 꽤 다르다. 형태가 다르면 실패 방식도 달라지고, 설명 방식도 달라진다.

• API·함수 호출 도구는 가장 구조적이다. 이름, 파라미터, 반환 형식이 명확해서 안정성이 높다. 가능하면 가장 먼저 고려할 형태다.

• CLI 도구는 강력하다. 이미 있는 명령줄 생태계를 그대로 활용할 수 있기 때문이다. 대신 너무 넓게 열어두면 모델에게 공구함이 아니라 열쇠 꾸러미를 통째로 준 셈이 된다.

• 브라우저 도구는 사람용 인터페이스를 대신 다루는 도구다. API가 없거나 실제 화면 확인이 필요할 때 유용하지만, 로그인 상태와 화면 구조 변화에 민감하다.

• 코드 실행기는 계산, 데이터 가공, 분석, 테스트 실행에 강하다. 모델이 말로 어림짐작하지 않고 실제 계산을 하게 만든다는 점에서 매우 중요하다.

• 검색·조회형 도구는 읽기 중심 작업에 잘 맞는다. 최신 정보 확인이나 사내 문서 검색처럼 모델의 기억을 보강하는 역할을 한다.

설계 원칙은 단순하다. 가장 덜 열린 도구로, 원하는 결과를 낼 수 있을 때가 가장 좋다. 고객 주문을 조회하는데 굳이 브라우저를 띄울 필요는 없다. 테스트를 한 번 돌리면 되는 일을 범용 셸로 열 필요도 없다. 도구가 강력할수록 인터페이스는 더 좁아져야 한다.

API와 함수 호출 도구는 가장 좋은 기본형이다

가능하다면 에이전트 도구는 함수 호출 형태로 정리하는 편이 좋다. 함수 이름이 있고, 입력 스키마가 있고, 반환 형식이 정해져 있기 때문이다. 모델은 이런 구조를 특히 잘 다룬다.²⁴

이때 중요한 것은 함수 하나가 너무 많은 일을 하지 않게 만드는 것이다. 예를 들어 manage_order처럼 거대한 만능 함수 하나를 두는 것보다, get_order, list_refundable_orders, cancel_order_request처럼 의도가 분리된 함수 여러 개가 보통 더 안정적이다.¹

그 이유는 간단하다. 모델이 해야 하는 선택이 선명해지기 때문이다. 사용자의 질문이 "환불 가능한 주문만 보여줘"라면, list_refundable_orders는 거의 직관적으로 맞는 후보가 된다. 반면 manage_order(action, options, filters, mode...) 같은 함수는 사람도 잠깐 멈춘다.

함수 호출 도구를 설계할 때는 특히 스키마가 중요하다. 필수 필드는 꼭 좁히고, 선택지는 enum으로 제한하고, 불필요한 자유 입력은 줄여야 한다. 최근 함수 호출 구현 가이드들이 strict 모드와 additionalProperties: false 같은 제약을 강조하는 이유도 여기에 있다.⁴ 모델이 자유롭게 상상할 공간을 줄일수록 시스템은 덜 흔들린다.

CLI 도구는 래핑하지 않으면 너무 넓다

CLI는 에이전트에게 엄청난 생산성을 준다. 이미 세상에는 훌륭한 명령줄 도구가 너무 많다. git, pytest, ffmpeg, psql, curl, jq만 잘 다뤄도 할 수 있는 일이 폭발적으로 늘어난다.

문제는 바로 그 점이다. 너무 강하다.

그래서 실무에서는 원시 셸을 그대로 열기보다, 목적별 도구로 감싸는 편이 낫다. 예를 들어 에이전트가 직접 bash 안에서 아무 명령이나 치게 하기보다 run_tests, format_codebase, list_changed_files, export_csv_summary 같은 도구를 제공하는 방식이다. 이렇게 하면 모델은 해야 할 일을 더 잘 이해하고, 시스템은 허용 범위를 더 쉽게 통제할 수 있다.

특히 CLI는 출력도 설계해야 한다. 셸 명령의 표준 출력은 사람에게는 익숙하지만 모델에게는 종종 너무 시끄럽다. 경고, 색상 코드, 장황한 로그, 진행률 바가 한꺼번에 섞이면 다음 단계 판단이 어려워진다. 그러므로 가능하다면 CLI 도구도 구조화된 결과 요약을 돌려주는 편이 좋다. 예를 들면 전체 로그 대신 exit_code, summary, artifacts, truncated_stdout 같은 필드로 정리하는 방식이 실용적이다.

브라우저 도구는 '눈'이자 동시에 '위험한 손'이다

브라우저 도구는 조금 특별하다. API가 없는 웹앱을 다룰 수 있고, 실제 화면을 보고 검증할 수 있으며, 로그인된 서비스까지 연결할 수 있다. 그래서 코딩 에이전트, QA 에이전트, 업무 자동화 에이전트에서 매우 강력하다.⁶

하지만 브라우저 도구는 하나로 뭉뚱그려 설계하면 금방 문제가 생긴다. 실제 브라우저 세션을 공유하는 도구와, 깨끗한 자동화 브라우저를 띄우는 도구와, 헤드리스 CI용 도구는 서로 완전히 다른 성격을 가진다.⁶⁷

예를 들어 실제 사용자 세션을 공유하는 브라우저는 Gmail, Notion, 사내 SaaS처럼 로그인 상태가 필요한 작업에 강하다. 반면 격리된 자동화 브라우저는 반복 테스트나 크롤링에 더 적합하다. 둘을 같은 도구처럼 다루면 실패 이유가 불분명해진다. 어떤 작업은 인증이 안 돼서 막히고, 어떤 작업은 실제 세션을 건드려서 위험해진다.

브라우저 도구를 설계할 때는 최소한 다음을 분명히 해야 한다.

• 이 도구가 실제 로그인 세션을 쓰는지, 격리된 새 브라우저를 쓰는지

• 읽기 중심인지, 클릭·입력·제출 같은 쓰기 행동까지 허용하는지

• 로그인, CAPTCHA, 2단계 인증이 나오면 자동으로 멈추는지

• 에이전트가 현재 무엇을 보고 무엇을 하려는지 사용자에게 드러나는지

공식 브라우저 연동 문서에서도 로그인 페이지나 CAPTCHA를 만나면 자동으로 멈추고 사람 개입을 요청하는 흐름을 중요하게 다룬다.⁶ 이건 편의 기능이 아니라 인터페이스 원칙이다. 브라우저는 눈으로 보기 좋은 장난감이 아니라, 실제 계정과 실제 버튼이 걸린 공간이기 때문이다.

코드 실행기는 말보다 계산을 믿게 만든다

모델은 계산을 설명할 수는 있어도, 계산을 항상 정확히 하지는 못한다. 그래서 분석형 에이전트에서 코드 실행기는 거의 필수에 가깝다. 숫자를 더하고, 표를 집계하고, 통계를 계산하고, 파일을 변환하는 일은 말로 하는 것보다 실제 코드로 하는 편이 훨씬 낫다.²

다만 코드 실행기 역시 인터페이스가 중요하다. 무턱대고 "파이썬 실행 가능"만 열어두면, 에이전트는 계산보다 환경 문제와 라이브러리 문제에 더 많은 토큰을 쓴다. 반대로 실행 가능 언어, 허용 패키지, 시간 제한, 파일 입출력 위치, 네트워크 가능 여부가 분명하면 훨씬 안정적이다.

좋은 코드 실행기는 모델에게 자유를 주되, 자유의 모양을 정해준다. 예를 들어 "CSV 파일은 inputs에 있고, 결과 이미지는 outputs에 저장하며, 실행 시간은 30초 이내"처럼 경계를 주면 모델은 훨씬 덜 헤맨다. 작업장은 앞 장에서 만들었고, 코드 실행기는 그 작업장 안에서 쓰는 정해진 공구가 되는 셈이다.

좋은 도구는 한 가지 일을 잘한다

도구 설계에서 자주 보는 실패는 "일단 다 넣자"는 유혹이다. 하나의 도구로 여러 업무를 처리하게 만들면 구현은 편해 보인다. 하지만 모델 입장에서는 선택 기준이 흐려진다.

예를 들어 calendar_action 하나에 조회, 추천, 초안 작성, 실제 생성, 취소까지 모두 넣어두면 어떻게 될까. 사용자가 "다음 주 수요일 오후 가능한 시간 찾아줘"라고 말했을 때 모델은 조회만 해야 하는지, 초안을 만들어야 하는지, 실제 일정을 생성해야 하는지 헷갈릴 수 있다.

반대로 다음처럼 나누면 훨씬 선명하다.

• find_free_slots

• draft_meeting_invite

• create_calendar_event

이 구조의 장점은 이름만 봐도 드러난다. 조회와 생성이 분리되고, 초안과 실제 실행도 분리된다. 사용자의 의도와 도구의 책임이 자연스럽게 맞물린다.

좋은 도구 이름은 보통 동사 + 대상으로 구성된다. get_weather, search_documents, send_email_draft처럼 말이다. 반대로 helper, process, do_task 같은 이름은 모델에게 거의 힌트를 주지 못한다.¹

도구 설명은 사용 설명서가 아니라 라우팅 힌트다

도구 설명은 사람을 위한 문서이면서 동시에 모델을 위한 길안내다. 설명이 좋으면 모델은 맞는 도구를 고를 확률이 올라간다. 설명이 나쁘면 좋은 모델도 흔들린다.¹⁴

좋은 설명에는 보통 네 가지가 들어간다.

• 언제 써야 하는가

• 언제 쓰면 안 되는가

• 무엇을 돌려주는가

• 어떤 제약이 있는가

예를 들어 "상품 검색 함수"라고만 쓰는 것은 부족하다. "카탈로그에서 상품을 검색한다. 사용자가 상품 찾기, 가격 비교, 재고 확인을 요청할 때 사용한다. 상품 ID, 이름, 가격, 재고 상태를 반환한다. 주문 생성이나 결제에는 사용하지 않는다." 정도는 되어야 모델이 훨씬 덜 헷갈린다.

파라미터 설명도 마찬가지다. location: string보다 "도시 이름, 예: 서울, Tokyo, New York"이 낫다. status보다 "허용값: pending, shipped, delivered"가 낫다.¹⁴ 모델은 추측의 기계라기보다 패턴의 기계에 가깝다. 힌트가 선명할수록 행동도 선명해진다.

입력은 좁게, 출력은 안정적으로

도구 입력은 모델이 사용자의 말에서 합리적으로 추출할 수 있는 정도여야 한다.¹ 사용자가 "도쿄 날씨 알려줘"라고 했는데 도구가 city, country_code, timezone, language, units, provider, cache_policy까지 요구한다면, 그건 모델이 아니라 설계가 무리한 것이다.

입력 설계에서는 세 가지가 특히 중요하다.

첫째, 필수 필드는 정말 필요한 것만 필수로 둔다.
둘째, 선택지는 가능한 한 enum으로 좁힌다.
셋째, 기본값은 서버나 도구 쪽에서 책임질 수 있으면 그쪽에서 책임진다.

출력은 더 중요하다. 출력이 흔들리면 다음 단계 전체가 흔들리기 때문이다. 좋은 출력은 보통 자연어보다 구조화된 데이터에 가깝다. 예를 들어 문서 검색 도구라면 긴 요약문 하나보다 documents, source_ids, snippets, retrieved_at 같은 필드가 더 유용하다. 최종 자연어는 모델이 만들면 된다. 도구는 재료를 안정적으로 돌려주는 편이 낫다.

오류 표면은 친절함보다 분해 가능성이 중요하다

에이전트 도구에서 아주 자주 보이는 나쁜 오류 메시지가 있다. 바로 Tool failed다. 이 문장은 거의 아무 도움도 주지 않는다. 왜 실패했는지, 다시 해도 되는지, 사람 확인이 필요한지 전혀 알 수 없기 때문이다.

좋은 도구 인터페이스는 오류도 구조적으로 돌려줘야 한다. 최소한 다음 정도는 구분하는 편이 좋다.

• 입력이 잘못된 것인지

• 권한이 없는 것인지

• 외부 서비스가 잠시 죽은 것인지

• 리소스가 없는 것인지

• 비즈니스 규칙상 불가능한 것인지

• 사람 확인이 필요한 것인지

예를 들면 VALIDATION_ERROR, AUTH_REQUIRED, RATE_LIMITED, NOT_FOUND, CONFLICT, UPSTREAM_TEMPORARY_ERROR 같은 코드가 있으면 모델은 대응 전략을 다르게 가져갈 수 있다. 입력 오류라면 사용자의 정보를 다시 묻고, 일시적 장애라면 재시도하고, 승인 필요라면 사람에게 넘기면 된다.

좋은 오류 응답은 보통 세 층으로 구성된다.

• 기계가 읽는 오류 코드

• 사람이 이해하는 짧은 설명

• 다음 행동을 위한 권장 조치

예를 들어 "캘린더 이벤트 생성 실패"보다 "CONFLICT: 같은 시간대에 잠긴 일정이 있어 생성할 수 없음. 다른 시간대를 제안하거나 사용자 승인 후 덮어쓰기 요청"이 훨씬 낫다. 이건 예의의 문제가 아니라 복구의 문제다.

읽기 도구와 쓰기 도구는 같은 얼굴을 하면 안 된다

이 장의 핵심이 권한 설계는 아니지만, 도구 인터페이스 단계에서 미리 구분해야 할 것이 있다. 바로 읽기와 쓰기의 분리다.

조회 도구와 상태 변경 도구가 너무 비슷하면 모델은 경계를 헷갈리기 쉽다.³ get_customer_info와 update_customer_info는 이름만 봐도 다르지만, customer_action 하나로 묶여 있으면 문제가 커진다. 특히 이메일 발송, 결제 승인, 일정 생성, 문서 삭제처럼 결과가 남는 작업은 더 그렇다.

그래서 좋은 인터페이스는 읽기와 쓰기를 서로 다른 성격으로 보이게 한다. 이름, 설명, 승인 방식, 반환 형식까지 구분되면 더 좋다. 읽기는 탐색이고, 쓰기는 결정이다. 둘은 같은 버튼에 담기에는 너무 성격이 다르다.

도구가 많아질수록 선택 품질은 떨어진다

현실의 에이전트는 시간이 갈수록 도구가 늘어난다. 처음에는 세 개였는데, 어느새 열다섯 개가 된다. 그러다 보면 팀은 묘한 착각에 빠진다. "도구가 많아졌으니 더 똑똑해졌겠지." 실제로는 반대일 때가 많다.

함수 선택과 파라미터 생성은 생각보다 어려운 문제다. 특히 후보 API가 많고, 여러 단계 호출과 중첩 의존성이 생기면 정확도가 눈에 띄게 흔들린다.⁵ 즉, 에이전트가 실패하는 이유는 도구가 없어서가 아니라 너무 많고 너무 비슷해서일 수 있다.

그래서 실전에서는 두 가지를 자주 한다.

첫째, 한 번에 보여주는 도구 수를 줄인다. 작업 종류에 따라 도구 집합을 나눠서 주는 것이다.
둘째, 정말 비슷한 도구는 과감히 합치거나 없앤다. 단, 읽기와 쓰기를 섞는 식의 위험한 통합은 피한다.

좋은 하네스는 모델에게 세상의 모든 공구를 들이밀지 않는다. 지금 이 일에 필요한 공구함만 건넨다.

다중 도구 체이닝은 인터페이스가 더 중요해진다

도구가 하나일 때는 설명이 조금 부족해도 어떻게든 버틸 수 있다. 하지만 두 개, 세 개가 연결되기 시작하면 인터페이스 품질이 급격히 중요해진다. 첫 번째 도구의 출력이 두 번째 도구의 입력이 되기 때문이다.¹⁴

예를 들어 회의 준비 에이전트가 있다고 해보자. 캘린더에서 일정을 읽고, 참석자 회사를 검색하고, 요약 메모를 만든다. 이 흐름에서 캘린더 도구가 참석자 정보를 제멋대로 돌려주거나, 검색 도구가 출처 없는 긴 문단만 반환하면 다음 단계가 금방 흔들린다.

그래서 체이닝이 예상되는 도구는 특히 다음 도구가 쓰기 쉬운 결과를 돌려줘야 한다. 사람이 읽기 좋은 결과와, 시스템이 이어받기 좋은 결과는 종종 다르다. 도구는 후자를 우선하고, 최종 문장은 모델이 다듬는 편이 낫다.

도구 호출 로그도 인터페이스의 일부다

도구 인터페이스를 설계할 때 로그를 나중 문제로 미루기 쉽다. 하지만 실제로는 로그까지 포함해서 인터페이스다. 왜냐하면 에이전트가 도구를 잘못 쓰는 순간, 우리가 보고 싶은 것은 대개 모델의 장황한 생각이 아니라 어떤 도구를 왜 골랐고 어떤 인자로 호출했고 무엇이 돌아왔는가이기 때문이다.

최소한 다음은 남기는 편이 좋다.

• 도구 이름

• 검증 후 실제 사용된 인자

• 호출 시각과 종료 시각

• 성공·실패 상태

• 오류 코드와 재시도 여부

• 요약된 결과와 생성된 산출물 위치

이 로그는 운영용 기록일 뿐 아니라, 나중에 평가 데이터가 되기도 한다. 어떤 질문에서 어떤 도구 선택이 자주 틀리는지, 어떤 파라미터가 자주 누락되는지, 어떤 오류가 반복되는지 볼 수 있기 때문이다. 에이전트 품질 개선은 결국 이런 흔적 위에서 이뤄진다.

작은 예시 하나로 보는 차이

같은 기능을 두 방식으로 설계해보자.

나쁜 예시는 이렇다. handle_customer_request(type, payload)
이 도구는 조회도 하고, 수정도 하고, 환불도 하고, 메일도 보낸다. 설명은 "고객 요청 처리"다.

좋은 예시는 이렇다. get_customer_profile, list_open_orders, draft_refund_response, submit_refund_request
각 도구는 책임이 분리되어 있고, 조회와 초안과 실제 제출이 단계별로 나뉜다.

둘 중 어느 쪽이 모델에게 더 쉬운지는 굳이 오래 고민할 필요가 없다. 사람에게 쉬운 것이 모델에게도 대개 쉽다. 반대로 사람도 설명서를 다시 읽어야 하는 도구는 모델도 자주 비틀어진다.

도구 인터페이스 설계 체크리스트

도구를 하나 추가하기 전에, 적어도 이 질문은 해보는 편이 좋다.

• 이 도구는 정말 한 가지 일을 하는가

• 이름만 보고도 용도가 드러나는가

• 입력은 사용자의 말에서 무리 없이 뽑아낼 수 있는가

• 출력은 다음 단계가 안정적으로 쓸 수 있는 구조인가

• 실패했을 때 원인과 다음 행동을 구분해서 돌려주는가

• 비슷한 도구와 경계가 명확한가

• 읽기와 쓰기가 섞여 있지 않은가

• 원시 인터페이스를 더 좁은 목적형 도구로 감쌀 수 없는가

이 질문들에 답이 흐리다면, 모델을 바꾸기 전에 도구부터 다시 설계하는 편이 빠르다.

도구는 기능 목록이 아니라 작업 방식이다

도구 설계를 잘못하면 에이전트는 똑똑한 척하면서 자꾸 엉뚱한 공구를 집는다. 도구 설계를 잘하면 같은 모델도 훨씬 차분하고 안정적으로 일한다. 그래서 도구 인터페이스는 단순한 연결 작업이 아니다. 모델에게 무엇을 할 수 있느냐를 알려주는 동시에, 어떻게 행동해야 하느냐를 가르치는 구조다.

프롬프트가 에이전트의 말투를 정한다면, 도구 인터페이스는 에이전트의 손놀림을 정한다. 결국 제품 품질은 말보다 손에서 드러난다.

다음 장에서는 이 손과 발에 어디까지 허용할 것인가를 다룬다. 같은 도구라도 권한과 승인 구조가 달라지면 완전히 다른 제품이 되기 때문이다.

참고

¹Designing Simple Tool Interfaces: A Complete Guide to Connecting AI Agents with External Functions

²ai-agents-for-beginners  12 Lessons to Get Started Building AI Agents

³[AI] Function Calling의 정석: 외부 API와 LLM을 안전하게 연결하는 구조

⁴LLM Function Calling: Complete Implementation Guide (2026)

⁵CallNavi, A Challenge and Empirical Study on LLM Function Calling and Routing

⁶Use Claude Code with Chrome (beta)

⁷Three Ways Claude Code Can Use a Browser