OpenAPI 도구

OpenAPI 도구 (OpenAPI Tool)

OpenAPI 3.x 스펙을 URL에서 가져와 API 작업별로 도구를 만드는 방법을 설명해요. 에이전트가 REST API를 직접 호출할 수 있어요.

출처: 문서

본문

OpenAPI 도구는 URL에서 OpenAPI 3.x 스펙을 가져와 각 API 작업마다 도구 하나를 만들어요. 각 엔드포인트의 파라미터, 요청 본문, 설명이 에이전트가 직접 호출할 수 있는 호출 가능한 도구로 변환돼요.

구성

toolsets:
  - type: openapi
    url: "https://petstore3.swagger.io/api/v3/openapi.json"

커스텀 헤더와 함께

생성된 도구가 만드는 모든 HTTP 요청에 커스텀 헤더를 전달하세요(예: 인증용):

toolsets:
  - type: openapi
    url: "https://api.example.com/openapi.json"
    headers:
      Authorization: "Bearer ${env.API_TOKEN}"
      X-Custom-Header: "my-value"

커스텀 타임아웃

기본 30초 HTTP 타임아웃을 덮어쓰세요(스펙 가져오기와 생성된 도구 호출 모두에 적용):

toolsets:
  - type: openapi
    url: "https://api.example.com/openapi.json"
    timeout: 60

내부 서비스 도달

기본적으로 OpenAPI 도구는 비공개 IP 주소로의 연결을 거부해서, DNS가 공개 호스트를 내부 범위로 해석하더라도 SSRF 시도를 차단해요. 스펙이나 그 servers 항목이 정당하게 localhost나 내부 네트워크를 겨냥할 때 allow_private_ips로 옵트인하세요:

toolsets:
  - type: openapi
    url: "http://localhost:8080/openapi.json"
    allow_private_ips: true

속성

속성 타입 필수 설명
url string ✓ OpenAPI 스펙 URL(JSON 형식). ${env.VAR} 보간 지원
headers map[string]string ✗ 모든 요청에 보내는 커스텀 HTTP 헤더 — 스펙 가져오기와 모든 생성된 도구 호출 모두. 값은 ${env.VAR}와 ${headers.NAME} 자리표시자 지원(후자는 docker agent가 서버로 노출될 때 호출자의 들어오는 요청에서 헤더를 전달)
timeout int ✗ HTTP 클라이언트 타임아웃(초, 기본: 30). 스펙 가져오기와 생성된 도구의 요청 모두에 적용
allow_private_ips boolean ✗ 비공개 IP 주소(루프백, RFC1918, 링크로컬 — 169.254.169.254의 클라우드 메타데이터 엔드포인트 포함 — 멀티캐스트, 미지정 주소)로 다이얼링을 허용. 스펙이나 그 서버가 정당하게 내부 서비스를 겨냥할 때만 true로 설정. 기본적으로 그런 주소는 DNS 해석 후 다이얼 시점에 거부되어 DNS 리바인딩이 검사를 우회할 수 없음

동작 방식

  • 스펙은 시작 시 설정된 url에서 가져와요.
  • 각 작업(GET, POST, PUT 등)은 operationId(또는 operationId가 없으면 method_path)로 이름 지어진 별도의 도구가 돼요.
  • 경로와 쿼리 파라미터는 도구 파라미터로 노출돼요. 요청 본문 속성은 body_ 접두사가 붙어요.
  • 읽기 전용 작업(GET, HEAD, OPTIONS)은 그에 따라 주석 처리돼요.
  • 응답은 텍스트로 반환되고, 오류에는 HTTP 상태 코드가 포함돼요.

한계

  • OpenAPI 스펙은 10MB 이하여야 해요.
  • 개별 API 응답은 1MB에서 잘려요.

예시

작동하는 에이전트 구성은 전체 Pet Store 예시를 확인하세요.

더 알아보기 (Learn more)