Azure OpenAI Responses API 사용하기

채팅 완성(Chat Completions) API와 Assistants API의 기능을 한데 모아 둔 게 바로 Responses API예요. 상태를 유지하는(stateful) 다중 턴 응답을 만들어서 대화형 에이전트에 잘 맞죠. 이 글은 텍스트 응답 생성부터 응답 검색·삭제, compaction(대화 압축), guardrail 필터링까지 핵심 호출을 차례로 보여줘요.

출처: 공식 문서 - Use the Azure OpenAI Responses API

사전 준비

배포된 Azure OpenAI 모델 하나.
인증 방식 하나: API 키(예: AZURE_OPENAI_API_KEY) 또는 Microsoft Entra ID(권장).
언어별 클라이언트 라이브러리 설치:
- Python: pip install openai azure-identity
- .NET: dotnet add package OpenAI, dotnet add package Azure.Identity
- JavaScript/TypeScript: npm install openai @azure/identity
- Java: 프로젝트에 com.openai:openai-java, com.azure:azure-identity 추가
REST 예시를 쓸 땐 AZURE_OPENAI_API_KEY(API 키 방식) 또는 AZURE_OPENAI_AUTH_TOKEN(Entra ID 방식)을 설정해요.

텍스트 응답 생성하기

client.responses.create에 모델과 input을 넘기면 응답이 돌아와요. 권장 방식은 Microsoft Entra ID 인증이고, 아래처럼 토큰 제공자로 DefaultAzureCredential을 쓸 수 있어요.

response = client.responses.create(
    model= "MODEL_NAME",
    input= "This is a test."
)
print(response.model_dump_json(indent= 2 ))

# Microsoft Entra ID 인증(권장)
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),  "https://ai.azure.com/.default"
)

클라이언트의 엔드포인트는 리소스 이름을 포함한 형태로 지정해요: https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/.

응답 검색·삭제하기

생성된 응답은 ID로 다시 조회하거나 삭제할 수 있어요.

client = OpenAI(
    base_url= "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.retrieve( "<response_id>" )
print(response.model_dump_json(indent= 2 ))

삭제도 client.responses.delete("<response_id>")처럼 호출하면 돼요. 서버에 저장된 응답을 지워서 리소스를 정리할 때 쓰죠.

Response 압축하기(Compact)

대화가 길어지면 컨텍스트가 커져요. Responses API는 기존 응답과 입력 항목을 압축된(compacted) 응답 하나로 합쳐서 컨텍스트를 유지하는 기능을 제공해요. 압축 대상 메시지 배열을 그대로 넘기거나, 조회한 응답에서 반환된 items를 그대로 사용해 압축할 수 있어요.

{
    "role" :  "user" ,
    "content" :  "Create a simple landing page for a dog cafe."
},
{
    "id" :  "msg_001" ,
    "type" :  "message" ,
    "status" :  "completed" ,
    "role" :  "assistant" ,
    "content" : [{ "type" :  "output_text" ,  "text" :  "..." }],
}

Guardrail과 콘텐츠 필터링 처리

content_filters 배열은 Microsoft Foundry 확장이라 기본 OpenAI 응답 스키마에는 없어요. 그래서 SDK에서 타입 지정 속성으로 노출되지 않고, 아래처럼 raw/추가 필드로 읽어야 해요.

# content_filters는 Azure 확장이라 model_extra에서 읽어요
content_filters = response.model_extra.get( "content_filters" , [])
for result in content_filters:
    print( f"Source: {result['source_type']} , Blocked: {result['blocked']} " )

입력 항목 목록 조회·파일 입력

List input items로 응답에 보냈던 입력 항목을 조회할 수 있어요. 모델이 추가한 항목(함수 호출, compaction 항목 등)을 포함한 전체 대화 컨텍스트를 살펴보는 데 유용해요.

비전 능력이 있는 모델은 PDF 입력을 지원해요. PDF 파일은 Base64 인코딩 데이터 또는 파일 ID로 제공할 수 있고, 모델이 내용을 해석하도록 각 페이지의 추출된 텍스트와 페이지 이미지가 함께 컨텍스트에 포함돼요.

Azure OpenAI Responses API 사용하기