SDK 개요
프로토콜에 따라 OpenAI, Anthropic 또는 Gemini 클라이언트 SDK를 선택하고 연동 전 확인을 완료합니다.
AGTCloud는 OpenAI, Anthropic 및 Gemini 호환 진입점을 제공합니다. 해당 공식 SDK를 이미 사용하는 서버 프로젝트는 보통 주요 호출 방식을 유지하고 API 주소, API Key 및 모델 ID를 AGTCloud 설정으로 교체할 수 있습니다.
SDK는 해당 프로토콜에 맞게만 요청을 구성합니다. 선택 전에 대상 모델이 지원하는 프로토콜을 확인하고 모델 이름만으로 호환성을 판단하지 않습니다.
클라이언트 SDK 선택
| SDK | 해당 프로토콜 | 인증 방식 | 적합한 시나리오 |
|---|---|---|---|
| OpenAI SDK | Chat Completions, Responses | Bearer API Key | 기존 OpenAI SDK 프로젝트 또는 메시지 대화, Typed Items, 스트리밍 출력 및 도구 호출이 필요한 경우 |
| Anthropic SDK | Anthropic Messages | x-api-key 및 버전 Header | 기존 Anthropic Messages 프로젝트 또는 Content Blocks 및 Anthropic 도구 구조가 필요한 경우 |
| Gemini SDK | Gemini Generate Content | Bearer API Key | 기존 Gemini SDK 프로젝트 또는 contents, parts 및 Gemini 네이티브 콘텐츠 구조가 필요한 경우 |
SDK는 프로토콜을 자동 변환하지 않습니다
OpenAI의 messages 또는 input, Anthropic의 Content Blocks, Gemini의 contents 및 parts는 서로 다른 데이터 구조입니다. 기존 업무 코드와 같은 프로토콜의 튜토리얼을 사용하고 프로토콜 간 리팩터링이 필요하면 공식 SDK 마이그레이션을 먼저 읽습니다.
세 프로토콜의 주요 차이
| 비교 항목 | OpenAI SDK | Anthropic SDK | Gemini SDK |
|---|---|---|---|
| 주요 진입점 | Chat Completions, Responses | Messages | Generate Content |
| 대화 입력 | messages 또는 input | messages 및 Content Blocks | contents 및 parts |
| 일반 텍스트 출력 | Chat Message 또는 Responses Output Items | content 콘텐츠 블록 | candidates[].content.parts |
| 스트리밍 구조 | Chat Delta 또는 response.* 이벤트 | Messages SSE 이벤트 | Stream Generate Content |
| 도구 구조 | Function Tools 및 Responses 내장 도구 | tool_use, tool_result | functionCall, functionResponse |
전체 필드, 열거형 및 응답 구조는 해당 API Reference를 기준으로 합니다. SDK 튜토리얼은 클라이언트 설치, 초기화 및 결과 읽기에 중점을 두며 전체 Schema를 반복해서 설명하지 않습니다.
연동 전 준비
API Key 생성
AGTCloud API Key를 API Keys 페이지에서 생성하고 서버 환경 변수 또는 비밀 관리 서비스에 저장합니다.
실제 API Key를 브라우저 코드, 모바일 설치 패키지, 공개 저장소, 스크린샷 또는 로그에 기록하지 않습니다.
모델 및 프로토콜 확인
전체 모델 ID를 모델 목록에서 복사하고 해당 모델이 사용할 프로토콜과 기능을 지원하는지 확인합니다.
이 채널은 모델 자리표시자로 MODEL_ID를 사용합니다. 실제 호출 전에 현재 API Key에 표시되는 모델 ID로 반드시 교체해야 합니다.
서버 실행 환경 선택
Python과 TypeScript SDK는 신뢰할 수 있는 서버 환경에서 실행해야 합니다. 현재 안정 버전 SDK를 설치하고 프로젝트의 의존성 잠금 파일로 실제 사용 버전을 고정합니다.
권장 검증 순서
- SDK를 설치하고 애플리케이션이 API Key를 읽을 수 있는지 확인합니다.
- 튜토리얼의 Base URL을 설정하고 전체 업무 엔드포인트 경로를 입력하지 않습니다.
- 순수 텍스트와 최소 필드로 비스트리밍 요청을 한 번 보냅니다.
- 텍스트 결과, 종료 상태 및 Token 사용량을 확인합니다.
- 업무 필요에 따라 Streaming, 도구, 멀티모달 또는 구조화된 출력을 검증합니다.
- 타임아웃, 요청 제한 및 서버 오류에 로그와 통제된 재시도를 추가합니다.
프로토콜이 있어도 모델이 모든 기능을 지원하는 것은 아닙니다
같은 프로토콜의 모델도 입력 모달리티, 도구, 구조화된 출력 및 스트리밍 기능이 다를 수 있습니다. 필드 미지원 또는 모델 사용 불가가 발생하면 모델 정보와 해당 API Reference를 먼저 확인합니다.
다음 단계
- OpenAI SDK로 Chat Completions 또는 Responses를 호출합니다.
- Anthropic SDK로 Messages를 호출합니다.
- Gemini SDK로 Generate Content를 호출합니다.
- 기존 공식 SDK 프로젝트는 공식 SDK 마이그레이션에서 마이그레이션 확인 항목을 볼 수 있습니다.
- 요청에 실패하면 오류 및 문제 해결을 참고합니다.