파일과 아티팩트

파일과 아티팩트 (Files and artifacts)

에이전트의 환경에서 파일이 어떻게 보관되고, 완료된 턴의 결과물(artifact)을 어떻게 다운로드하는지 다루는 가이드예요. 파일 업로드, 검색, 수명, 제한을 배워요.

출처: 문서

본문

파일과 게시된 아티팩트

파일은 에이전트의 환경에 살아요. 아티팩트(artifact)는 OpenAI 호스팅 환경의 파일을 게시한 복사본이에요. 환경이 만료된 뒤에도 그 복사본을 다운로드할 수 있어요.

파일 업로드하기

OpenAI 호스팅 환경의 경우 세션을 만들 때 environment.files에 입력 파일을 제공하세요. 각 파일의 대상 위치를 /workspace 아래에서 선택하세요.

Files API의 file_id와 함께 type: "file_id"를 사용하거나, base64로 인코딩된 data와 함께 type: "inline"을 사용하세요. 두 형태 모두 path가 필요해요.

환경이 연결된 뒤 파일을 추가하려면 environment Files API를 사용하세요.

파일 검색하기

자체 환경에서

에이전트에게 출력을 알려진 경로에 쓰도록 요청하세요. 턴이 완료된 뒤 제공자 또는 인프라를 통해 파일을 검색해요. 환경이 만료되거나 삭제되기 전에 애플리케이션 저장소에 저장하세요.

자체 호스팅 환경의 파일은 /workspace/outputs 아래 파일을 포함해 Artifacts API로 게시되지 않아요. 제공자별 파일 접근은 Sandbox providers를 참고하세요.

OpenAI 호스팅 환경에서

에이전트에게 파일을 /workspace/outputs 아래에 저장하도록 요청하세요(예: /workspace/outputs/report.pdf). OpenAI는 턴이 완료될 때 출력을 불변(immutable) 아티팩트로 게시해요.

API 클라이언트, 세션 ID, 완료된 턴 ID, 아티팩트 경로, 로컬 대상 경로를 이 함수에 전달하세요. 아티팩트를 나열하고 턴과 경로가 모두 일치하는 파일을 다운로드해요:

아티팩트 찾고 다운로드하기

# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

요청 및 응답 필드는 List artifacts, Retrieve metadata, Download content 참조를 확인하세요.

여러 파일 다운로드하기

API는 요청당 하나의 아티팩트를 다운로드하며 배치 다운로드 엔드포인트를 제공하지 않아요. 여러 파일을 다운로드하려면 아티팩트를 나열하고 각 파일의 content를 요청하세요. 단일 다운로드의 경우 에이전트에게 결과를 /workspace/outputs 아래 ZIP 파일로 묶도록 요청한 뒤, 그 아카이브를 하나의 아티팩트로 다운로드하세요.

파일 수명

게시된 아티팩트는 환경 만료 후에도 유지돼요. 보존해야 할 것은 세션을 삭제하기 전에 모두 다운로드하세요.

이 API를 통해 아티팩트를 업로드하거나 편집할 수 없어요. 새 버전을 게시하려면 에이전트에게 파일을 업데이트하고 다른 턴을 완료하도록 요청하세요. 버전을 구분하려면 턴 ID와 경로를 사용하세요.

게시된 복사본이 더 이상 필요 없으면 Delete an artifact로 삭제하세요. 삭제해도 환경의 파일은 그대로 남아 있어요.

파일 제한

더 알아보기 (Learn more)

관련 문서: 샌드박스 수명 주기와 OpenAI 호스팅 환경을 참고하세요.