제 맛대로 번역했습니다.
에이전트의 실력은 우리가 주는 도구에 달려있다. 제대로 된 도구를 만드는 노하우, 그리고 Claude 에게 도구를 직접 튜닝하게 해 성능을 올리는 방법
MCP는 LLM 에이전트에게 업무를 해결하게 할 수 있는 수백 개의 도구를 제공해줄 수 있다. 하지만 그 도구를 어떻게 효율적으로 만들 수 있을까?
1장
- 도구의 빠른 프로토타입 제작 및 테스트 방법
- 에이전트와 함께 종합 평가를 만들고 실행하는 법
- Claude Code 같은 에이전트와 협업해 자동으로 도구 성능을 높이는 방법
2장
- 어떤 도구를 만들어야하고, 만들지 말아야하는가
- 도구에 이름을 붙여 경계를 명확하게
- 에이전트가 바로 쓸 수 있는 정보만 골라서 주기
- 토큰 효율을 위한 도구 최적화
- 도구 설명 및 스펙 프롬프트 엔지니어링
도구란 뭔가
결정론적 시스템과 비결정론적 시스템이 있다.
우리가 일반적으로 개발할 땐 결정론적 시스템 간의 계약을 만든다.
ex) getWeather("Korea")
하지만 도구(tool) 은 결정론적 시스템과 비결정론적 에이전트 사이의 새로운 종류의 계약이다.
사용자가 "오늘 우산 가져가야할까?" 라고 물으면 에이전트는
- 날씨 도구 호출
- 일반 지식
- 위치 물어보기
- 도구 사용법을 착각하거나 환각
즉, 에이전트를 위한 소프트웨어는 기존 함수 및 API 를 개발자나 시스템을 위해 만드는 방식이 아니라 에이전트 입장에서 다시 봐야된다.
우리의 목표는 에이전트가 다양한 성공 전략을 짤 수 있게 표면적을 극대화하는 것이다.
다행히 에이전틱한 도구는 사람에게도 직관적이다.
도구를 잘 만드는 법
1. 프로토타입을 빠르게 만들기
에이전트가 어떤 도구를 편하게 쓰고 어떤 도구를 헷갈려 하는지 직접 해봐야 안다.
먼저 간단한 프로토타입을 로컬에 띄워 테스트하고 필요한 프롬프트와 유스케이스를 파악해라
2. 종합 평가 실행하기
도구가 얼마나 잘 쓰이는지 측정하려면 평가가 필요하다.
- 좋은 평가 태스트 예시 (복잡하고 현실적)
"다음주에 워노랑 최신 프로젝트 미팅을 잡아주세요, 지난 기획 미팅 노트를 첨부하고 회의실 예약도 잡아주세요"
"고객 ID 9182 가 한 번 결제했는데 3번 청구됐대요, 관련 로그를 모두 찾아 문제가 다른 고객한테도 있는지 확인하세요"
- 나쁜 평가 태스크 예시 (너무 단순)
"jane@acme.corp 랑 다음주 미팅 잡아줘"
"payment_logs 에서 customer_id=9182 인 purchase_complete 찾아줘"
각 태스크에는 검증 가능한 정답이나 결과를 만들어야한다.
검증기는 그냥 AI 맡겨서 단순 비교랑 고급 방식도 가능하다. 그러지만 너무 엄격한 검증 방식은 피해야한다.
- 간단한 while-loop 에이전트로 각 태스크를 개별 실행
- 시스템 프롬프트에 reasoning + feedback 블록을 먼저 출력하도록 지시 -> CoT 효과
- 정확도 외에 다음 지표 수집 권장
- 개별 도구 호출, 태스크 수행 시간
- 총 도구 호출 수
- 토큰 소비량
- 도구 에러율
어디서 막히는지 직접 로그를 읽고 대화 기록을 모두 확인하세요
좋은 도구 만드는 핵심 원칙
1. 도구는 많이가 아니라 제대로 선택해라
도구를 기존 API 엔드포인트를 그대로 감싼다고 좋은 게 아니다.
LLM 은 컨텍스트가 제한적이기 때문에 전통 소프트웨어랑은 다른 설계가 필요하다.
예: 주소록에서 연락처 찾기
-> list_all_contacts (전체 반환) -> 컨텍스트 낭비
-> search_contacts(query) 가 훨씬 자연스럽다.
2. 네임스페이싱으로 경계 정하기
수십 ~ 수백 개 도구가 있을 때 이름이 모호하면 에이전트가 헷갈려한다.
asana_search_tasks
asana_search_project
jira_search_issues
slack_list_channels
slack_search_messages
접두사, 접미사 중 어떤 게 나은지는 모델마다 다르니 직접 테스트
3. 도구 응답은 의미 있는 정보만 반환
- UUID, 256px_image_url 같은 저수준 ID 는 ㄴㄴ
- name, profile_image_url 같은 사람이 알아들을 수 있는 정보 우선으로
4. 토큰 효율 최적화
- pagination, filtering, range selection, truncation 기본값을 적절히 설정
- 잘림 발생 시 안내 메세지 넣기
- 에러 메세지도 "잘못된 형식" 대신 "예시와 함꼐 구체적으로 어떻게 고치라"는 식으로 작성 (ex) 회원가입 할 때 그냥 "잘못된 형식" 하면 뭔지 모르니까~)
5. 도구 설명 및 스펙 철저히 프롬프트 엔지니어링
도구 설명은 신입 사원에게 설명하듯 써야한다.
모호한 용어, 특수 쿼리 포맷, 리소스 간 관계등은 모두 명시적으로 작성해야한다.
