Apply Patch

Apply Patch

apply_patch 도구는 GPT-5.1이 구조화된 diff로 코드베이스에서 파일을 만들고·업데이트하고·삭제하게 해줘요. 모델은 편집을 제안만 하는 대신, 앱이 적용하고 그 결과를 다시 보고하는 패치 연산을 내보내서 반복적·다단계 코드 편집 워크플로를 가능하게 해요.

출처: 문서

본문

언제 쓰나요

apply_patch를 쓰는 일반적인 시나리오:

• 다중 파일 리팩토링 — 심볼 이름 바꾸기, 헬퍼 추출, 여러 파일에 걸친 모듈 재구성.
• 버그 수정 — 모델이 문제를 진단하고 정밀한 패치를 내보내게 함.
• 테스트·문서 생성 — 코드 변경과 함께 새 테스트 파일, fixture, 문서 생성.
• 마이그레이션·기계적 편집 — 반복적·구조화 업데이트(API 마이그레이션, 타입 주석, 서식 수정 등) 적용.

저장소와 원하는 변경을 텍스트로 설명할 수 있다면, apply_patch는 보통 대응하는 diff를 생성할 수 있어요.

Responses API로 apply patch 도구 사용하기

높은 수준에서 apply_patch를 Responses API와 쓰는 흐름은 이래요.

1. apply_patch 도구로 Responses API를 호출한다. input에 사용 가능한 파일에 대한 컨텍스트(또는 요약)를 주거나, 파일 시스템을 탐색할 도구를 준다. tools=[{"type": "apply_patch"}]로 도구를 활성화한다.
2. 모델이 하나 이상의 패치 연산을 반환하게 한다. Response output에 apply_patch_call 객체가 하나 이상 들어간다. 각 호출은 단일 파일 연산(create, update, delete)을 설명한다.
3. 환경에 패치를 적용한다. 각 apply_patch_call의 operation diff를 해석하고, 작업 디렉터리·저장소에 패치를 적용하고, 각 패치의 성공 여부와 로그·오류 메시지를 기록하는 패치 하네스·스크립트를 실행한다.
4. 패치 결과를 모델에 다시 보고한다. previous_response_id를 쓰거나 대화 항목을 input으로 다시 전달해 Responses API를 다시 호출한다. 각 call_id에 대해 status와 선택적 output 문자열이 있는 apply_patch_call_output 이벤트를 포함한다. 필요하면 계속 편집할 수 있도록 tools=[{"type": "apply_patch"}]를 유지한다.
5. 모델이 계속하거나 변경을 설명하게 한다. 모델이 더 많은 apply_patch_call 연산을 내거나, 무엇을 왜 바꿨는지 인간 대상 설명을 제공할 수 있다.

1단계: 모델에 계획하고 패치를 내보내라고 요청한다. 예시 입력에는 편집할 파일 컨텍스트를 담고 apply_patch 도구로 호출해요. 응답 output에서 type == "apply_patch_call"인 항목을 필터링해요.

from openai import OpenAI

client = OpenAI()

# For brevity, we are including file context in the example input.
# Most agentic use cases should instead equip the model with tools
# for exploring file system state.
RESPONSE_INPUT = """
The user has the following files:
<BEGIN_FILES>
===== lib/fib.py
def fib(n):
    if n <= 1:
        return n
    return fib(n-1) + fib(n-2)

===== run.py
from lib.fib import fib

def main():
  print(fib(42))
<END_FILES>

You are a helpful coding assistant that should assist the user with whatever they
ask.

User query:
Help me rename the fib() function to fibonacci()
"""

response = client.responses.create(
    model="gpt-6-astra",
    input=RESPONSE_INPUT,
    tools=[{"type": "apply_patch"}],
)

# response.output may contain multiple apply_patch_call entries, e.g.:
# - update lib/fib.py
# - update run.py
patch_calls = [
    item.model_dump() for item in response.output if item.type == "apply_patch_call"
]

apply_patch_call 객체 예시는 operation에 type: "update_file"와 path: "lib/fib.py", 그리고 -def fib(n): → +def fibonacci(n): 같은 V4A diff(diff)를 담아요.

2단계: 패치를 적용하고 결과를 다시 보냅니다. 각 호출을 하네스로 적용하고 apply_patch_call_output 이벤트(call_id, status, output)를 만들어 previous_response_id로 후속 요청에 보내요.

from apply_patch_harness import apply_operation  # your implementation

