Archivos y artefactos

Archivos y artefactos publicados

Los archivos se almacenan en el entorno del agente. Un artefacto es una copia publicada de un archivo de un entorno alojado por OpenAI. Puedes descargar esa copia incluso después de que venza el entorno.

Subir archivos

Si usas un entorno alojado por OpenAI, incluye los archivos de entrada en environment.files al crear la sesión. Elige una ruta de destino dentro de /workspace para cada archivo.

Usa type: "file_id" con un file_id de la API de archivos, o bien type: "inline" con el valor de data codificado en base64. Ambas opciones requieren el campo path.

Para agregar archivos después de que se conecte el entorno, usa la API de archivos del entorno.

Resolver errores de carga

Al crear una sesión o adjuntar un archivo, la validación de archivos puede devolver un error HTTP 429 con el código files_api_rate_limit_exceeded. Consulta los límites de solicitudes de la API de archivos para ver la respuesta y los pasos que debes seguir para resolver el error.

Si recibes un error HTTP 400, usa error.param y error.message para identificar el dato que debes corregir. Por ejemplo, si la ruta de destino está fuera de /workspace, la API devuelve esta respuesta:

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

El parámetro sigue la estructura de la solicitud. En estos ejemplos, i es el índice del archivo. El primer archivo tiene el índice 0.

Asegúrate de que los datos en base64 y los ID de archivo sean válidos, y elige una ruta absoluta dentro de /workspace. Consulta los límites de archivos. La API devuelve un error HTTP 400 si la ruta de destino pasa por un enlace simbólico, ya existe o contiene un componente demasiado largo.

Si ocurre un error inesperado al instalar un archivo, la API devuelve un error HTTP 500. Antes de volver a intentarlo, comprueba si se creó el archivo en la ruta de destino y sigue las indicaciones para reintentar la solicitud.

Recuperar tus archivos

Desde tu propio entorno

Pídele al agente que guarde el resultado en una ruta que conozcas. Cuando termine el turno, recupera el archivo a través de tu proveedor o de tu infraestructura. Guárdalo en el almacenamiento de tu aplicación antes de que venza el entorno o de que lo elimines.

Los archivos de los entornos que alojas en tu propia infraestructura no se publican a través de la API de artefactos, ni siquiera los que están dentro de /workspace/outputs. Consulta Proveedores de sandbox para saber cómo acceder a los archivos con cada proveedor.

Desde un entorno alojado por OpenAI

Pídele al agente que guarde el archivo dentro de /workspace/outputs, por ejemplo, en /workspace/outputs/report.pdf. Cuando termina el turno, OpenAI publica los resultados como artefactos inmutables.

Pasa a esta función tu cliente de API, el ID de la sesión, el ID del turno completado, la ruta del artefacto y la ruta de destino local. La función obtiene la lista de artefactos y descarga el archivo que coincide tanto con el turno como con la ruta:

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

Consulta la documentación de Obtener la lista de artefactos, Recuperar metadatos y Descargar contenido para conocer los campos de las solicitudes y las respuestas.

Descargar varios archivos

La API descarga un artefacto por solicitud y no ofrece un punto de acceso para descargas por lotes. Para descargar varios archivos, obtén la lista de artefactos y solicita el content de cada archivo. Si quieres hacer una sola descarga, pídele al agente que agrupe los resultados en un archivo ZIP dentro de /workspace/outputs y luego descarga ese archivo como un solo artefacto.

Cuánto tiempo se conservan los archivos

Los artefactos publicados siguen disponibles después de que vence el entorno. Antes de eliminar la sesión, descarga todo lo que necesites conservar.

Esta API no permite subir ni editar artefactos. Para publicar una nueva versión, pídele al agente que actualice el archivo y complete otro turno. Usa el ID del turno y la ruta para distinguir las versiones.

Elimina un artefacto cuando ya no necesites la copia publicada. El archivo del entorno permanece intacto al eliminar el artefacto.

Límites de archivos