SDK 및 CLI

SDK 및 CLI (SDKs and CLI)

OpenAI API로 앱을 만들 때 쓸 수 있는 공식 도구들 — 각 언어별 SDK, 터미널용 CLI, 에이전트 오케스트레이션용 Agents SDK — 을 어떻게 시작하면 좋은지 안내해 드릴게요.

출처: 문서

본문

이 페이지는 OpenAI API로 개발하는 주요 방법을 다뤄요: 애플리케이션 코드를 위한 공식 SDK, 셸 중심 워크플로를 위한 OpenAI CLI, 오케스트레이션을 위한 Agents SDK, 그리고 직접 만든 HTTP 클라이언트까지요.

API 키 만들고 내보내기

시작하기 전에 대시보드에서 API 키를 만들고, 그 키를 써서 안전하게 API에 접근해요. 키는 .zshrc 파일 같은 안전한 위치에 저장해 두세요. 키를 만들었다면 터미널에서 환경 변수로 내보내면 돼요.

macOS / Linux:

export OPENAI_API_KEY="your_api_key_here"

Windows (PowerShell):

setx OPENAI_API_KEY "your_api_key_here"

OpenAI SDK는 시스템 환경에서 API 키를 자동으로 읽도록 설정돼 있어요.

공식 SDK 설치

JavaScript — Node.js, Deno, Bun 같은 서버 사이드 환경에서는 공식 TypeScript·JavaScript용 OpenAI SDK를 써요. npm으로 설치:

npm install openai

설치가 끝나면 example.mjs 파일을 만들고 예제 코드를 넣어요:

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

node example.mjs로 실행하면(Deno·Bun도 동일) 잠시 후 API 응답이 출력돼요.

Python — 공식 Python용 OpenAI SDK를 pip로 설치:

pip install openai

example.py 파일을 만들고:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

python example.py로 실행하면 결과가 출력돼요.

.NET — Microsoft와 협력해 C#용 공식 API 클라이언트를 제공해요. NuGet에서 .NET CLI로 설치:

dotnet add package OpenAI

Responses API로 간단한 요청을 보내면:

using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

ResponseResult response = await client.CreateResponseAsync(
    "gpt-6-astra",
    "Say 'this is a test.'"
);

Console.WriteLine($"[ASSISTANT]: {response.GetOutputText()}");

Java — Java용 API 헬퍼는 현재 베타 단계예요. Maven 의존성으로 추가:

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.69.3</version>
</dependency>

Responses API로 간단한 요청을 보내면:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class Main {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    ResponseCreateParams params =
        ResponseCreateParams.builder().input("Say this is a test").model("gpt-6-astra").build();

    Response response = client.responses().create(params);
    response.output().stream()
        .flatMap(item -> item.message().stream())
        .flatMap(message -> message.content().stream())
        .flatMap(content -> content.outputText().stream())
        .forEach(outputText -> System.out.println(outputText.text()));
  }
}

Go — Go용 API 헬퍼도 베타 단계예요. 아래 코드로 라이브러리를 임포트:

import (
	"github.com/openai/openai-go/v3" // imported as openai
)

Responses API로 첫 요청을 보내면:

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()

	resp, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Say this is a test")},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(resp.OutputText())
}

Ruby — 공식 Ruby용 OpenAI SDK를 gem으로 추가:

gem "openai"

example.rb 파일을 만들고:

require "openai"

openai = OpenAI::Client.new

response = openai.responses.create(
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn."
)

puts(response.output_text)

ruby example.rb로 실행하면 결과가 나와요.

CLI — 터미널에서 직접 OpenAI API를 호출하려면 생성된 openai CLI 도구를 설치해요:

brew install openai/tools/openai

셸에서 기본 요청을 보내면:

openai responses create \
  --model "gpt-6-astra" \
  --input "Write a one-sentence bedtime story about a unicorn." \
  --raw-output \
  --transform 'output.#(type=="message").content.0.text'

CLI는 파일에서 구조화된 데이터 추출, 이미지 생성, 음성 제작, jq 같은 셸 도구와 조합한 API 호출 등 반복적인 터미널 워크플로에 유용해요.

Agents SDK 사용하기

위의 공식 SDK는 직접 API 요청을 보낼 때 쓰고, 애플리케이션이 에이전트·도구·핸드오프·가드레일·트레이싱·샌드박스 실행을 위한 코드 우선(code-first) 오케스트레이션이 필요하면 Agents SDK를 사용해요. 직접 API 요청과 코드 우선 오케스트레이션 중 고민된다면 Responses API와 Agents SDK 비교 문서를 참고하세요.

Azure OpenAI 라이브러리

Microsoft Azure 팀이 OpenAI API와 Azure OpenAI 서비스 양쪽 모두와 호환되는 라이브러리를 관리하고 있어요. OpenAI API에서 함께 쓸 수 있는 방법은 아래 문서를 참고하세요.

커뮤니티 라이브러리

아래 라이브러리들은 개발자 커뮤니티가 직접 만들고 관리하는 것들이에요. API 변경 소식을 빠르게 받아보려면 OpenAPI specification 저장소를 지켜봐도 좋아요.

OpenAI는 이 프로젝트들의 정확성이나 보안을 검증하지 않는다는 점 유의하세요. 사용에 따른 책임은 본인에게 있어요!

기타 OpenAI 저장소

  • tiktoken — 토큰 수 세기
  • simple-evals — 간단한 평가 라이브러리
  • mle-bench — 머신러닝 엔지니어 에이전트 평가 라이브러리
  • gym — 강화학습 라이브러리
  • swarm — 교육용 오케스트레이션 저장소

더 알아보기 (Learn more)

CLI의 다양한 워크플로와 명령 패턴은 OpenAI CLI 가이드를 참고하세요. 각 SDK의 더 자세한 기능은 해당 GitHub 저장소의 README에서 확인할 수 있어요.