Agent 용 OpenAPI

OpenAPI (전 Swagger) 가 REST API description 의 OG. 최신 revision (3.1.x, 3.2.x) 이 JSON Schema 를 가장 최근 draft 와 align — OpenAPI 문서가 LLM tool 정의의 완벽 source. 같은 JSON Schema, 같은 description, 같은 필드 nullability.

등장한 패턴: service 의 OpenAPI 문서 작성. 그것에서 두 artifact 생성 — 사람-coded caller 용 일반 client SDK 와 LLM 소비자 용 tool-list 번들 (function-call 정의, MCP server tool, 또는 둘). Contract 의 source of truth 하나; contract 소비자의 surface 여러.

사람과 LLM 소비 사이 진짜 차이 둘 살펴:

Description 품질. 사람은 'string, optional' 같은 파라미터 description 견딤; LLM 은 description 읽어서 tool 고름. OpenAPI 문서의 모든 파라미터 description 을 'LLM 이 잘 고를까?' 마음으로 다시 읽어.
Operation 그룹화. 사람은 path 와 tag 로 navigate; LLM 은 flat tool list 봄. 합리적이면 관련 operation 한 tool 로 그룹, 구별된 semantic 은 구별된 tool 로 노출, 모든 operation 을 별도 tool 로 mapping 시 폭발 조심.

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'}

Code

External links

Exercise

Progress

댓글 0