Quick Flow

GPT Action은 “API를 호출해”라는 instruction이 아니라, GPT에 노출할 endpoint·parameter·인증을 제한하는 외부 시스템 계약입니다. 처음에는 조회용 action 하나를 작은 schema로 검증하고, 변경 action은 별도 endpoint·권한·승인 경계로 추가합니다.

1. 목적: "주문 상태 조회"처럼 한 행동으로 좁힌다.
2. schema: 서버, endpoint, parameter, operationId, response를 OpenAPI JSON/YAML로 정의한다.
3. auth: None / API key / OAuth 중 API의 실제 접근 모델에 맞게 고른다.
4. policy: workspace의 action domain allowlist와 GPT 권한을 확인한다.
5. Preview: 정상 입력, 없는 ID, 권한 없음, 시간 초과를 테스트한다.
6. 확장: 변경·삭제 action은 조회 action과 분리하고 재승인 흐름을 검토한다.

schema를 최소 surface로 만들기

Action schema는 어떤 server를 부르고, 어떤 endpoint·parameter·operationId를 사용하며, 어떤 응답을 받는지 정의하는 OpenAPI JSON 또는 YAML 문서입니다. Instructions에는 언제 action을 써야 하는지와 사용자 확인 규칙을 적고, schema에는 실제 호출 가능한 경로만 둡니다. instruction이 넓어도 schema 밖의 endpoint는 호출할 수 없습니다.

openapi: 3.1.0
info:
  title: Order lookup
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      summary: 주문 상태만 조회한다
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }

/orders 전체를 수정·삭제·조회하는 넓은 schema보다, 필요한 GET /orders/{orderId}부터 시작하는 편이 안전합니다. 입력 validation, API의 authorization, idempotency, audit log는 GPT schema만으로 자동 보장되지 않으므로 외부 API에서도 구현합니다.

인증과 workspace 제한

인증은 None, API key, OAuth 중에서 고릅니다. 인증이 필요 없는 공개 조회만 None을 쓰고, server-to-server 접근은 API key, 사용자 계정별 접근은 OAuth가 맞습니다. OAuth에는 Client ID·Client Secret·Authorization URL·Token URL·scope·token exchange가 필요하며 editor가 callback URL을 제공합니다. scope는 필요한 읽기·쓰기 권한만 요청합니다.

Enterprise·Edu workspace는 action domain을 모든 domain 또는 승인된 domain으로 제한할 수 있습니다. 허용 domain이 0개면 GPT custom action은 실행되지 않습니다. custom action은 Pro mode에서 사용할 수 없고, Actions와 Apps는 같은 GPT에서 함께 사용할 수 없습니다. 기능이 보이지 않거나 호출이 막히면 prompt보다 모델 선택, GPT capability, workspace domain·권한을 먼저 확인합니다.

호출 전후의 사용자 보호

사용자는 action 전에 승인을 요청받을 수 있으며, OAuth 연결도 계정별로 검토·관리할 수 있습니다. Link 또는 GPT Store에 공개하는 GPT가 actions를 사용하면 유효한 Privacy Policy URL이 필요합니다. 외부 상태를 바꾸는 action은 미리보기 -> 대상·변경 설명 -> 사용자 승인 -> 실행 결과 확인 흐름을 Instructions와 API 양쪽에 둡니다.

쓰기 action 지침 예시
- 먼저 변경할 대상 ID, 현재 값, 새 값을 보여 준다.
- 사용자가 명시적으로 승인한 뒤에만 호출한다.
- 성공 응답만으로 끝내지 말고 읽기 endpoint로 실제 결과를 다시 확인한다.
- 실패하면 재시도하지 말고 오류 코드와 다음 조치를 보고한다.