ファイルとアーティファクト

ファイルと公開済みアーティファクト

ファイルはエージェントの環境に保存されます。アーティファクトは、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、アーティファクトのパス、ローカルの保存先を渡します。この関数はアーティファクトの一覧を取得し、ターンとパスの両方が一致するファイルをダウンロードします。

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 でダウンロードできるアーティファクトは、1 リクエストにつき 1 件です。一括ダウンロード用のエンドポイントはありません。複数のファイルをダウンロードするには、アーティファクトの一覧を取得し、ファイルごとに content をリクエストします。1 回でダウンロードしたい場合は、結果を ZIP ファイルにまとめて /workspace/outputs 配下に保存するようエージェントに指示し、そのアーカイブを 1 件のアーティファクトとしてダウンロードしてください。

ファイルの保持期間

公開済みのアーティファクトは、環境の有効期限が切れた後も保持されます。保管が必要なものは、セッションを削除する前にダウンロードしてください。

この API では、アーティファクトをアップロードしたり編集したりすることはできません。新しいバージョンを公開するには、エージェントにファイルの更新を指示し、新たなターンを完了させます。各バージョンはターン ID とパスで区別できます。

公開されたコピーが不要になったら、アーティファクトを削除してください。削除後も環境内のファイルはそのまま残ります。

ファイルの上限