Skip to content
Published on

도구 표면 설계 — 스키마 한 줄이 성공률을 움직입니다

🇰🇷KO🇺🇸EN🇯🇵JA🇨🇳ZH
Split View필사 모드✨Start Quiz
공유하기
Authors

도구를 늘렸는데 성공률이 떨어졌습니다

에이전트에게 도구를 다섯 개 더 붙였더니 과제 성공률이 오히려 내려갔다고 해 보겠습니다. 구성한 예시지만, 도구 표면을 넓혀 본 팀이라면 방향이 낯설지 않을 것입니다. 이유는 두 겹입니다. 도구 스키마는 매 턴 컨텍스트 예산을 먹고, 비슷한 도구가 많을수록 선택이 흔들립니다. 모델이 더 많은 일을 할 수 있게 되는 것과, 지금 이 과제를 더 잘 끝내는 것은 다른 문제입니다.

도구 표면이라는 말은 그래서 유용합니다. 도구 하나하나가 아니라, 모델이 마주하는 인터페이스 전체가 설계 대상이라는 뜻이기 때문입니다. Anthropic의 에이전트 구축 가이드는 이것을 에이전트-컴퓨터 인터페이스라 부르고, 사람의 UI만큼 공들이라고 권합니다. 자체 SWE-bench 작업에서 프롬프트보다 도구 최적화에 더 많은 시간을 썼다는 회고가 그 권고의 무게를 보여 줍니다.

도구 수의 저주: 전부 노출 대 큐레이션

가장 먼저 정할 것은 개수입니다. 있는 도구를 전부 노출하는 방식은 준비가 쉽지만, 스키마만으로 예산이 줄고 유사 도구 사이의 오선택이 늘어납니다. 반대로 이 과제에 쓰이는 것만 추려 노출하는 큐레이션이 대부분의 작업에서 기본값이 되어야 합니다. 여력이 있다면 그 위에 이 과제 전용 도구를 하나 만들어 얹는 선택지도 있습니다. 전용 도구는 만들고 유지하는 비용이 들지만, 여러 호출을 한 번에 줄입니다.

Anthropic의 도구 작성 가이드가 권하는 통합이 그 연장선에 있습니다. 사용자 목록 조회, 일정 목록 조회, 일정 생성을 각각 도구로 주는 대신, 내부에서 그 단계를 처리하는 일정 잡기 도구 하나로 합치는 식입니다. 도구 수가 줄면 스키마 비용과 오선택과 호출 왕복이 함께 줄어듭니다.

이름과 설명이 인터페이스입니다

모델은 코드를 보지 못하고 이름과 설명만 봅니다. 그래서 설명 한 줄이 동작을 바꿉니다. 같은 가이드는 서비스와 리소스 단위로 이름을 묶는 네임스페이싱을 권합니다. asana_search와 jira_search처럼 접두어가 소속을 말해 주면, 비슷한 검색 도구가 여럿 있어도 모델이 덜 헷갈립니다.

# 나쁜 예 — 무엇을 언제 쓰는지 모델이 추측해야 합니다
- name: proc2
  description: '프로세스 유틸'

# 좋은 예 — 언제 쓰고, 언제 다른 도구를 쓸지가 설명에 있습니다
- name: code_search_symbol
  description: '저장소에서 심볼의 정의 위치를 찾는다. 파일 본문 검색에는 code_grep을 쓸 것.'

좋은 설명의 기준은 사람 신입에게 주는 온보딩 문서와 같습니다. 무엇을 하는 도구인지, 언제 쓰는지, 언제 쓰면 안 되는지, 반환이 어떻게 생겼는지. 설명이 좋아질수록 프롬프트에서 도구 사용법을 설명하던 문단이 사라집니다.

파라미터 설계: 실수를 구조로 막습니다

파라미터는 모델이 틀릴 수 있는 지점을 줄이는 방향으로 설계합니다. Anthropic 에이전트 가이드는 이것을 제조업의 포카요케에 비유합니다. 실수를 지적하는 대신 실수가 불가능한 구조를 만드는 것입니다. 이를테면 상대 경로와 절대 경로를 모두 받는 파라미터는 작업 디렉터리가 바뀌는 순간 오류의 원천이 되므로, 절대 경로만 받게 좁히면 그 실수 부류가 구조적으로 사라집니다. 식별자도 마찬가지입니다. 의미 없는 UUID를 주고받게 하기보다 사람이 읽는 이름을 쓰게 하면 모델의 정확도가 올라간다는 것이 도구 작성 가이드의 관찰입니다.

실패를 어떻게 돌려줄 것인가

도구는 실패합니다. 설계 대상은 실패 자체가 아니라 실패가 모델에게 돌아가는 형식입니다. 예외 문자열과 스택트레이스를 그대로 돌려주면, 모델은 원인을 모른 채 같은 호출을 반복하기 쉽습니다. 실패 원인과 지금 시도 가능한 대안을 구조화해 돌려주면 다음 호출이 달라집니다.

{
  "error": "file_not_found",
  "path": "src/pay/handler.py",
  "hint": "이 저장소의 소스 루트는 services/ 입니다.",
  "try_next": ["list_dir services/pay", "code_search_symbol handler"]
}

이 형식은 4편에서 다룰 재시도 정책과 직접 얽힙니다. 원인이 돌아오지 않는 재시도는 같은 실패의 반복 구매이고, 대안이 돌아오는 재시도는 탐색이 됩니다. 재시도 상한을 정하기 전에 실패 반환 형식부터 고치는 것이 순서상 먼저입니다.

응답도 표면입니다: 토큰 효율

도구가 돌려주는 응답은 그대로 컨텍스트 예산에서 빠져나갑니다. 그래서 도구 작성 가이드는 페이지네이션, 범위 지정, 필터링, 합리적 기본값의 잘라내기를 도구 쪽 책임으로 둡니다. 파일 4천 줄을 통째로 돌려주는 읽기 도구보다, 기본 200줄에 범위 파라미터를 받는 읽기 도구가 표면으로서 낫습니다. 잘라냈다면 잘라냈다는 사실과 더 좁혀 검색하는 방법을 응답에 함께 적어 주는 것까지가 설계입니다.

도구도 평가 대상입니다

도구 표면은 만들고 끝나는 것이 아니라 평가로 다듬는 대상입니다. 같은 가이드가 권하는 루프는 단순합니다. 프로토타입을 만들고, 현실적인 과제로 평가를 돌리고, 에이전트가 남긴 기록을 읽으며 어디서 헤맸는지 찾고, 도구를 고쳐 다시 잽니다. 도구 하나의 설명 문구를 바꾸는 것도 하네스 변경이므로, 7편에서 다룰 하네스 지문에 잡혀야 하는 변경입니다. 어느 표면이 나은지를 판정하는 것은 결국 평가자이고, 그 평가자의 신뢰도가 5편의 주제입니다.

직접 연습하기

하네스 엔지니어링 RPG에서는 최소 3개, 과제별 선별 8개, 선별에 전용 도구를 얹은 구성, 전부 노출 21개의 네 가지 도구 표면을 어느 시나리오에서든 끼워 볼 수 있습니다. 전부 노출이 스키마 비용으로 무너지는 시나리오와, 최소 구성이 우회 비용으로 무너지는 시나리오를 모두 겪어 보면 큐레이션이 기본값인 이유가 몸에 남습니다.

참고 자료

Discuss on Twitter • View on GitHub