results = []
for call in patch_calls:
    op = call["operation"]
    success, maybe_log_output = apply_operation(op)

    results.append(
        {
            "type": "apply_patch_call_output",
            "call_id": call["call_id"],
            "status": "completed" if success else "failed",
            "output": maybe_log_output,
        }
    )

followup = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=response.id,
    input=results,
    tools=[{"type": "apply_patch"}],
)

패치가 실패하면(예: 파일을 찾을 수 없음) status: "failed"와 함께 도움이 되는 output 문자열을 넣어 모델이 복구하게 해요.

{
  "type": "apply_patch_call_output",
  "call_id": "call_cNWm41dB3RyQcLNOVTIPBWZU",
  "status": "failed",
  "output": "Could not apply patch to lib/foo.py — file not found on disk"
}

Apply patch 연산

패치 하네스는 V4A diff 형식을 해석하고 변경을 적용할 책임이 있어요. 참조 구현은 Python Agents SDK나 TypeScript Agents SDK 코드를 보세요.

패치 하네스 구현하기

apply_patch 도구를 쓸 때는 입력 스키마를 제공하지 않아요. 모델이 operation 객체를 구성하는 법을 알아요. 여러분의 일은:

1. Response에서 연산을 파싱한다. type: "apply_patch_call"인 항목을 스캔하고, 각 호출의 operation.type, operation.path, 가능한 diff를 검사한다.
2. 파일 연산을 적용한다. create_file·update_file은 V4A diff를 파일 시스템·인메모리 워크스페이스에 적용하고, delete_file은 path 파일을 제거한다. 각 연산의 성공 여부와 로그·오류 메시지를 기록한다.
3. apply_patch_call_output 이벤트를 반환한다. 각 call_id에 대해 정확히 하나의 이벤트를 내보낸다. 성공하면 status: "completed", 오류를 만나면 status: "failed"(짧은 인간 가독 output 문자열 포함).

안전과 견고성

• 경로 검증: 디렉터리 트래버설을 막고 허용된 디렉터리로 편집을 제한.
• 백업: 패치 적용 전에 파일 백업(또는 스크래치 복사본에서 작업) 고려.
• 오류 처리: 패치를 적용할 수 없을 때는 항상 정보 있는 output으로 failed 상태 반환.
• 원자성: "전부 또는 전무" 의미론(어떤 패치가 실패하면 롤백)이나 파일별 성공/실패를 결정.

Agents SDK와 함께 쓰기

Agents SDK로 apply patch 도구를 쓸 수도 있어요. 실제 파일 연산을 처리하는 하네스는 여전히 구현해야 하지만, applyDiff(Python apply_diff) 함수로 diff 처리를 처리할 수 있어요. Python 예시는 ApplyPatchTool(editor=editor, needs_approval=True, on_approval=...)을 에이전트의 tools에 붙여 실행해요. 전체 실행 예시는 GitHub에서 볼 수 있어요. TypeScript 예시, Python 예시.

일반적인 오류 처리하기

status: "failed"와 명확한 output 메시지로 모델이 복구하게 해요. 파일을 찾을 수 없으면 "Error: File not found at path 'lib/baz.py'" 같은 출력을, 패치 충돌이면 "Error: Invalid Context:\n@@ def fib(n):" 같은 출력을 반환해요. 모델은 이 오류 메시지를 바탕으로 이후 diff를 조정할 수 있어요(예: 프롬프트에서 파일을 다시 읽거나 변경을 단순화).

모범 사례

• 명확한 파일 컨텍스트를 주세요. Responses API를 호출할 때 파일의 인라인 스냅샷(예시처럼)이나 파일 시스템 탐색 도구(예: shell 도구)를 주세요.
• shell 도구와 함께 쓰는 걸 고려하세요. shell 도구와 함께 쓰면 모델이 파일 시스템 디렉터리를 탐색하고, 파일을 읽고, 키워드를 grep해서 에이전트적 파일 발견·편집을 가능하게 해요.
• 작고 집중된 diff를 장려하세요. 시스템 지시에서 모델을 거대한 재작성보다 최소·목표 편집으로 유도하세요.
• 변경이 깨끗하게 적용되는지 확인하세요. 일련의 패치 후 테스트·린터를 실행하고 실패를 다음 input에 공유해 모델이 고치게 하세요.

사용 메모

apply_patch는 Responses, Chat Completions, Assistants API에서 사용할 수 있고, GPT-5.5, GPT-5.4, GPT-5.2, GPT-5.1 모델을 지원해요.

더 알아보기 (Learn more)

• 도구 사용하기
• Shell 도구
• Python Agents SDK