Responses API 복구 워크플로: Responses API을 실제 에이전트 프로젝트 복구 경로에 넣습니다.

채팅 완료부터 Responses API까지: 반드시 알아야 할 마이그레이션 문제점

에이전트를 채팅 완료에서 Responses API로 마이그레이션하는 경우 새 인터페이스가 텍스트 생성, 도구 호출 및 파일 처리와 같은 여러 엔드포인트를 통합하지만 복구 논리가 간단하지 않다는 것을 곧 알게 될 것입니다. 이 문서에서는 특정 모순, 즉 API 호출이 실패할 때 전체 에이전트 링크에 영향을 주지 않고 복구하는 방법에 중점을 둡니다.

복구 작업 흐름에서 Responses API의 역할

Responses API은 두 가지 주요 역할을 수행합니다.

통합 응답 컨테이너: 모델 출력, 도구 호출 결과 및 파일 참조를 응답 개체에 패키지합니다. 여러 엔드포인트의 출력을 함께 연결하는 대신 이 개체 하나만 처리하면 됩니다.
상태 앵커: 각 응답에는 후속 추적, 재시도 또는 대체에 사용할 수 있는 고유 ID가 있습니다. 이는 응답 ID를 복구 체크포인트로 사용할 수 있음을 의미합니다.

그러나 통합은 결합 위험도 가져옵니다. 요청에는 텍스트와 여러 도구 호출이 동시에 포함될 수 있으며 하위 작업이 실패하면 전체 응답이 기대에 미치지 못하게 됩니다.

run_with_recovery 함수와 다운그레이드 로직은 텍스트의 코드 예제에 해당하는 코드 편집기에 표시됩니다.

실패 모드 목록: 작업 흐름을 중단시키는 상황

실제 작동에서는 다음 세 가지 실패 모드가 가장 일반적입니다.

1. 도구 호출 시간 초과 또는 예외

모델이 외부 도구(예: 데이터베이스 검색)를 호출하기로 결정하고 도구가 지정된 시간 내에 결과를 반환하지 않는 경우 전체 응답은 incomplete로 표시될 수 있습니다. 이 상태를 캡처하지 않으면 에이전트가 중단됩니다.

2. 응답 잘림(truncation)

max_tokens 제한으로 인해 모델 출력이 잘릴 수 있습니다. 이때 응답 객체의 truncated 필드는 true이지만 많은 사람들은 이를 무시하고 불완전한 출력을 직접 사용하여 다음 결정을 내릴 것입니다.

3. 콘텐츠 필터링 히트

OpenAI의 콘텐츠 보안 정책에 의해 모델 출력이 차단된 경우 응답 상태는 filtered가 됩니다. 이러한 상황은 에이전트가 코드나 민감한 텍스트를 생성할 때 쉽게 발생할 수 있습니다.

run_with_recovery 함수와 다운그레이드 로직은 텍스트의 코드 예제에 해당하는 코드 편집기에 표시됩니다.

대체 인터페이스 선택: Assistant API를 사용해야 하는 경우와 채팅 완료로 다운그레이드하는 경우

모든 장애에 복잡한 복구가 필요한 것은 아닙니다. 다음 전략에 따라 채점하는 것이 좋습니다.

시간 초과/잘림 → 동일한 입력(최대 3회)으로 직접 재시도하고 max_tokens를 늘리거나 도구 시간 초과 임계값을 줄입니다.
도구 호출 실패 → 도구가 계속해서 실패하는 경우 해당 도구를 도구 목록에서 일시적으로 제거해야 하며, 에이전트 무한 루프를 피하기 위해 일반 텍스트 응답을 사용하여 사용자에게 "도구를 사용할 수 없습니다"라고 알려야 합니다.
콘텐츠 필터링/지속적인 실패 → 채팅 완료 API로 다운그레이드하여 간단한 시스템 프롬프트만 사용하고 도구 호출 없이 사용자에게 최소한의 철저한 응답을 제공할 수 있도록 합니다.

코드 다이어그램(Python):

def run_with_recovery(messages, tools):
    try:
        response = client.responses.create(
            model="gpt-4o",
            input=messages,
            tools=tools
        )
        if response.status == "incomplete":
            # 检查 truncation
            if response.truncated:
                return retry_with_increased_tokens(messages, tools)
            # 检查工具超时
            if any(call.status == "failed" for call in response.tool_calls):
                return fallback_to_chat(messages)
        return response
    except Exception:
        return fallback_to_chat(messages)

工具调用的恢复陷阱

Responses API 的 tool_calls 数组里每个元素都有 id、type、status。最容易踩的坑是：

只检查 status 是否为 "completed"，忽略 "failed" 状态。
把失败的工具调用结果拼到 conversation history 里，导致模型后续重复尝试相同工具。

正确做法：对失败的工具调用，添加一条 assistant 消息说明“该工具暂时不可用”，并设置 output_tools 매개변수는 모델이 다시 호출되는 것을 금지합니다.

실제 시나리오: 사용자가 실시간 주식 데이터를 쿼리합니다.

에이전트가 주가 API를 호출해야 한다고 가정해 보겠습니다.

일반 프로세스: Responses API가 스톡 도구를 호출하고 데이터를 반환하면 에이전트가 답변을 생성합니다.
실패 시나리오: Stock API 시간 초과(5초 동안 응답이 없음).
내 복구: 공구 호출 상태 실패 감지 → 도구 목록에서 공구 제거 → 채팅 완료 호출을 통해 다운그레이드하고 "현재 실시간 가격을 얻을 수 없습니다. 나중에 다시 시도하십시오"라고 응답합니다.

이 프로세스를 통해 다운스트림 인터페이스 오류로 인해 에이전트가 완전히 충돌하지 않도록 할 수 있습니다.

재시도를 중지하고 대체를 시작해야 하는 경우

무한정 재시도하지 마세요. 나는 다음을 설정했다:

동일한 입력을 최대 3회까지 재시도
3회 실패 시 다운그레이드 모드 진입
다운그레이드 모드는 5분 동안 지속되며 그 이후에는 원래 도구 목록이 자동으로 복원됩니다.

다음 단계: 일반 개발자에서 에이전트 엔지니어로

위의 복구 설계는 단지 시작점일 뿐입니다. 프로덕션에서 Responses API을(를) 완전히 마스터하려면 컨텍스트 창 관리, 다중 에이전트 조정, 권한 모델 등 더 많은 것을 이해해야 합니다. 이러한 내용은 고급과정에서 체계적으로 설명됩니다.