에이전트를 위한 도구 설계
모든 도구를 결정론적 시스템과 비결정론적 에이전트 간의 계약으로 설계하세요. 사람을 위한 API와 달리, 에이전트를 위한 도구는 설명만으로 계약이 명확해야 합니다. 에이전트는 설명에서 의도를 추론하고 예상되는 형식과 일치하는 호출을 생성합니다. 모든 모호함은 어떤 프롬프트 엔지니어링으로도 해결할 수 없는 잠재적 실패 모드가 됩니다.
이 스킬의 작업 단위는 단일 도구 또는 도구 카탈로그입니다. 프로젝트 형태, 파이프라인 아키텍처, 업무-모델 적합성, 프로젝트 수준의 비용 결정은 project-development에 속합니다. 하위 에이전트 도입 여부 결정은 multi-agent-patterns에 속합니다. 이 스킬은 결정론적 코드를 에이전트에 연결하는 인터페이스 계층을 담당합니다.
활성화 시점
작업 단위가 도구일 때 이 스킬을 활성화하세요:
- 새로운 도구 설명, 스키마 또는 응답 형식 작성
- 에이전트가 잘못된 도구를 선택하거나 잘못된 형식의 호출을 생성하는 경우 디버깅
- 중복되는 도구 카탈로그 통합 (전형적인 "도구가 17개인데 에이전트가 절반은 잘못 선택하는" 경우)
- 에이전트가 스스로 수정할 수 있도록 실행 가능한 오류 메시지 설계
- 카탈로그 전체에서 도구 및 파라미터 이름을 일관되게 지정 (MCP 네임스페이싱, 동사-명사 명명)
- 통합 원칙에 따라 추가하기 전에 타사 도구 평가
다른 스킬이 담당하는 인접 작업에는 이 스킬을 활성화하지 마세요:
- 프로젝트에서 LLM을 사용해야 하는지, 파이프라인 단계가 무엇이어야 하는지 결정:
project-development - 작업을 하위 에이전트에 분산할지 아니면 더 많은 도구를 가진 단일 에이전트로 실행할지 결정:
multi-agent-patterns - 궤적 수준에서 도구 출력의 토큰 가중치 감소 (관찰 마스킹, 대규모 형식 옵션 선택):
context-optimization
핵심 개념
통합 원칙에 따라 도구를 설계하세요. 특정 상황에서 인간 엔지니어조차 어떤 도구를 사용해야 할지 확실히 말할 수 없다면 에이전트가 더 잘할 것이라고 기대할 수 없습니다. 각 도구가 하나의 명확한 목적을 가질 때까지 도구 세트를 줄이세요. 에이전트는 설명을 비교하여 도구를 선택하며, 어떤 중복도 선택 오류를 유발하기 때문입니다.
모든 도구 설명을 에이전트 행동을 형성하는 프롬프트 엔지니어링으로 취급하세요. 설명은 사람을 위한 문서가 아니라 에이전트의 컨텍스트에 주입되어 추론을 직접적으로 안내합니다. 도구가 무엇을 하는지, 언제 사용하는지, 무엇을 반환하는지에 답하는 설명을 작성하세요. 이 세 가지 질문이 에이전트가 도구 선택 중에 정확히 평가하는 것이기 때문입니다.
세부 주제
도구-에이전트 인터페이스
도구를 계약으로 각 도구를 자체 포함된 계약으로 설계하세요. 사람이 API를 호출할 때는 문서를 읽고, 규칙을 이해하며, 적절한 요청을 합니다. 에이전트는 단일 설명 블록에서 전체 계약을 추론해야 합니다. 형식 예제, 예상 패턴, 명시적 제약 조건을 포함하여 계약을 명확하게 만드세요. 호출자가 알아야 할 모든 것을 생략하지 마세요. 에이전트는 호출을 하기 전에 명확한 질문을 할 수 없기 때문입니다.
도구 설명을 프롬프트로 도구 설명이 에이전트 컨텍스트에 직접 로드되어 집합적으로 행동을 유도한다는 점을 인식하고 작성하세요. "데이터베이스 검색"과 같은 모호한 설명과 난해한 파라미터 이름은 에이전트가 추측하도록 강제하며, 추측은 잘못된 호출을 생성합니다. 대신 사용 컨텍스트, 파라미터 형식 예제, 합리적인 기본값을 포함하세요. 설명의 모든 단어는 도구 선택 정확도를 높이거나 낮춥니다.
네임스페이싱 및 구성
컬렉션이 커짐에 따라 공통 접두사 아래에 도구 네임스페이스를 지정하세요. 에이전트는 계층적 그룹화의 이점을 얻기 때문입니다. 에이전트가 데이터베이스 작업이 필요하면 db_* 네임스페이스로 라우팅하고, 웹 상호작용이 필요하면 web_*로 라우팅합니다. 네임스페이싱이 없으면 에이전트는 평평한 목록의 모든 도구를 평가해야 하며, 개수가 늘어남에 따라 선택 정확도가 저하됩니다.
통합 원칙
단일 포괄 도구
여러 개의 좁은 도구가 중복되는 대신 단일 포괄 도구를 구축하세요. list_users, list_events, create_event를 개별적으로 구현하는 대신, 가용성을 찾고 한 번의 호출로 일정을 잡는 schedule_event를 구현하세요. 포괄 도구는 전체 워크플로를 내부적으로 처리하여 에이전트가 올바른 순서로 호출을 연결해야 하는 부담을 없앱니다.
통합이 효과적인 이유 에이전트는 제한된 컨텍스트와 주의력을 가지고 있기 때문에 통합을 적용하세요. 컬렉션의 각 도구는 도구 선택 중에 주의력을 놓고 경쟁하며, 각 설명은 컨텍스트 예산 토큰을 소비하고, 중복 기능은 모호성을 만듭니다. 통합은 중복 설명을 제거하고, 선택 모호성을 없애며, 효과적인 도구 세트를 축소합니다. Vercel의 d0 사례 연구는 특수 도구를 더 작은 기본 도구 세트로 줄여 더 나은 측정 결과를 얻은 구체적인 예입니다 (claim-tool-design-vercel-d0-reduction).
통합하지 말아야 할 때 도구가 근본적으로 다른 동작을 하거나, 다른 컨텍스트를 제공하거나, 독립적으로 호출 가능해야 하는 경우 도구를 분리하여 유지하세요. 과도한 통합은 또 다른 문제를 만듭니다. 파라미터와 모드가 너무 많은 단일 도구는 에이전트가 올바르게 파라미터화하기 어렵습니다.
아키텍처 축소
대부분의 특수 도구를 제거하고 원시적인 범용 기능을 선호함으로써 통합 원칙을 논리적 극한으로 밀어붙이세요. 프로덕션 증거는 이 접근 방식이 정교한 다중 도구 아키텍처보다 더 나은 성능을 낼 수 있음을 보여줍니다.
파일 시스템 에이전트 패턴 데이터 탐색, 스키마 조회, 쿼리 검증을 위한 맞춤 도구를 구축하는 대신 단일 명령 실행 도구를 통해 직접 파일 시스템 액세스를 제공하세요. 에이전트는 표준 Unix 유틸리티(grep, cat, find, ls)를 사용하여 시스템을 탐색하고 운영합니다. 이는 파일 시스템이 모델이 깊이 이해하는 입증된 추상화이고, 표준 도구는 예측 가능한 동작을 가지며, 에이전트는 미리 정의된 워크플로에 제약받지 않고 원시 요소를 유연하게 연결할 수 있으며, 파일 내의 좋은 문서가 요약 도구를 대체하기 때문에 효과적입니다.
축소가 복잡성보다 나은 경우 데이터 계층이 잘 문서화되고 일관되게 구조화되어 있고, 모델이 충분한 추론 능력을 가지고 있으며, 특수 도구가 모델을 제약하거나 오히려 방해하고 있거나, 결과 개선보다 스캐폴딩 유지에 더 많은 시간을 소비하는 경우 축소를 선택하세요. 기본 데이터가 지저분하거나 제대로 문서화되지 않은 경우, 도메인에 모델이 부족한 전문 지식이 필요한 경우, 안전 제약 조건이 에이전트 동작을 제한해야 하는 경우, 또는 운영이 구조화된 워크플로의 이점을 진정으로 누리는 경우에는 축소를 피하세요.
미래 모델을 위해 구축하세요 현재의 한계를 고정시키는 정교한 아키텍처보다는 모델 개선의 이점을 얻을 수 있는 최소한의 아키텍처를 설계하세요. 각 도구가 새로운 기능을 가능하게 하는지, 아니면 모델이 스스로 처리할 수 있는 추론을 제약하는지 질문하세요. "안전장치"로 구축된 도구는 모델이 개선됨에 따라 종종 책임이 됩니다.
프로덕션 증거는 아키텍처 축소 사례 연구를 참조하세요.
도구 설명 엔지니어링
설명 구조 모든 도구 설명을 네 가지 질문에 답하도록 구성하세요:
- 도구는 무엇을 합니까? 도구가 정확히 무엇을 수행하는지 명시하세요. "도움이 됩니다" 또는 "사용할 수 있습니다"와 같은 모호한 언어는 피하세요.
- 언제 사용해야 합니까? 직접적인 트리거("사용자가 가격에 대해 물어봄")와 간접적인 신호("현재 시장 금리 필요")를 지정하세요.
- 어떤 입력을 받습니까? 각 파라미터를 유형, 제약 조건, 기본값 및 형식 예제와 함께 설명하세요.
- 무엇을 반환합니까? 출력 형식, 구조, 성공적인 응답 예제 및 오류 조건을 문서화하세요.
기본 파라미터 선택 일반적인 사용 사례를 반영하도록 기본값을 설정하세요. 기본값은 불필요한 파라미터 지정을 없애고 생략된 파라미터로 인한 오류를 방지하여 에이전트 부담을 줄입니다. 에이전트가 모든 옵션을 이해할 필요 없이 유용한 결과를 생성하는 기본값을 선택하세요.
응답 형식 최적화
도구 응답 크기는 컨텍스트 사용에 상당한 영향을 미치므로 응답 형식 옵션(간결 vs. 상세)을 제공하세요. 간결 형식은 필수 필드만 반환하며 확인에 적합합니다. 상세 형식은 완전한 객체를 반환하며 전체 컨텍스트가 결정을 주도할 때 적합합니다. 에이전트가 적절히 선택할 수 있도록 도구 설명에 각 형식을 사용해야 하는 경우를 문서화하세요.
오류 메시지 설계
오류 메시지를 두 대상을 위해 설계하세요: 문제를 디버깅하는 개발자와 실패에서 복구하는 에이전트. 에이전트의 경우, 모든 오류 메시지는 실행 가능해야 합니다. 즉, 무엇이 잘못되었는지와 어떻게 수정하는지 명시해야 합니다. 재시도 가능한 오류에 대한 재시도 지침, 입력 오류에 대한 수정된 형식 예제, 불완전한 요청에 대한 특정 누락 필드를 포함하세요. "실패"라고만 말하는 오류는 복구 신호를 전혀 제공하지 않습니다.
도구 정의 스키마
모든 도구에서 일관된 스키마를 수립하세요. 도구 이름에 동사-명사 패턴 사용(get_customer, create_order), 도구 간 일관된 파라미터 이름 사용(항상 customer_id, 때로는 id, 때로는 identifier를 사용하지 않음), 일관된 반환 필드 이름을 사용하세요. 일관성은 에이전트의 인지 부하를 줄이고 도구 간 일반화를 개선합니다.
도구 컬렉션 설계
설명 중복은 모델 혼란을 유발하고 더 많은 도구가 항상 더 나은 결과로 이어지지는 않기 때문에, 목적이 중복되지 않는 가장 작은 세트로 도구 컬렉션을 제한하세요. 진정으로 더 많은 도구가 필요할 때는 네임스페이싱을 사용하여 논리적 그룹을 만드세요. 선택 메커니즘을 구현하세요: 도메인별 도구 그룹화, 예제 기반 선택 힌트, 전문화된 하위 도구로 라우팅하는 우산 도구.
MCP 도구 명명 요구 사항
"도구를 찾을 수 없음" 오류를 피하기 위해 항상 MCP(모델 컨텍스트 프로토콜)와 함께 정규화된 도구 이름을 사용하세요.
형식: 서버명:도구명
# 올바름: 정규화된 이름
"BigQuery:bigquery_schema 도구를 사용하여 테이블 스키마를 검색하세요."
"GitHub:create_issue 도구를 사용하여 이슈를 생성하세요."
# 잘못됨: 정규화되지 않은 이름
"bigquery_schema 도구를 사용하세요..." # 여러 서버가 있는 경우 실패할 수 있음
서버 접두사 없이 에이전트는 여러 MCP 서버를 사용할 수 있을 때 도구를 찾지 못할 수 있습니다. 모든 도구 참조에 서버 컨텍스트를 포함하는 명명 규칙을 수립하세요.
에이전트를 사용하여 도구 최적화
관찰된 도구 실패를 에이전트에 피드백하여 문제를 진단하고 설명을 개선하세요. 보고된 효율성 향상은 대상 도구 카탈로그에서 재현될 때까지 워크로드별로 취급하세요.
도구 테스트 에이전트 패턴:
def optimize_tool_description(tool_spec, failure_examples):
"""
에이전트를 사용하여 도구 실패를 분석하고 설명을 개선합니다.
프로세스:
1. 에이전트가 다양한 작업에서 도구를 사용하려고 시도
2. 실패 모드 및 마찰점 수집
3. 에이전트가 실패를 분석하고 개선 사항 제안
4. 동일한 작업에 대해 개선된 설명 테스트
"""
prompt = f"""
이 도구 사양과 관찰된 실패를 분석하세요.
도구: {tool_spec}
관찰된 실패:
{failure_examples}
다음을 식별하세요:
1. 에이전트가 이 도구로 실패하는 이유
2. 설명에서 누락된 정보
3. 어떤 모호함이 잘못된 사용을 유발하는지
이러한 문제를 해결하는 개선된 도구 설명을 제안하세요.
"""
return get_agent_response(prompt)
이것은 피드백 루프를 만듭니다: 도구를 사용하는 에이전트가 실패 데이터를 생성하고, 에이전트가 이 데이터를 사용하여 도구 설명을 개선하며, 이는 미래 실패를 줄입니다.
도구 설계 테스트
다섯 가지 기준으로 도구 설계를 평가하세요: 명확성, 완전성, 복구 가능성, 효율성, 일관성. 대표적인 에이전트 요청을 제시하고 결과적인 도구 호출을 예상 동작과 비교하여 테스트하세요.
실용적인 지침
도구 선택 프레임워크
도구 컬렉션을 설계할 때:
- 에이전트가 수행해야 하는 고유한 워크플로 식별
- 관련 작업을 포괄적인 도구로 그룹화
- 각 도구가 명확하고 모호하지 않은 목적을 가지도록 보장
- 오류 사례 및 복구 경로 문서화
- 실제 에이전트 상호작용으로 테스트
도구 감사 체크리스트
에이전트에 도구를 추가하기 전에 모든 도구에 대해 이 체크리스트를 사용하세요:
- 이름: 동사-명사, 카탈로그에 여러 도메인이 있는 경우 네임스페이스 지정.
- 설명: 도구가 무엇을 하는지, 언제 사용하는지, 무엇을 반환하는지 명시.
- 스키마: 모든 파라미터에 유형, 제약 조건, 기본값 및 예제 값이 있음.
- 반환 형태: 성공 및 오류 페이로드가 문서화되고 기계가 읽을 수 있음.
- 복구: 각 오류가 재시도 전에 에이전트에게 무엇을 변경해야 하는지 알려줌.
- 중복: 동일한 활성화 시나리오를 가진 다른 도구가 없음.
- 통합 결정: 독립적인 호출이 필요한 경우가 아니면 인접한 좁은 도구가 병합됨.
- 토큰 영향: 큰 응답은 간결 모드 또는 파일 참조 모드를 지원.
예시
예시 1: 잘 설계된 도구
def get_customer(customer_id: str, format: str = "concise"):
"""
ID로 고객 정보를 검색합니다.
다음 경우에 사용:
- 사용자가 특정 고객 세부 정보에 대해 물을 때
- 의사 결정을 위해 고객 컨텍스트가 필요할 때
- 고객 신원 확인 시
인자:
customer_id: 형식 "CUST-######" (예: "CUST-000001")
format: "concise"는 주요 필드, "detailed"는 전체 레코드
반환:
요청된 필드가 있는 고객 객체
오류:
NOT_FOUND: 고객 ID를 찾을 수 없음
INVALID_FORMAT: ID는 CUST-###### 패턴과 일치해야 함
"""
예시 2: 잘못된 도구 설계
이 예시는 여러 도구 설계 안티패턴을 보여줍니다:
def search(query):
"""데이터베이스를 검색합니다."""
pass
이 설계의 문제점:
- 모호한 이름: "search"는 모호합니다 - 무엇을, 어떤 목적으로 검색합니까?
- 누락된 파라미터: 어떤 데이터베이스입니까? 쿼리는 어떤 형식을 취해야 합니까?
- 반환 설명 없음: 이 함수가 무엇을 반환하는지 설명하지 않습니다 - 레코드 목록, 단일 결과, 오류 코드?
- 사용 컨텍스트 없음: 에이전트가 언제 이 도구를 선택해야 하는지 명확하지 않습니다.
- 오류 처리 없음: 실패 시 어떤 일이 발생하는지, 에이전트가 어떻게 복구해야 하는지에 대한 정보가 없습니다.
잘 알려진 패턴 및 사례 연구
Vercel d0 감소 (claim-tool-design-vercel-d0-reduction)
Vercel의 d0 사례는 정교한 다중 도구 아키텍처가 통합되고 축소된 접근 방식으로 대체된 예입니다. 특수 도구를 데이터베이스 상호작용을 위한 몇 가지 원시 작업으로 대체하여 에이전트 선택 오류를 줄이고, 유지 관리 부담을 낮추며, 실제 벤치마크에서 더 나은 성능을 달성했습니다. 이는 에이전트가 더 적고 더 일반적인 도구를 더 효과적으로 사용할 수 있다는 원칙을 보여줍니다. (참고: 이는 개념적 주장입니다. 정확한 세부 사항은 Vercel의 게시된 연구를 참조하세요.)
파일 시스템 에이전트 (claim-tool-design-filesystem-agent)
이 패턴은 데이터베이스 상호작용을 위한 맞춤 도구를 파일 시스템 액세스 및 SQL 실행을 위한 단일 명령 실행 도구로 대체합니다. 이 접근 방식은 파일 시스템과 기본 Unix 유틸리티가 구조화된 데이터 탐색을 위한 입증된 인터페이스를 제공하기 때문에 효과적입니다. 잘 문서화된 데이터베이스 스키마가 포함된 파일이 있는 경우, 에이전트는 특수 탐색 도구 없이 grep, cat, head와 같은 도구를 사용하여 스키마를 찾고 쿼리를 구성할 수 있습니다.
핵심 통찰력: 데이터가 잘 문서화되고 일관되게 구조화되어 있을 때, 가장 좋은 도구 인터페이스는 아무것도 하지 않고 데이터를 직접 노출하는 것입니다.