대부분의 에이전트 코드베이스에는 아무도 유지보수하고 싶어 하지 않는 파일이 있습니다. 이 파일에는 40개의 도구 정의가 담겨 있으며, 각 정의는 이미 어딘가에 스키마가 있는 엔드포인트를 설명하는 수기로 작성된 JSON 스키마입니다. API 팀이 새로운 필수 필드를 배포하고, 스펙이 업데이트되고, 문서가 업데이트되지만, 누군가 400 오류를 알아차릴 때까지 에이전트는 계속해서 이전 페이로드를 보냅니다.
모든 엔드포인트에 대한 기계 판독 가능한 설명은 이미 가지고 있습니다. 바로 OpenAPI 문서입니다. 할 일은 이를 모델이 호출할 수 있는 도구 정의로 변환하고, 기억에 의존하는 대신 자동으로 두 가지를 동기화하는 것입니다.
이 가이드에서는 OpenAPI 작업이 도구 스키마에 어떻게 매핑되는지, 생성기가 이 과정에서 무엇을 수정해야 하는지, 200개의 엔드포인트 스펙을 모델이 추론할 수 있는 수준으로 줄이는 방법, 그리고 생성된 도구가 제대로 작동하는지 테스트하는 방법을 다룹니다. 스택의 더 앞단에 있다면, 에이전트가 코드를 작성할 때 여전히 API 도구가 필요한가에 대한 저희 게시물이 더 넓은 맥락을 제공합니다.
Apidog가 여기서 중요한 이유는, 스펙이 정확해야만 거기에서 생성되는 모든 것이 정확할 수 있기 때문입니다. 도구 정의는 그 원본 문서의 모든 공백을 그대로 물려받습니다.
수동으로 작성된 도구 정의의 비용
5개의 엔드포인트에서는 도구를 수동으로 작성하는 것이 괜찮게 느껴집니다. 하지만 세 가지 이유로 20개쯤 되면 더 이상 괜찮지 않게 됩니다.
정의가 어긋납니다. 스펙은 코드에서 생성되거나 API 팀에 의해 유지보수됩니다. 도구 파일은 에이전트를 구축한 사람이 유지보수합니다. 둘을 연결하는 것이 없기 때문에 조용히 어긋나게 되고, 첫 번째 증상은 에이전트가 "갑자기" 작동을 멈추는 것입니다.
설명이 얇아집니다. 사람이 40개의 스키마를 수동으로 작성하면, 마지막 20개는 한 줄 설명으로 끝납니다. 모델은 이 설명을 읽고 도구를 선택하므로, 얇은 텍스트는 도구 선택을 직접적으로 저해합니다. 에이전트를 위한 도구 스키마 설계에 대한 저희 게시물에서 왜 문구가 그렇게 중요한지 더 자세히 다룹니다.
오류는 런타임까지 보이지 않습니다. API가 정수를 원하는 필드를 문자열이라고 명시한 수동 작성된 스키마는, 에이전트가 프로덕션에서 실제 작업을 위해 처음 시도할 때 422 오류를 발생시킵니다.
스펙에서 생성하면 이 세 가지 문제가 한 번에 해결됩니다. 하나의 진실 공급원이 있고, 설명은 문서에서 사용하는 텍스트와 동일하며, 유형은 서버가 검증하는 스키마와 동일합니다.
OpenAPI 작업이 도구로 되는 방법
매핑은 보이는 것보다 더 직접적입니다. 단일 작업을 예로 들어봅시다:
paths:
/orders/{orderId}/refund:
post:
operationId: refundOrder
summary: 주문 환불
description: >
완료된 주문에 대해 전체 또는 부분 환불을 처리합니다.
환불은 취소할 수 없습니다. 부분 환불은 남은 환불 가능 잔액보다
크지 않은 금액이 필요합니다.
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
description: 환불할 주문.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [reason]
properties:
amount:
type: integer
description: 센트 단위의 금액. 전체 환불의 경우 생략.
reason:
type: string
enum: [duplicate, fraudulent, requested_by_customer]
여기서 나오는 도구 정의는 다음과 같습니다:
{
"name": "refundOrder",
"description": "완료된 주문에 대해 전체 또는 부분 환불을 처리합니다. 환불은 취소할 수 없습니다. 부분 환불은 남은 환불 가능 잔액보다 크지 않은 금액이 필요합니다.",
"input_schema": {
"type": "object",
"required": ["orderId", "reason"],
"properties": {
"orderId": { "type": "string", "description": "환불할 주문." },
"amount": { "type": "integer", "description": "센트 단위의 금액. 전체 환불의 경우 생략." },
"reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
}
}
}
네 가지 규칙이 대부분의 작업을 수행합니다:
operationId가 도구 이름이 됩니다. 작업에operationId가 없으면, 메서드와 경로에서 안정적인 이름을 생성하고 스펙에 추가하십시오.- 경로, 쿼리 및 본문 매개변수는 하나의 속성 객체로 평면화됩니다. 모델은 값이 어디로 전송되는지 신경 쓰지 않습니다. 실행기는 신경 쓰므로, 각 매개변수가 어디로 가는지 기록하는 보조 테이블을 유지하십시오.
summary와description이 결합하여 도구 설명이 됩니다. 요약만으로는 일반적으로 선택을 안내하기에는 너무 간결합니다.- 필수 배열이 병합됩니다. 필수 경로 매개변수와 필수 본문 필드는 동일한
required목록에 포함됩니다.
실행기는 나머지 절반이며, 크기는 작습니다:
def execute(tool_name, args, spec_index, http):
op = spec_index[tool_name] # 메서드, 경로 템플릿, 매개변수 위치
path = op.path
query, body = {}, {}
for name, value in args.items():
location = op.locations[name] # "path" | "query" | "header" | "body"
if location == "path":
path = path.replace("{" + name + "}", str(value))
elif location == "query":
query[name] = value
elif location == "body":
body[name] = value
return http.request(op.method, path, params=query, json=body or None)
이것이 전체 브릿지입니다. 나머지는 처리 과정에서 정리하는 작업입니다.
생성기가 수정해야 할 사항
스펙을 도구 스키마로 단순히 덤프하면 모델이 제대로 처리하지 못하는 도구가 생성됩니다. 다섯 가지 조정이 중요합니다.
$ref 포인터 해결. 대부분의 도구 호출 API는 JSON Schema의 하위 집합을 허용하며, components 섹션의 참조를 따르지 않습니다. 이를 인라인화하십시오. 재귀 스키마는 인라인화 시 무한히 확장될 수 있으므로 주의하고, 고정된 깊이에서 재귀를 중단하고 더 깊은 구조를 산문으로 설명하십시오.
지원되지 않는 키워드 삭제. oneOf, allOf, discriminator, nullable은 스펙에서 흔하지만 도구 스키마에서는 제대로 지원되지 않습니다. allOf는 속성을 병합하여 축소합니다. oneOf의 경우, 지배적인 변형을 선택하거나, 각 형태별로 작업을 두 개의 도구로 분할하십시오. 후자 옵션은 어쨌든 더 나은 도구 선택을 유도하는 경향이 있습니다.
깊은 중첩 평면화. 세 단계 깊이의 본문은 모델이 올바르게 채우기 어렵습니다. 주문 생성 페이로드에 customer.address.postal_code와 같이 중첩되어 있다면, 더 평면적인 도구 표면을 고려하고 실행기에서 중첩된 형태를 재조립하십시오.
응답 스키마 정리. 도구 정의는 입력을 설명합니다. 전체 응답 스키마는 정의에 속하지 않으며, 이를 포함하는 것은 컨텍스트를 낭비합니다. 응답이 어떻게 생겼는지는 결과가 반환될 때 중요하며, 이는 에이전트의 컨텍스트 창 내에서 API 응답 유지하기에 대한 저희 게시물에서 다루는 별개의 문제입니다.
안전 플래그 전달. 쓰기 작업은 실행기가 승인 게이트를 통해 라우팅할 수 있도록 표시되어야 합니다. 스펙이 x-agent-requires-approval과 같은 확장을 사용하는 경우, 이를 읽고 존중하십시오. 이는 AI 에이전트 가드레일 가이드의 패턴과 함께 사용하십시오.
모델에게 200개의 모든 엔드포인트를 제공하지 마십시오
가장 큰 실제적인 문제는 변환이 아닙니다. 그것은 양입니다. 성숙한 API는 수백 개의 작업을 가지고 있으며, 이 모든 것을 도구 목록에 붙여넣으면 두 가지 실패가 동시에 발생합니다: 작업이 시작되기 전에 컨텍스트가 스키마로 가득 차고, 모델이 거의 동일한 옵션 중에서 선택하기 때문에 선택 정확도가 떨어집니다.
이것을 줄이는 세 가지 방법이 있으며, 대략적으로 효과가 좋은 순서대로 나열합니다.
태그로 필터링. OpenAPI 작업은 태그를 가지며, 태그는 일반적으로 제품 영역에 매핑됩니다. 환불을 처리하는 에이전트는 admin 또는 analytics 태그가 아니라 orders 및 payments 태그가 필요합니다. 이는 한 줄짜리 필터이며 일반적으로 대부분의 표면을 제거합니다.
허용 목록 큐레이션. 이 에이전트가 호출할 수 있는 작업을 operationId별로 작성하고, 해당 작업만 생성하십시오. 이는 보안 제어 역할도 합니다. 엔드포인트에 대한 도구가 없는 에이전트는 실수로 이를 호출할 수 없기 때문입니다. AI 에이전트가 API를 파괴하는 것을 막기에 대한 저희 게시물은 바로 이런 종류의 좁은 표면을 주장합니다.
필요할 때 도구 검색. 매우 큰 API의 경우, 작업을 인덱싱하고 작업에 따라 턴당 몇 개를 선택하십시오. 이는 검색 단계를 추가하고 자체 실패 모드를 가지므로, 필터링 및 큐레이션만으로는 충분하지 않을 때만 사용하십시오.
또한 프로토콜 경로도 있습니다. Model Context Protocol은 서버가 클라이언트에 도구를 노출하는 방법을 표준화하며, OpenAPI 문서로 지원되는 MCP 서버는 프레임워크당 하나씩이 아닌 단일 통합 지점을 제공합니다. MCP가 무엇인지에 대한 저희 설명서가 모델을 다루고, Apidog로 MCP 서버 구축하기가 구축 방법을 다룹니다.
스펙이 먼저 정확해야 합니다
생성은 품질 문제를 상류로 옮깁니다. OpenAPI 문서의 모호한 설명은 모호한 도구 설명이 되고, 모델은 잘못된 엔드포인트를 선택합니다. 서버가 실제로는 필수라고 요구하는 선택적 필드는 에이전트가 첫 시도에서 잘못 호출하는 도구가 됩니다.
따라서 무엇이든 생성하기 전에 에이전트의 눈으로 스펙을 감사하십시오:
- 모든 작업에는
operationId가 있으며, 동사 + 명사 형태로 읽힙니다. - 모든 작업에는 무엇을 하는지, 무엇을 변경하는지, 언제 사용하지 않아야 하는지에 대한 설명이 있습니다. "사용자 삭제"로는 충분하지 않습니다. "사용자와 모든 세션을 영구적으로 삭제합니다. 되돌릴 수 없습니다. 일시적으로 접근을 비활성화하려면 deactivateUser를 사용하십시오."가 올바릅니다.
- 모든 매개변수에는 단위와 형식을 포함한 설명이 있습니다.
amount는 모호합니다. "센트 단위 금액, 최소 50"은 그렇지 않습니다. - 열거형은 산문으로 설명하는 대신 선언되어, 모델이 추측하는 대신 닫힌 집합을 얻습니다.
- 필수 항목이 정확합니다. 스펙은 모든 것을 선택적으로 표시하는 경향이 있어 유효성 검사 실패가 런타임으로 미뤄집니다.
이것은 일반적인 스펙 위생이며, 동일한 텍스트가 공개 문서를 구동하기 때문에 두 배의 효과를 얻습니다. Apidog에서는 스펙, 문서, 모의 서버 및 테스트가 하나의 프로젝트에서 나오므로, 설명을 명확히 하면 이 모든 것이 한 번에 개선됩니다. Apidog에서 API 버전 관리에 대한 저희 가이드는 생성된 도구를 시간이 지나도 정직하게 유지하는 나머지 절반을 다룹니다.
도구 세트를 공유하고 복사하지 마십시오
생성된 도구 세트는 구성이며, 한 개발자의 체크아웃에 있는 구성은 수동으로 작성된 스키마와 동일한 방식으로 어긋납니다. 필터 목록, 허용 목록 및 고정된 스펙 버전은 공유 아티팩트여야 하며, 그 원본 스펙 옆에 버전이 지정되어야 합니다.
일부 플랫폼은 이것을 기본 단위로 만듭니다. Sharkly에서 에이전트는 일회성 프롬프트가 아니라 저장된 작업 구성입니다. 지침, 런타임, 스킬, 저장소 및 실행 설정이 함께 이동하며 Space 전체에서 공유될 수 있으므로, 작동하는 도구 설정은 각 사람이 다시 만드는 것이 아니라 팀이 재사용하는 것이 됩니다. 아래의 런타임은 여전히 Claude Code, Codex 또는 이미 실행 중인 다른 무엇이든 될 수 있습니다. 변경되는 것은 주변 구성이 로컬에 머무르지 않는다는 것입니다.
생성된 도구 테스트
생성된 도구는 수동으로 작성된 도구와는 다른 방식으로 실패하므로, 호출뿐만 아니라 생성도 테스트해야 합니다.
스키마 왕복 검사부터 시작하십시오. 생성된 각 도구에 대해 스키마에서 유효한 예제를 만들고 전송하십시오. 400 또는 422를 반환하는 모든 것은 도구 스키마와 서버가 일치하지 않는다는 것을 의미하며, 스펙을 수정해야 합니다.
그런 다음 선택을 테스트하십시오. 알려진 올바른 도구를 포함하는 작은 작업 프롬프트 세트를 작성하고 실행한 다음, 모델이 어떤 도구를 선택했는지 기록하십시오. 이것은 누군가가 작업을 이름을 바꾸거나 설명을 축소할 때를 감지하는 저렴한 회귀 테스트 스위트입니다. 출력이 비결정적이므로, 비결정적 AI 에이전트 테스트에 대한 저희 가이드에 따라 정확한 인수가 아닌 도구 이름을 단언하십시오.
마지막으로, 실제 시스템을 사용하기 전에 모의 환경에서 에이전트를 실행하십시오. 동일한 스펙에서 생성된 모의 서버는 부작용 없이 실제와 같은 응답을 제공하며, 재시도 로직이 처리해야 하는 500 오류 및 타임아웃을 주입할 수 있습니다.
마무리
스펙은 계약이며, 도구 목록은 수동으로 유지보수되는 병렬 복사본이 아니라 그 투영이어야 합니다. 도구를 생성하고, 엄격하게 필터링하고, 설명을 정직하게 유지하고, 형태와 선택 모두를 테스트하십시오.
OpenAPI 문서를 내보내고 설명이 없는 작업의 수를 세는 것부터 시작하십시오. 그 숫자가 신뢰할 수 있는 에이전트 도구를 얻기 위해 해야 할 작업의 양입니다. 이를 수정하는 동안 스펙, 모의 및 테스트를 한 곳에서 관리하고 싶다면 Apidog를 다운로드하십시오.
자주 묻는 질문
Swagger 2.0 문서에서 도구를 생성할 수 있습니까? 예, 하지만 먼저 OpenAPI 3.x로 변환하십시오. 2.0 본문 모델은 생성기가 일관성 없게 처리할 정도로 충분히 다르며, 현재 도구는 3.x를 대상으로 합니다. OpenAPI Specification 저장소에 차이점이 문서화되어 있습니다.
모델이 한 번에 얼마나 많은 도구를 처리할 수 있습니까? 기술적 한계 훨씬 이전에 정확도가 저하되기 시작하며, 실제적인 상한은 보통 수십 개 정도입니다. 그 이상을 넘는 목록은 테스트할 한계라기보다는 태그로 필터링하거나 허용 목록을 큐레이션해야 한다는 신호로 간주하십시오.
도구 이름이 operationId와 정확히 일치해야 합니까? 예, operationId가 읽기 가능할 때 그렇습니다. 이는 도구 호출에서 스펙 작업으로 직접 조회할 수 있게 하여 추적 및 디버깅을 훨씬 쉽게 만듭니다. 이름이 좋지 않다면 생성기에서 변경하지 말고 스펙에서 이름을 바꾸십시오.
GraphQL API는 어떻습니까? 동일한 아이디어가 다른 소스에 적용됩니다: 스키마를 인트로스펙트하고 쿼리 또는 뮤테이션당 하나의 도구를 생성합니다. GraphQL 스키마는 더 많은 표면을 노출하므로 볼륨 문제가 더 심각하며, 따라서 필터링이 훨씬 더 중요합니다.
여전히 도구를 수동으로 작성해야 합니까? 몇 가지는 그렇습니다. 여러 호출을 하나의 작업으로 연결하는 복합 도구와 HTTP 이외의 다른 것을 감싸는 도구는 여전히 수동으로 작성됩니다. 핵심은 일상적인 단일 엔드포인트 래퍼가 수작업이 아니라는 것입니다.
테스트 중에 에이전트가 쓰기 엔드포인트를 호출하는 것을 어떻게 막을 수 있습니까? HTTP 메서드를 필터링하여 테스트 실행을 위한 읽기 전용 도구 세트를 생성하고, 쓰기 작업에 대해서는 에이전트를 모의 환경으로 연결하십시오. 에이전트가 프로덕션이 아닌 모의 환경을 사용해야 하는 이유에 대한 저희 게시물이 설정 방법을 다룹니다.