프롬프트 객체에서 마이그레이션하기

프롬프트 객체에서 마이그레이션하기 (Migrate from prompt objects)

OpenAI는 API에서 재사용 가능한 프롬프트 객체를 폐기(deprecate)하고 있어요. 프롬프트 생성은 2026년 6월 3일부터 비중이 줄어들고, v1/prompts는 2026년 11월 30일에 종료될 예정이에요. 자세한 일정은 deprecations 페이지를 확인하세요.

출처: 문서

본문

OpenAI API 플랫폼의 Prompts에서 벗어나려면, 프롬프트 내용을 관리되는 prompt 객체에서 꺼내 애플리케이션 코드로 옮기면 돼요. 그러면 리뷰·테스트·배포·버전 관리에 대한 통제력을 더 확보할 수 있어요.

Before: 프롬프트 객체 사용하기

from openai import OpenAI

client = OpenAI()
prompt_id = "pmpt_123"

response = client.responses.create(
    prompt={
        "prompt_id": prompt_id,
        "version": "1",
        "variables": {
            "customer_name": "Acme",
            "issue": "billing question",
        },
    }
)

After: 코드에 프롬프트 인라인하기

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "system",
            "content": "You are a helpful support assistant. Be concise, accurate, and friendly.",
        },
        {
            "role": "user",
            "content": "Customer name: Acme. Issue: billing question. Write a response to the customer.",
        },
    ],
)

print(response.output_text)

Codex로 마이그레이션하기

마이그레이션을 자동화하고 OpenAI API 개발을 빠르게 하려면 OpenAI Developers 플러그인과 OpenAI Docs 스킬을 쓰세요.

$openai-docs update this project to store prompts in code instead of using a prompts object

무엇이 바뀌나요

API 요청에서 저장된 프롬프트 객체를 참조하는 대신, 프롬프트 텍스트를 코드베이스에 저장하고 생성한 메시지를 Responses API 호출의 input으로 직접 전달해요.

프롬프트 내용을 소스 코드로 옮겨서, 프롬프트 변경이 제품 로직과 같은 리뷰·릴리스 프로세스를 거치게 해요.
프롬프트 변수를 함수 인자로 바꿔서, 동적 값이 앱에서 명시적이고 타입이 있게 해요.
References API 호출에서 prompt 객체 대신 input으로 메시지를 전달해요.
버저닝을 저장소로 옮겨서 git 커밋, PR 리뷰, 테스트·evals를 쓰게 해요.
정적 콘텐츠를 앞에, 동적 콘텐츠를 뒤에 두어 프롬프트 캐싱 이점을 유지해요. 캐시 히트는 정확한 prefix 일치에 의존하니까요.

예시: 헬퍼 함수로 프롬프트 만들기

from openai import OpenAI

client = OpenAI()


def build_support_prompt(customer_name, issue):
    return [
        {
            "role": "system",
            "content": "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.",
        },
        {
            "role": "user",
            "content": f"Customer name: {customer_name}. Issue: {issue}. Write a response to the customer.",
        },
    ]


response = client.responses.create(
    model="gpt-6-astra",
    input=build_support_prompt(
        customer_name="Acme",
        issue="billing question",
    ),
)

무엇을 얻게 되나요

엔지니어링 통제력이 강해져요. 프롬프트가 제품 코드와 함께 있고, 변경은 PR을 거치며, 테스트와 evals를 CI에서 돌리고, 롤아웃·실험은 자체 설정이나 feature flag로 관리할 수 있어요.

프롬프트를 코드베이스 전체에 인라인으로 흩뜨리지 마세요. 작은 prompts/ 모듈을 만들고, 각 프롬프트를 이름 있는 빌더 함수로 두고, 가벼운 eval fixture를 추가해서 프롬프트 변경이 제품 로직처럼 리뷰되게 하세요.

프롬프트 객체에서 마이그레이션하기