파일과 아티팩트

파일과 게시된 아티팩트

파일은 에이전트 환경에 저장됩니다. 아티팩트는 OpenAI 호스팅 환경에서 게시한 파일 사본입니다. 환경이 만료된 후에도 이 사본을 다운로드할 수 있습니다.

파일 업로드

OpenAI 호스팅 환경에서는 세션을 생성할 때 environment.files에 입력 파일을 지정하세요. 각 파일의 저장 경로는 /workspace 아래에 지정하세요.

type: "file_id"를 사용하려면 file_id에 Files API에서 받은 값을 지정하세요. type: "inline"을 사용하려면 base64로 인코딩한 데이터를 data에 지정하세요. 두 방식 모두 path가 필요합니다.

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

업로드 오류 해결

세션을 생성하거나 파일을 첨부할 때 파일 검사 과정에서 HTTP 429와 함께 files_api_rate_limit_exceeded가 반환될 수 있습니다. 응답 내용과 복구 절차는 Files API 요청 한도에서 확인하세요.

HTTP 400이 반환되면 error.param과 error.message를 확인해 어떤 입력값을 수정해야 하는지 파악하세요. 예를 들어 저장 경로가 /workspace 밖에 있으면 다음 응답이 반환됩니다.

12345678{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

오류에 표시되는 매개변수는 요청 구조를 따릅니다. 아래 예시에서 i는 파일의 인덱스이며, 첫 번째 파일의 인덱스는 0입니다.

유효한 base64 데이터와 파일 ID를 사용하고 /workspace 아래의 절대 경로를 지정하세요. 파일 한도도 확인하세요. 저장 경로가 심볼릭 링크를 거치거나, 해당 경로에 이미 파일이나 디렉터리가 있거나, 경로 구성 요소가 너무 길면 HTTP 400이 반환됩니다.

파일을 설치하는 중에 예기치 않은 오류가 발생하면 HTTP 500이 반환됩니다. 다시 시도하기 전에 지정한 경로에 파일이 생성되었는지 확인한 후 재시도 지침을 따르세요.

파일 가져오기

자체 호스팅 환경에서 가져오기

에이전트에게 저장 경로를 지정해 주고 그 경로에 결과물을 저장하도록 요청하세요. 턴이 완료되면 제공업체나 자체 인프라를 통해 파일을 가져오세요. 환경이 만료되거나 환경을 삭제하기 전에 파일을 애플리케이션 스토리지에 저장하세요.

자체 호스팅 환경의 파일은 /workspace/outputs 아래에 있어도 Artifacts API를 통해 게시되지 않습니다. 제공업체별 파일 접근 방법은 샌드박스 제공업체 문서에서 확인하세요.

OpenAI 호스팅 환경에서 가져오기

에이전트에게 파일을 /workspace/outputs 아래에 저장하도록 요청하세요. 예를 들어 /workspace/outputs/report.pdf에 저장할 수 있습니다. 턴이 완료되면 OpenAI는 결과물을 변경할 수 없는 아티팩트로 게시합니다.

다음 함수에 API 클라이언트, 세션 ID, 완료된 턴의 ID, 아티팩트 경로, 로컬 저장 경로를 전달하세요. 이 함수는 아티팩트 목록을 조회한 뒤 턴 ID와 경로가 모두 일치하는 파일을 다운로드합니다.

1
2
3
4
5
6
7
8
9
10
11# 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}")

요청 및 응답 필드는 아티팩트 목록 조회, 메타데이터 조회, 콘텐츠 다운로드 문서에서 확인하세요.

여러 파일 다운로드

API는 요청당 아티팩트 하나를 다운로드하며 일괄 다운로드 엔드포인트는 제공하지 않습니다. 여러 파일을 다운로드하려면 아티팩트 목록을 조회한 후 각 파일의 content를 요청하세요. 한 번에 다운로드하려면 에이전트에게 결과물을 ZIP 파일 하나로 묶어 /workspace/outputs 아래에 저장하도록 요청한 후 해당 압축 파일을 하나의 아티팩트로 다운로드하세요.

파일 보관 기간

게시된 아티팩트는 환경이 만료된 후에도 유지됩니다. 보관할 파일은 세션을 삭제하기 전에 다운로드하세요.

이 API로는 아티팩트를 업로드하거나 수정할 수 없습니다. 새 버전을 게시하려면 에이전트에게 다음 턴에서 파일을 수정하고 해당 턴을 완료하도록 요청하세요. 턴 ID와 경로로 버전을 구분할 수 있습니다.

게시된 사본이 더 이상 필요하지 않으면 아티팩트를 삭제하세요. 아티팩트를 삭제해도 환경에 있는 파일은 그대로 유지됩니다.

파일 한도