도구 설계의 예술

ACI: Agent-Computer Interface

HCI(Human-Computer Interaction) 분야는 수십 년간 연구되어 왔지만, Agent와 컴퓨터 간의 상호작용(ACI)은 이제 막 시작되었습니다. 실무 경험에 따르면 도구 설계의 품질이 Agent의 능력 한계를 직접 결정합니다.

핵심 개념: 도구는 Agent와 세계 사이의 계약입니다

전통적인 소프트웨어 개발에서는 사용자 인터페이스(HCI) 설계에 많은 노력을 쏟습니다. 버튼 위치, 문구 작성, 인터랙션 피드백 등을 고민하죠. 그런데 Agent가 시스템의 사용자가 되면, 인터페이스는 곧 도구 정의로 바뀝니다. 도구의 이름, 파라미터, 설명이 바로 Agent의 사용자 인터페이스입니다.

HCI 인간 → 시스템

인간은 버튼, 폼, 메뉴를 통해 시스템과 상호작용합니다. UI 설계 품질이 사용자 경험에 직접 영향을 미칩니다.

사용자가 「날씨 확인」 버튼 클릭 → 시스템이 getWeather("NYC") 호출 → 결과를 사용자에게 반환

결정론적: 동일한 조작 → 동일한 결과

ACI Agent → 시스템

Agent는 도구 정의(이름, 파라미터, 설명)를 통해 시스템과 상호작용합니다. 도구 설계 품질이 Agent 성능에 직접 영향을 미칩니다.

사용자: 「우산 가져가야 하나요?」 → Agent 판단: 날씨 도구가 필요한가? → 먼저 도시를 물어봄 → get_weather(city="上海") 호출 → 종합 판단 후 답변

비결정론적: 동일한 질문 → 다른 호출 경로

"Plan to invest as much effort into your Agent-Computer Interface (ACI) as you would into a Human-Computer Interface (HCI)."

도구와 전통적 API의 근본적 차이

사용자가 「우산 필요하나요?」라고 할 때 Agent의 의사결정 과정

사용자는 어디에 있나요?

대화 기록에 위치가 없으면, Agent가 먼저 「어느 도시에 계신가요?」라고 물어본 뒤 도구 호출 여부를 결정할 수 있습니다.

날씨 도구를 호출해야 하나요?

직전 대화에서 날씨를 이미 조회했다면, Agent는 캐시된 결과로 바로 답변하고 도구 호출을 건너뛸 수 있습니다.

어떤 도구를 호출하나요?

get_weather를 호출할까요, get_forecast를 호출할까요? 현재 날씨 대 미래 예보 — 도구 이름과 설명이 Agent의 선택을 결정합니다.

파라미터를 어떻게 채우나요?

city 파라미터에 「Shanghai」를 넣어야 할까요, 「上海」를 넣어야 할까요? 형식이 명확하지 않으면 Agent가 자주 실수합니다.

전통적 API는 결정론적입니다: 개발자가 getWeather("NYC")를 작성하면 매번 실행 경로가 동일합니다. Agent 도구는 비결정론적입니다: 모델이 언제, 어떻게 사용할지 이해해야 하며, 이는 전적으로 도구 설계 품질에 달려 있습니다.

도구 설계 4원칙

PRINCIPLE 01

모델이 충분히 생각할 수 있는 Token 공간을 확보하세요

모델은 파라미터를 Token 단위로 생성하며, 한번 작성을 시작하면 되돌리기 어렵습니다. 도구 설계는 복잡한 파라미터를 작성하기 전에 단순한 방향성 파라미터를 먼저 작성할 수 있도록 해야 합니다.

나쁜 예: 첫 번째 파라미터에서 500줄 코드 패치 작성 요구
좋은 예: file_path → change_type → content 순으로 작성

PRINCIPLE 02

형식을 모델의 학습 데이터에 맞추세요

모델은 학습 시 대량의 자연어와 일반적인 코드 형식을 접했습니다. 도구 파라미터 형식이 이런 익숙한 패턴에 가까울수록 모델이 실수를 덜 합니다.

나쁜 예: 커스텀 DSL로 파일 변경 사항 설명
좋은 예: 표준 unified diff 형식 사용 — 학습 데이터에서 수없이 보았습니다

