AI 에이전트를 위한 도구 구축, 작동을 증명하는 평가와 함께
AI 에이전트를 위한 도구를 구축한다는 것은 에이전트가 호출하는 함수를 작성하는 것이지, 에이전트를 구축하는 플랫폼을 선택하는 것이 아니다. Anthropic은 2025년 9월 "Writing effective tools" 엔지니어링 게시물에서 이 경계를 그었고(스키마, 설명, 그리고 평가가 핵심), 2026년 중반까지 이를 둘러싼 스택은 정해졌다: MCP 2025-06-18 스펙, JSON Schema 파라미터, 도구 세트당 하나의 평가 루프. 아무도 제공하지 않는 마지막 부분은 이것이다: 고객이 만나기 전에 도구가 작동함을 증명하는 반복 가능한 방법.
주요 요점:
- 도구는 모델이 호출하기로 선택한 기계 판독 가능한 계약(이름, JSON Schema, 설명)이 있는 함수다.
- 도구가 당신의 제품일 때는 맞춤 구축하고, 배관일 때는 호스팅 서비스(Composio, Toolhouse)를 구매하라.
- 도구를 통합하라: 에이전트는 하나의 컨텍스트에서 약 10~15개 도구를 넘으면 성능이 저하된다(OpenAI의 지침).
- 대부분의 도구 실패는 설명 실패이지, 코드 실패가 아니다: 스키마를 온보딩 문서처럼 프롬프트 엔지니어링하라.
- 평가할 수 없는 도구는 개선할 수 없다: 정확도, 도구 호출 횟수, 토큰, 오류율, 지연 시간을 측정하라.
정확히 도구란 무엇인가? 결정론적 코드와 비결정론적 에이전트 사이의 계약
AI 에이전트용 도구는 기계 판독 가능한 계약(이름, JSON Schema 파라미터, 설명)을 가진 함수로, 모델이 자체적으로 호출하기로 선택한다. 당신의 코드는 그 호출을 결정론적으로 실행하고 모델이 다음에 추론할 컨텍스트를 반환한다. 모델은 호출 여부와 시기를 결정하고, 당신은 어떤 일이 일어나는지를 결정한다.
이 분할이 전부다. 당신의 실행자는 결정론적 코드다: 같은 인수가 들어오면 같은 결과가 나온다. 도구를 선택하는 에이전트는 그렇지 않다: 같은 프롬프트를 두 번 실행하면 두 가지 다른 도구 선택을 얻을 수 있다. 따라서 그들 사이의 계약이 무게를 담당한다. 이름은 도구가 무엇을 위한 것인지 말하고, 스키마는 도구가 무엇을 전달할 수 있는지 말하고, 설명은 언제 신경 써야 하는지 말한다. 마지막 부분이 대부분의 팀이 실패하는 곳인데, 설명을 문서화로 취급한다. 그것은 모델의 유일한 브리핑이며 계약의 일부다.
도구 호출 루프, 한 호흡에
루프는 네 박자로 실행된다: 도구 정의를 등록하고, 모델이 호출을 내보내고, 당신의 실행자가 실행하고, 결과는 다음 의사결정의 입력으로 컨텍스트에 다시 들어간다. Anthropic의 "Writing effective tools"는 이 루프 위에 그것의 핵심 사례를 구축한다; 이 가이드는 그 작업을 확장한다. 모델 측 메커니즘에 대해, 요청 및 응답 형태가 제공자마다 어떻게 다른지를 포함하여, 공급자 간 함수 호출이 어떻게 작동하는지를 보라. 우리는 당신의 측면, 즉 도구 자체에 머문다.
도구는 당신의 에이전트가 결정론적 코드에 닿는 유일한 지점이다. 프롬프트처럼이 아니라 API처럼 그 계약을 설계하라.
구축, 구매, 또는 래핑: 에이전트는 어떻게 도구를 얻어야 하는가?
당신의 에이전트는 세 가지 방법 중 하나로 도구를 얻는다: 맞춤 MCP 서버를 구축하거나, Composio 같은 호스팅 플랫폼을 구독하거나, 원시 REST API를 직접 래핑한다. 모든 구축 대 구매 논쟁은 한 가지 질문으로 축약된다: 이 도구가 당신의 제품인가, 아니면 배관인가? 우리는 첫 번째는 구축하고 두 번째는 구매한다; 아래 표는 우리가 실제로 실행하는 결정이다.
호스팅 도구 플랫폼이 올바른 답일 때
호스팅 플랫폼은 이미 인증이 해결된 사전 구축된 통합을 판매하며, 이것은 Notion, Slack, Gmail이 이번 주에 필요하고 그것 중 어느 것도 당신을 차별화하지 않을 때의 올바른 답이다. Composio의 문서는 수백 개의 그러한 통합을 광고하고, 함수 호출 라이브러리의 우리 순위는 Composio를 4위에, Toolhouse를 7위에 놓는다: 견고한 배관, 정직하게 검토됨. 솔직한 한계: 모든 호출은 추가 네트워크 홉을 취하고, 당신은 그들의 지연 시간과 인증 모델을 상속받으며, 마이그레이션은 도구 계층을 다시 작성하는 것을 의미한다. Composio는 무료 계층과 그 위의 유료 플랜을 가지고 있다; 가격 책정은 선택 게시물에 속하고, 이것에는 속하지 않는다.
당신 자신의 MCP 서버를 구축할 때
도구 로직이 독점적일 때, 100ms 미만의 응답이 필요할 때, 또는 그 도구의 평가가 당신의 품질 기준의 일부일 때 구축하라. 당신의 내부 주문 데이터베이스를 검색하는 지원 에이전트는 Composio 통합이 아니다. 그것은 도구 코스튬을 입은 당신의 제품이고; 빌려 쓰는 것은 전략적 오류다.
도구가 당신의 제품일 때는 맞춤 구축하고, 도구가 배관일 때는 호스팅 서비스를 구매하라.
좋은 도구 정의의 해부
좋은 도구 정의는 모델이 처음에 만족할 수 있는 JSON Schema 계약이다: 동사-명사 이름, 값이 폐쇄형 집합을 형성하는 열거형이 있는 타입 파라미터, 현실과 일치하는 필수 목록, 그리고 행동을 제약하는 설명. 공급자는 구문이 다르고, 의도는 같다. 계약을 한 번 작성하라; 그것을 번역하라.
데이터베이스가 아닌 모델을 위해 파라미터 이름을 지정하라
user가 아닌 user_id라고 부르라: 첫 번째는 모델이 전달할 수 있는 식별자이고, 두 번째는 이름, 객체, 또는 이메일일 수 있다. 값이 폐쇄형 집합을 형성하는 어디서나 자유 텍스트 대신 열거형을 사용하라("status": {"enum": ["open", "shipped", "delivered"]}), 왜냐하면 열거형은 잘못된 인수를 구조적으로 불가능하게 만들기 때문이다. 그 다음 당신의 공급자가 제공하는 가장 엄격한 모드를 켜라: OpenAI의 strict: true는 추가 속성을 금지하는 반면, Anthropic은 input_schema에 대해 필수 목록을 시행한다(그들의 도구 사용 구현 문서는 현재 모범 사례를 설명한다). 마지막으로, 행동을 제약하는 설명을 작성하라: "ISO 8601 날짜, 예: 2026-08-01"이 "날짜"를 이긴다.
같은 도구, 세 공급자
2026년에 실제로 만날 세 가지 형식의 하나의 search_orders 도구:
실제 차이는 세 행에 맞는다:
그 MCP 열은 도구 작성자에게 프로토콜이 중요한 이유다: 주석은 클라이언트에게 도구가 읽기 전용임을 확인하기 전에 알린다. MCP에 처음인가? 우리 MCP 개념 가이드는 아키텍처를 다루고; 이 게시물은 정의 핵심에 머문다.
대부분의 도구 실패는 설명 실패다: 모델이 스키마가 아무것도 말하지 않았기 때문에 잘못된 인수로 올바른 도구를 선택했다.
AI 에이전트 도구 구축을 위한 일곱 가지 설계 원칙
일곱 가지 원칙, 대략 영향의 순서: 처음 두 가지는 에이전트가 올바르게 선택할 수 있는지를 결정하고, 나머지는 일단 그것이 할 수 있게 되면 얼마나 잘 수행하는지를 결정한다.
1. 높은 영향의 워크플로우를 먼저 선택하라
모든 것을 도구화하지 말라. 사용자가 반복하는 다섯 가지 작업을 나열하고, 잘못된 답변이 실제 비용을 유발하는 두 세 가지를 선택하고, 그것들을 먼저 구축하라. 아무도 한 시간을 절약하지 못하는 도구는 소음이다. OpenAI는 에이전트 구축에 대한 실용적인 가이드에서 같은 결정을 내린다: API 인벤토리가 아닌 워크플로우에서 시작하라.
2. 통합하라, 증가시키지 말라
당신이 추가하는 모든 도구는 모델의 선택 주의를 놓고 경쟁한다. OpenAI의 가이드는 대략 10개 도구 아래에서 성능이 강하게 유지되고 15를 넘으면 저하된다고 보고한다. 따라서 병합하라: 작업 파라미터(search, update, cancel)를 가진 하나의 주문 도구가 세 개의 거의 동일한 도구를 이긴다. 하나의 결정이 모두를 포함할 때까지 통합하라.
3. 관련 도구에 네임스페이스를 지정하라
수십 개의 도구를 넘으면 도메인으로 접두사를 붙이라: github_create_issue, github_list_pulls, jira_create_issue. 네임스페이스가 없으면 두 백엔드에 대해 create_issue를 하는 것은 모든 호출에서 동전 던지기이고, 접두사는 뭔가 잘못되었을 때 평가 출력을 읽을 수 있게 만든다.
4. 높은 신호 컨텍스트를 반환하라
도구 결과는 컨텍스트 윈도우로 바로 들어가므로, 다음 의사결정이 필요로 하는 것을 반환하고 다른 것은 아무것도 반환하지 말라. 가득한 40열 행이 아니라; 모델이 해석할 수 없는 원시 UUID도 아니라. 다섯 개의 사전 포맷된 필드를 반환하라: 주문 #4471, 배송됨 2026-07-28, ETA 2026-08-02, 운송사 DHL.
5. 페이지네이션과 절단으로 토큰 예산을 책정하라
도구 출력은 대부분의 에이전트가 가진 가장 큰 컨텍스트 예산 항목이다. Claude Code는 단일 도구 결과를 약 25,000 토큰 정도로 절단한다; 당신의 루프는 그보다 훨씬 전에 끊어야 한다. 기본적으로 페이지네이션하라: 커서가 있는 20개 행, 4,000개 행은 절대 아니다. 스택 추적과 HTML 본문을 소스에서 절단하라.
6. 에이전트가 작용할 수 있는 오류를 작성하라
막다른 오류를 만나는 에이전트는 루프를 돌거나 포기한다. 좋은 오류는 모델이 그것을 읽고 올바른 다음 단계를 취할 수 있게 한다:
...