Custom GPT Actions는 ChatGPT가 외부 API를 호출하게 하는 기능입니다. 액션은 인증 방식과 OpenAPI 스키마로 API 기능을 정의하며, GPT는 앱과 액션을 함께 쓸 수 있습니다. 실시간 데이터가 필요한 업무일수록 액션 설계가 대화 품질을 가릅니다.
Custom GPT Actions 추천 API 연동을 쓰려면 스키마 필드와 인증을 먼저 맞춰야 합니다. 이 글은 설정 순서, 업무 사례, 테스트와 운영 한도를 실무 기준으로 정리합니다. 스키마는 에디터에 붙여 넣거나 URL로 가져오는 방식부터 확인할 수 있습니다.
Custom GPT Actions란 무엇인가, API 연동이 필요한 이유
Custom GPT Actions는 GPT가 대화 중에 외부 API를 호출하게 만드는 기능입니다. 공식 안내는 액션이 인증 방식과 API 기능을 정의하는 스키마 두 요소로 구성된다고 밝힙니다. GPT는 앱과 액션을 동시에 쓸 수 있어 검색과 일정, 사내 조회를 한 흐름에 묶을 수 있습니다.
연동이 없으면 모델은 학습 데이터와 업로드 파일에만 의존합니다. 재고, 예약, 티켓 상태처럼 실시간 값이 필요한 업무에서는 액션이 사실상 필수입니다. 처음부터 호출 범위와 실패 메시지를 정해 두면 이후 스키마 수정이 줄어듭니다.
Actions 설정 전 확인해야 할 OpenAPI 스펙과 인증 방식
(출처: 아름다운학교운동본부)
Actions를 켜기 전에 OpenAPI 스펙과 인증을 먼저 확정해야 합니다. 스키마는 JSON 또는 YAML이며 에디터에 붙여넣기, URL 가져오기, 내장 예시로 추가합니다. 인증은 GPT 에디터에서 None, API Key, OAuth 중 하나를 고릅니다.
스펙이 불완전하면 모델이 인자를 빠뜨리거나 잘못된 경로를 호출합니다. 공개 엔드포인트인지, 사용자별 로그인인지에 따라 인증을 갈라야 이후 콜백과 토큰 오류가 줄어듭니다. 인증을 나중에 바꾸면 콜백 URL과 헤더 규칙도 다시 맞춰야 합니다.
OpenAPI 스키마에서 꼭 채울 필드
스키마에는 서버 URL, 경로, 메서드, 요청 본문과 응답 형식을 빠짐없이 적습니다. operationId와 description을 구체적으로 쓰면 모델이 도구를 고르는 정확도가 올라갑니다. 필수 파라미터는 required로 표시하고, 예시 값을 넣어 테스트 호출이 바로 되게 합니다.
에러 응답 코드와 메시지 필드도 정의해야 실패 대화를 통제할 수 있습니다. 인증 헤더를 스키마와 에디터 설정이 서로 다르게 두면 401이 반복되므로 헤더 이름과 전달 위치를 한쪽으로 맞춥니다. 서버 URL은 스테이징과 운영을 구분해 적습니다.
API 키·OAuth 중 어떤 인증을 고를지
공용 서비스 키면 API Key가 단순합니다. 에디터 UI로 키를 넣으면 OpenAI는 비밀키를 DB에 암호화 저장합니다. 사용자마다 권한이 다르면 OAuth를 고르고 client ID, client secret, authorization URL, token URL, scope를 채웁니다.
OAuth 토큰 교환은 authorization_code 그랜트입니다. 콜백은 chat.openai.com 또는 chatgpt.com의 /aip/{gpt-id}/oauth/callback 형식이 유효합니다. 보안상 state 파라미터는 반드시 써야 하며, 이후 요청에는 Authorization 헤더로 Bearer 또는 Basic과 함께 액세스 토큰이 전달됩니다.
업무에 바로 쓰는 Custom GPT Actions 추천 API 연동 사례
추천 API는 매일 쓰는 생산성 도구와 사내 REST로 나누는 편이 안전합니다. 검색, 캘린더, 슬랙처럼 권한이 분명한 서비스부터 붙이면 스키마 검증이 빠릅니다. 사내 조회는 읽기 전용 엔드포인트로 시작해 쓰기 사고를 막습니다. 읽기와 쓰기는 액션을 분리해 잘못된 변경을 줄입니다.
한 번에 많은 액션을 넣으면 모델이 도구를 혼동합니다. 업무 시나리오 두세 개에 필요한 호출만 남기고, 성공 기준을 응답 필드로 고정하는 편이 운영에 유리합니다. 권한 범위를 좁혀 두면 감사와 요금 통함께 쉬워집니다.
검색·캘린더·슬랙 등 생산성 API
웹 검색 API는 최신 공지와 문서 링크를 대화에 끌어올 때 씁니다. 캘린더 API는 빈 시간 조회와 일정 생성에 맞고, 슬랙 API는 채널 알림과 스레드 회신에 맞습니다. 각 서비스의 공식 스코프만 열고, 쓰기 권한은 필요한 메서드에만 부여합니다.
ChatGPT 액션 추천 API로 생산성 도구를 고를 때는 응답이 JSON으로 단순한지를 봅니다. 중첩이 깊은 객체는 description을 쪼개고, 날짜는 ISO 형식으로 통일해야 모델이 인자를 덜 틀립니다. 파일 전송이 큰 기능은 액션 페이로드보다 대화 첨부가 안정적입니다.
사내 데이터 조회용 REST API
사내 REST는 고객, 주문, 재고처럼 조회가 잦은 자원부터 노출합니다. GET 위주로 시작하고, 식별자는 사번이나 주문번호처럼 사람이 말할 수 있는 값을 받습니다. 응답은 필요한 필드만 남긴 요약 객체가 대화에 유리합니다.
내부망만 열리는 API는 ChatGPT 클라우드에서 호출되지 않습니다. 공개 HTTPS 게이트웨이와 IP 제한, 만료 있는 토큰을 준비해야 외부 API 연동 자동화가 실제로 동작합니다. 개인정보가 섞인 필드는 마스킹 규칙을 스키마 설명에 명시합니다.
연동 실패를 줄이는 스키마 설계와 테스트 체크리스트
연동 실패의 대부분은 스키마와 실제 응답이 다를 때 납니다. 필수 필드를 빼거나 enum을 실제 값과 다르게 적으면 모델이 재시도를 반복합니다. 스테이징 URL로 먼저 호출하고, 성공·4xx·5xx 대화를 각각 확인합니다.
테스트에서는 operationId마다 최소 한 번씩 실행합니다. 인증 만료, 권한 부족, 빈 결과도 점검해야 사용자가 같은 질문을 반복하지 않습니다. 변경 후에는 스키마 버전과 배포 시각을 기록해 롤백을 쉽게 합니다. 실패 문구를 액션 설명에 적어 두면 재질문 횟수가 줄어듭니다.
| 점검 항목 | 확인 기준 | 실패 시 증상 |
|---|---|---|
| 스키마와 실응답 | 필수 필드·enum 일치 | 재시도 반복 |
| 인증 헤더 | Bearer 또는 Basic 전달 | 401 반복 |
| 콜백과 state | 지정 redirect와 state 검증 | OAuth 로그인 중단 |
| 한도와 권한 | 일일 쿼터와 최소 스코프 | 호출 차단·과금 급증 |
보안·권한·요금 한도까지 챙기는 운영 포인트
API Key는 공용 비밀이므로 GPT 공유 범위를 제한해야 합니다. OAuth는 사용자별 토큰이라 권한 분리에는 유리하지만, 앱의 redirect와 state 검증이 필요합니다. 호출 한도와 과금은 공급자 콘솔에서 일일 쿼터를 걸어 폭주를 막습니다.
로그에는 토큰과 주민번호, 카드번호를 남기지 마십시오. 액션 설명을 너무 넓게 쓰면 모델이 위험한 쓰기 API까지 고를 수 있습니다. 운영 담당은 월 1회 스코프와 키 만료를 점검하는 주기를 고정하십시오. 공유 링크 수신자 수만큼 키가 쓰일 수 있으니 배포 대상을 최소로 유지하십시오.
Custom GPT Actions API 연동 핵심 정리와 다음 단계
Custom GPT Actions 설정은 스키마와 인증을 맞춘 뒤, 좁은 생산성 API부터 붙이는 순서가 안정적입니다. ChatGPT OpenAPI 스키마에 서버, 경로, 필수 인자, 오류 형식을 채우고 GPT Actions OAuth 또는 API Key를 업무 권한에 맞게 고르십시오.
다음 단계로는 읽기 전용 액션 하나로 파일럿을 돌리고, 체크리스트를 통과한 뒤에만 쓰기를 엽니다. 한도와 로그 정책을 정한 다음 사용 부서를 늘리면 장애 범위가 작아집니다. 콜백 URL과 스코프를 문서에 남겨 인수인계 공백을 줄이십시오.
