Agent 용 OpenAPI

OpenAPI 는 (예전 이름이 Swagger 야) REST API 를 설명하는 방식의 원조야. 최근 판 (3.1.x, 3.2.x) 이 JSON Schema 의 최신 초안과 모양을 맞추면서, OpenAPI 문서가 LLM tool 정의를 뽑아내기에 더없이 좋은 원천이 됐어. 같은 JSON Schema, 같은 description, 같은 nullability.

그래서 이런 모양이 자리를 잡았어. 서비스의 OpenAPI 문서를 하나 쓴다. 거기서 산출물을 둘 뽑는다 — 사람이 짠 코드가 쓸 평범한 client SDK 와, LLM 이 쓸 tool 목록 묶음 (function-call 정의든, MCP server 의 tool 이든, 둘 다든). Contract 의 원본은 하나고, 그걸 쓰는 얼굴만 여럿인 거지.

사람이 읽을 때와 LLM 이 읽을 때 진짜로 갈리는 지점이 둘 있어:

Description 의 품질. 사람은 'string, optional' 같은 파라미터 설명도 그럭저럭 견뎌. 하지만 LLM 은 그 설명을 읽고 tool 을 골라. OpenAPI 문서의 파라미터 설명을 전부 'LLM 이 이걸 보고 제대로 고를까?' 라는 눈으로 다시 읽어봐.
Operation 묶기. 사람은 path 와 tag 를 따라 길을 찾지만, LLM 은 평평한 tool 목록 하나를 봐. 그러니 말이 되는 선에서 관련 operation 을 tool 하나로 묶고, 뜻이 확실히 다른 건 따로 떼어놓고, operation 하나하나를 전부 tool 로 옮겨 목록이 터지는 일은 피해.

Code

OpenAPI 에서 LLM tool 정의 생성·python

# Pseudocode — spec 이 transformer driving 에 충분
import yaml

oas = yaml.safe_load(open("openapi.yaml"))
tools = []
for path, methods in oas["paths"].items():
    for method, op in methods.items():
        if not op.get("operationId"):
            continue
        tools.append({
            "name": op["operationId"],
            "description": op.get("summary", "") + "\n" + op.get("description", ""),
            "parameters": build_schema_from_oas(op),
        })

OpenAPI 3.1+ 의 Webhook — async event 가 contract 일부·yaml

webhooks:
  orderShipped:
    post:
      summary: Sent when an order is shipped.
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OrderShipped'}

Exercise

네가 관리하는 서비스의 (또는 인기 있는 공개 서비스의) OpenAPI 문서를 가져와서 프로그램으로 tool 목록을 뽑아봐. 그중 셋을 골라 LLM 이 읽을 설명으로 다시 써. 자동으로 뽑힌 설명과 다시 쓴 설명의 차이가, 문서를 tool 목록으로 바꾸는 편집 작업 그 자체야.

Code

External links

Exercise

Progress

댓글 0