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

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

ファイルはエージェントの環境内に保存されます。アーティファクトは、OpenAI がホストする環境内のファイルをコピーして公開したものです。このコピーは、環境の有効期限が切れた後もダウンロードできます。

ファイルのアップロード

OpenAI がホストする環境では、セッションの作成時に environment.files で入力ファイルを指定します。各ファイルの保存先は /workspace 配下から選びます。

type: "file_id" と Files API の file_id、または type: "inline" と base64 エンコードされた data を組み合わせて使用します。どちらの形式でも path が必要です。

環境への接続後にファイルを追加するには、環境の Files API を使用します。

ファイルの取得

独自の環境からの取得

あらかじめ決めたパスに出力を書き込むようエージェントに依頼します。ターンが完了したら、プロバイダーまたはインフラストラクチャを通じてファイルを取得します。環境の有効期限が切れる前、または環境を削除する前に、アプリケーションのストレージにファイルを保存してください。

セルフホスト環境のファイルは、/workspace/outputs 配下のファイルも含め、Artifacts API では公開されません。プロバイダーごとのファイルへのアクセス方法については、サンドボックスプロバイダーを参照してください。

OpenAI がホストする環境からの取得

/workspace/outputs/report.pdf など、/workspace/outputs 配下にファイルを保存するようエージェントに依頼します。ターンが完了すると、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 回のダウンロードで取得するには、 /workspace/outputs 配下の ZIP ファイルに結果をまとめるようエージェントに依頼し、そのアーカイブを 1 つのアーティファクトとしてダウンロードします。

ファイルの保持期間

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

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

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

ファイルの制限