Fichiers et artefacts

Fichiers et artefacts publiés

Les fichiers sont stockés dans l’environnement de l’agent. Un artefact est une copie publiée d’un fichier provenant d’un environnement hébergé par OpenAI. Vous pouvez télécharger cette copie après l’expiration de l’environnement.

Importer des fichiers

Pour un environnement hébergé par OpenAI, indiquez les fichiers d’entrée dans environment.files lors de la création de la session. Choisissez un chemin de destination dans /workspace pour chaque fichier.

Utilisez type: "file_id" avec un file_id obtenu via l’API Files, ou type: "inline" avec les données encodées en base64 dans data. Dans les deux cas, le champ path est obligatoire.

Pour ajouter des fichiers une fois l’environnement connecté, utilisez l’API Files de l’environnement.

Résoudre les erreurs d’importation

Lors de la création d’une session ou de l’ajout d’un fichier, la vérification des fichiers peut renvoyer une erreur HTTP 429 avec le code files_api_rate_limit_exceeded. Consultez les limites de débit de l’API Files pour connaître le contenu de la réponse et la marche à suivre.

En cas d’erreur HTTP 400, utilisez error.param et error.message pour identifier la valeur à corriger. Par exemple, si la destination se trouve en dehors de /workspace, l’API renvoie la réponse suivante :

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

Le nom du paramètre reflète la structure de la requête. Ici, i correspond à l’indice du fichier. Le premier fichier a pour indice 0.

Vérifiez que les données encodées en base64 et les identifiants de fichiers sont valides, puis choisissez un chemin absolu dans /workspace. Consultez les limites applicables aux fichiers. L’API renvoie une erreur HTTP 400 si la destination existe déjà, si son chemin passe par un lien symbolique ou si l’un des composants du chemin est trop long.

Si une erreur inattendue survient pendant l’installation d’un fichier, l’API renvoie une erreur HTTP 500. Avant de réessayer, vérifiez si le fichier a été créé à l’emplacement prévu, puis suivez les consignes pour réessayer après une erreur transitoire.

Récupérer vos fichiers

Depuis votre propre environnement

Demandez à l’agent d’enregistrer son résultat à un emplacement connu. Une fois le tour terminé, récupérez le fichier via votre fournisseur ou votre infrastructure. Enregistrez-le dans l’espace de stockage de votre application avant que l’environnement n’expire ou que vous le supprimiez.

L’API Artifacts ne publie pas les fichiers des environnements auto-hébergés, y compris ceux qui se trouvent dans /workspace/outputs. Consultez la section Fournisseurs de bacs à sable pour savoir comment accéder aux fichiers selon votre fournisseur.

Depuis un environnement hébergé par OpenAI

Demandez à l’agent d’enregistrer le fichier dans /workspace/outputs, par exemple à l’emplacement /workspace/outputs/report.pdf. À la fin du tour, OpenAI publie les fichiers de sortie sous forme d’artefacts immuables.

Passez à cette fonction votre client API, l’identifiant de la session, l’identifiant du tour terminé, le chemin de l’artefact et la destination locale. Elle liste les artefacts et télécharge le fichier qui correspond à la fois au tour et au chemin indiqués.

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}")

Pour connaître les champs des requêtes et des réponses, consultez les pages de référence Lister les artefacts, Récupérer les métadonnées et Télécharger le contenu.

Télécharger plusieurs fichiers

L’API permet de télécharger un seul artefact par requête et ne propose aucun point de terminaison pour le téléchargement par lots. Pour télécharger plusieurs fichiers, listez les artefacts, puis demandez le contenu de chaque fichier via content. Pour tout récupérer en un seul téléchargement, demandez à l’agent de regrouper les résultats dans une archive ZIP dans /workspace/outputs, puis téléchargez cette archive sous forme d’un seul artefact.

Durée de conservation des fichiers

Les artefacts publiés restent disponibles après l’expiration de l’environnement. Avant de supprimer la session, téléchargez tous les fichiers que vous souhaitez conserver.

Cette API ne permet ni d’importer ni de modifier des artefacts. Pour publier une nouvelle version, demandez à l’agent de mettre à jour le fichier et de terminer un nouveau tour. Utilisez l’identifiant du tour et le chemin du fichier pour distinguer les versions.

Supprimez un artefact lorsque vous n’avez plus besoin de la copie publiée. Le fichier reste intact dans l’environnement.

Limites applicables aux fichiers