빠른 흐름
API 연결 전 준비
1. GPT가 해야 할 외부 동작을 좁힌다
2. API 인증 방식을 정한다
3. OpenAPI schema를 작성한다
4. action domain 허용 여부를 확인한다
5. 테스트 호출과 실패 응답을 검증한다설정 구조
Action은 GPT와 외부 API 사이의 계약이다
OpenAI Help 기준으로 GPT Action은 외부 API에 연결하기 위해 인증 정보와 OpenAPI schema를 함께 설정하는 구조입니다. GPT가 어떤 endpoint를 호출할 수 있는지, 어떤 parameter가 필요한지, 어떤 응답을 받을지 schema가 정의합니다.
GPT instruction
-> 언제 action을 쓸지 설명
Action schema
-> 어떤 API를 어떻게 호출할지 정의
Authentication
-> API 접근 권한 관리프롬프트에 "우리 API를 호출해"라고 쓰는 것만으로는 충분하지 않습니다. 실제 호출 가능한 surface는 action schema와 인증 설정이 결정합니다.
Apps와 Actions는 같은 GPT 안에서 함께 쓰지 못할 수 있다
공식 문서 기준으로 GPT는 Apps 또는 Actions 중 하나를 사용할 수 있고, 둘을 동시에 쓰지 못하는 제한이 있습니다. 외부 SaaS와의 사용자 경험을 만들지, 특정 API를 직접 호출하는 custom action을 만들지 먼저 결정해야 합니다.
Apps
-> ChatGPT 안의 앱 경험과 연결
Actions
-> OpenAPI schema 기반 API 호출이미 Apps로 충분히 제공되는 기능이면 custom action을 만들 필요가 없습니다. 반대로 내부 API나 사내 도구처럼 직접 schema가 필요한 경우에는 Actions가 맞습니다.
도메인 허용과 워크스페이스 정책을 확인한다
Enterprise와 Edu 같은 워크스페이스에서는 action domain allowlist나 GPT governance 정책이 적용될 수 있습니다. 문서 기준으로 action domain이 전혀 허용되지 않으면 custom action은 실행될 수 없습니다. 개인 환경에서 잘 되던 GPT가 조직 워크스페이스에서 실패하면 domain allowlist와 관리자 설정을 먼저 확인해야 합니다.
선택 기준
| 상황 | 선택 |
|---|---|
| 공개 SaaS 앱 연결 | Apps 우선 검토 |
| 내부 API 호출 | GPT Actions |
| 인증이 필요한 API | 인증 방식과 scope 최소화 |
| schema가 자주 바뀜 | action version 관리 |
| 조직 워크스페이스 | domain allowlist 확인 |
| 안전한 실행 필요 | 읽기 action과 쓰기 action 분리 |
주의할 점
GPT Action은 외부 시스템에 실제 요청을 보낼 수 있으므로 읽기와 쓰기 동작을 같은 수준으로 취급하면 안 됩니다. 삭제, 결제, 전송, 업데이트 같은 쓰기 action은 별도 확인 절차와 좁은 권한으로 설계해야 합니다.
OpenAPI schema가 넓으면 GPT가 의도하지 않은 endpoint를 선택할 여지가 커집니다. 처음에는 꼭 필요한 endpoint만 노출하고, 실패 응답과 권한 오류를 테스트한 뒤 확장하는 편이 안전합니다.
참고 링크
1 sources