PRINCIPLE 03

불필요한 형식 오버헤드를 피하세요

모델에게 줄 수 세기나 JSON 이스케이프 같은 기계적 작업을 시키지 마세요. 모델은 정확한 계수에 약하므로 강요하면 오류만 늘어납니다.

나쁜 예: {"start_line": 15, "end_line": 23}과 같이 정확한 줄 번호 요구
좋은 예: 고유한 컨텍스트 문자열로 대상 위치 매칭

PRINCIPLE 04

Poka-yoke（포카요케, 실수 방지 설계）

도요타 생산 시스템에서 유래한 개념으로, 설계를 바꿔 실수가 일어나기 어렵게 만드는 것입니다. 모델이 실수하지 않길 바라기보다, 도구 자체를 잘못 사용하기 어렵게 설계하세요.

나쁜 예: 상대 경로를 허용하는 파라미터 (모델이 작업 디렉터리를 자주 혼동)
좋은 예: 절대 경로만 허용하여 근본적으로 모호함 제거

실제 사례: SWE-bench에서의 변경 사항

파일 경로: 상대 경로 vs 절대 경로

BEFORE -- 상대 경로

{ "tool": "edit_file", "path": "src/utils/helper.py", "content": "..." }

Agent가 작업 디렉터리를 자주 혼동하여 잘못된 파일을 편집하거나 파일을 찾지 못하는 오류 발생

AFTER -- 절대 경로

{ "tool": "edit_file", "path": "/repo/src/utils/helper.py", "content": "..." }

경로 모호성 제거, 도구 호출이 빈번한 오류에서 거의 완벽한 수준으로 개선

이 변경의 코드량은 매우 작았습니다. 단순히 파라미터가 상대 경로를 받던 것을 절대 경로만 요구하도록 바꾼 것뿐입니다. 하지만 효과는 엄청났습니다: 파라미터 설계 하나의 변경으로 전체 Agent의 신뢰성이 크게 향상되었습니다. 이것이 포카요케의 힘입니다.

도구 설명 작성의 기술

업계 최선 실무에 따르면 도구 설명은 똑똑하지만 컨텍스트가 없는 주니어 개발자를 위한 문서를 작성하듯 써야 합니다. 이 개발자는 아무것도 모르지만 이해력이 뛰어나므로, 모든 전제 조건을 알려줘야 합니다.

좋은 도구 설명에 포함되어야 할 내용

사용 예시: 구체적인 입출력 샘플로 모델이 한눈에 이해할 수 있게

엣지 케이스 처리: 입력이 비어 있으면 어떻게 하나요? 결과가 없으면 무엇을 반환하나요?

입력 형식 요구사항: 날짜는 ISO 8601인가요, 타임스탬프인가요? 경로는 절대인가요, 상대인가요?

다른 도구와의 차이: 「코드는 search_code로, 파일명은 search_files로 검색하세요. 혼동하지 마세요」

이 도구를 사용하지 않아야 할 때: 「파일 존재 여부만 확인할 때는 file_exists를 사용하세요. read_file은 내용을 읽어야 할 때를 위한 것입니다」

도구 설명 비교

나쁜 도구 설명

{ "name": "search", "description": "Search for things" }

모델이 무엇을 검색해야 할지 모르고(코드? 파일? 웹페이지?), 파라미터 형식도 불명확하며, 다른 검색 도구와 구분이 안 됩니다

좋은 도구 설명

{ "name": "search_code", "description": "Search for code patterns across the repository using regex. Returns matching file paths and line numbers. Use search_files for filename matching instead. Example: search_code({ pattern: 'def process_', file_glob: '*.py' })" }

이름이 정확하고, 설명이 명확하며, 예시가 있고, 다른 도구와의 경계도 명시되어 있습니다

도구 설계에는 Prompt 설계만큼의 노력을 투자해야 합니다. 도구 이름, 파라미터 구조, 설명 문구 모두 Agent의 사용자 인터페이스입니다. 파라미터 하나를 바꾸는 것만으로 사용하기 어려운 Agent가 신뢰할 수 있는 Agent로 변할 수 있습니다. SWE-bench의 절대 경로 사례가 이를 잘 보여줍니다.