📄 원문: Writing effective tools for AI agents—using AI agents
- 출처: Writing effective tools for AI agents—using AI agents
- 저자: Ken Aizawa
- 원문 발행일: 2025년 9월 11일
- 라이선스: © 2025 Anthropic PBC
- 번역일: 2025년 9월 12일
- 번역 및 감수: Claude and 공부하우
⚖️ 저작권 안내
이 번역문은 교육 및 정보 제공 목적으로 작성되었습니다. 원문의 저작권은 Ken Aizawa에 있으며, 이 번역은 Ken Aizawa의 공식 번역이 아닙니다.
본 번역은 다음과 같은 교육적 공정 사용(Fair Use) 원칙에 따라 제공됩니다:
- 비영리 교육 목적
- 원문 출처의 명확한 표시
- 한국어 사용자의 기술 이해 증진을 위한 변형적 사용
- 원저작물의 시장 가치에 부정적 영향을 미치지 않음
저작권 관련 문제가 제기될 경우, 즉시 적절한 조치를 취하겠습니다. 상업적 사용이나 재배포 전에 원저작권자의 허가를 받으시기 바랍니다.
문의사항이나 우려사항이 있으시면 오른쪽 템플릿 복사를 클릭 하신 뒤, 연락 페이지를 통해 알려 주시기 바랍니다.
AI 에이전트를 위한 효과적인 도구 작성 — AI 에이전트와 함께
Model Context Protocol (MCP)은 LLM 에이전트에게 실제 작업을 해결할 수 있는 수백 개의 도구를 제공할 수 있습니다. 하지만 이러한 도구를 최대한 효과적으로 만들려면 어떻게 해야 할까요?
이 글에서는 다양한 에이전틱 AI 시스템의 성능을 향상시키는 가장 효과적인 기술을 설명합니다¹.
먼저 다음과 같은 방법을 다룹니다:
- 도구의 프로토타입 구축 및 테스트
- 에이전트와 함께 도구의 포괄적인 평가 생성 및 실행
- Claude Code와 같은 에이전트와 협업하여 도구 성능 자동 향상
그리고 도중에 발견한 고품질 도구 작성을 위한 핵심 원칙들로 마무리합니다:
- 구현할 도구와 구현하지 않을 도구 선택
- 기능의 명확한 경계를 정의하기 위한 도구 네임스페이싱
- 도구에서 에이전트로 의미 있는 컨텍스트 반환
- 토큰 효율성을 위한 도구 응답 최적화
- 도구 설명 및 사양의 프롬프트 엔지니어링
도구란 무엇인가?
도구는 결정론적 시스템과 비결정론적 에이전트 간의 계약을 반영하는 새로운 종류의 소프트웨어입니다.
전통적인 프로그래밍에서 함수를 호출하면 항상 동일한 입력에 대해 동일한 출력을 얻습니다. 하지만 에이전트가 관련되면 이러한 예측 가능성이 사라집니다. 예를 들어, "우산을 가져가야 할까요?"라는 질문에 에이전트는:
- 날씨 도구를 호출할 수 있습니다
- 일반 지식으로 답변할 수 있습니다
- 위치에 대한 명확화 질문을 할 수 있습니다
- 심지어 도구를 사용하려다가 환각을 일으킬 수도 있습니다
이는 에이전트를 위한 소프트웨어를 작성할 때 근본적으로 다른 접근 방식이 필요함을 의미합니다. 에이전트는 우리가 제공하는 도구만큼만 효과적입니다.
도구 작성 방법
효과적인 도구를 작성하는 과정을 세 가지 핵심 단계로 나눕니다:
빠른 프로토타입 구축
첫 번째 단계는 간단합니다: 작동하는 것을 빠르게 만드는 것입니다. 완벽하지 않아도 됩니다. 에이전트가 사용하고 피드백을 제공할 수 있는 기능적인 도구가 필요할 뿐입니다.
MCP를 사용하는 경우, 빠른 시작 가이드를 통해 몇 분 안에 기본 서버를 실행할 수 있습니다. 핵심은 과도한 엔지니어링을 피하는 것입니다. 프로토타입이 실제 에이전트와 함께 테스트될 때까지 무엇이 필요한지 알 수 없습니다.
평가 실행
평가를 구축하면 도구의 성능을 체계적으로 측정할 수 있습니다. Claude Code를 사용하여 이 평가에 대해 도구를 자동으로 최적화할 수 있습니다.
평가 프로세스:
- 테스트 시나리오 생성: 에이전트에게 도구가 처리해야 하는 다양한 작업을 생성하도록 요청합니다
- 평가 실행: 이러한 시나리오에 대해 도구를 테스트합니다
- 결과 분석: 실패를 식별하고 개선 영역을 찾습니다
- 반복: 도구를 개선하고 다시 테스트합니다
예를 들어, Slack MCP 서버를 테스트할 때:
그리고 Asana MCP 서버의 경우:
에이전트와 협업
가장 강력한 기술 중 하나는 Claude와 같은 에이전트를 사용하여 도구 자체를 개선하는 것입니다. 에이전트는:
- 혼란스러운 도구 설명을 식별할 수 있습니다
- 더 나은 매개변수 이름을 제안할 수 있습니다
- 오류 메시지를 개선할 수 있습니다
- 누락된 기능을 발견할 수 있습니다
이는 단순히 피드백을 받는 것이 아니라 에이전트와 적극적으로 협업하여 에이전트가 더 잘 사용할 수 있는 도구를 만드는 것입니다.
효과적인 도구 작성을 위한 원칙
수십 개의 도구를 구축하고 테스트하면서, 우리는 일관되게 성능을 향상시키는 몇 가지 핵심 원칙을 발견했습니다:
1. 작성할 도구 선택 (그리고 작성하지 않을 도구)
너무 많은 도구를 만들지 마세요. 모든 API 엔드포인트를 도구로 변환하고 싶은 유혹이 있지만, 이는 역효과를 낳습니다. 에이전트는 도구가 너무 많으면 혼란스러워하고 잘못된 도구를 선택하거나 불필요하게 여러 도구를 사용합니다.
대신:
- 영향력이 큰 워크플로우에 집중하세요
- 가능한 경우 기능을 통합하세요
- 단일 목적 도구보다 포괄적인 도구를 선호하세요
예를 들어, 별도의 list_users, list_events, create_event 도구 대신 모든 캘린더 관련 작업을 처리하는 단일 schedule_event 도구를 만드는 것이 좋습니다.
2. 도구 네임스페이싱
명확한 네임스페이스는 에이전트가 유사한 도구를 구별하는 데 도움이 됩니다. 여러 통합이 있는 경우 일관된 접두사를 사용하세요:
asana_search
jira_search
asana_projects_search
jira_projects_search
이는 에이전트가 올바른 도구를 선택하는 데 도움이 될 뿐만 아니라 개발자가 도구를 구성하고 유지 관리하기 쉽게 만듭니다.
3. 도구에서 의미 있는 컨텍스트 반환
도구 응답은 에이전트가 이해하고 작업할 수 있도록 최적화되어야 합니다. 즉:
- 암호화된 ID보다 사람이 읽을 수 있는 정보를 우선시합니다
- 관련 메타데이터를 포함합니다
- 응답 형식에 유연성을 제공합니다
enum ResponseFormat {
DETAILED = "detailed", // 모든 정보 포함
CONCISE = "concise" // 핵심 정보만
}
4. 토큰 효율성을 위한 도구 최적화
토큰은 제한된 리소스입니다. 도구는 다음을 통해 효율적이어야 합니다:
- 페이지네이션 구현: 한 번에 모든 것을 반환하지 마세요
- 필터링 제공: 에이전트가 필요한 것만 요청할 수 있도록 합니다
- 지능적으로 잘라내기: 긴 응답을 요약하거나 잘라냅니다
- 명확한 오류 메시지: 장황한 스택 트레이스 대신 실행 가능한 오류를 제공합니다
5. 도구 설명 및 사양의 프롬프트 엔지니어링
도구 설명은 새로운 팀 멤버에게 설명하는 것처럼 작성하세요:
- 도구가 하는 일을 명확히 설명합니다
- 예상 입력과 출력에 대해 명시적으로 설명합니다
- 모호하지 않은 매개변수 이름을 사용합니다
- 일반적인 사용 사례에 대한 예제를 포함합니다
좋은 예:
이 도구는 지정된 채널에서 최근 Slack 메시지를 검색합니다.
채널 ID 또는 이름을 제공하고 선택적으로 메시지 수 제한을 지정할 수 있습니다.
타임스탬프와 함께 메시지를 시간 역순으로 반환합니다.
나쁜 예:
Slack 데이터를 가져옵니다.
앞으로의 전망
도구는 에이전트가 작업을 추구하는 데 성공적인 전략을 사용하여 효과적일 수 있는 표면적을 증가시킵니다. 다행히도 에이전트에게 가장 "인체공학적"인 도구는 인간에게도 놀랍도록 직관적입니다.
핵심 교훈: 평가를 구축하고, 에이전트와 협업하며, 원칙을 따르되 항상 특정 사용 사례에 대해 테스트하세요. 도구 개발은 반복적인 프로세스이며, 에이전트 자체가 최고의 협력자가 될 수 있습니다.
¹ 이러한 원칙은 MCP를 넘어 적용되며 Anthropic API의 도구 사용, 컴퓨터 사용, 또는 다른 에이전틱 시스템과 잘 작동합니다.
감사의 말
이 게시물의 통찰력은 연구, MCP, 제품 엔지니어링, 마케팅, 디자인, 응용 AI 전반의 팀원들로부터 나왔습니다. 특별히 Alex Albert, Colt Blackmore, Michael Chun, Sam Dunn, Nate Fairbank, Joe Fenton, Ben Gershuny, Matt Hu, Max Irvine, Chak Ming Lai, Jared Linder, Lauren Lindsey, Hugo Ponte, Durk Riedstra, Jesse Rodriguez, Karina Rojas, Brendan Sullivan, Trevor Sumner에게 감사드립니다.
이 번역문은 교육 및 정보 제공 목적으로 작성되었습니다. 원문의 저작권은 Anthropic에 있으며, 이 번역은 Anthropic의 공식 번역이 아닙니다.
본 번역은 다음과 같은 교육적 공정 사용(Fair Use) 원칙에 따라 제공됩니다:
- 비영리 교육 목적
- 원문 출처의 명확한 표시
- 한국어 사용자의 기술 이해 증진을 위한 변형적 사용
- 원저작물의 시장 가치에 부정적 영향을 미치지 않음
저작권 관련 문제가 제기될 경우, 즉시 적절한 조치를 취하겠습니다. 상업적 사용이나 재배포 전에 원저작권자의 허가를 받으시기 바랍니다.
문의사항이나 우려사항이 있으시면 연락 주시기 바랍니다.