Archivos y artefactos

Archivos y artefactos publicados

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

Subir archivos

Para un entorno alojado por OpenAI, proporciona los archivos de entrada en environment.files al crear la sesión. Elige el destino de cada archivo dentro de /workspace.

Usa type: "file_id" con un file_id de la API de archivos, o type: "inline" con data codificado en base64. Ambas formas requieren un path.

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

Recuperar tus archivos

Desde tu propio entorno

Pídele al agente que escriba sus resultados en una ruta conocida. Una vez que finalice el turno, recupera el archivo a través de tu proveedor o infraestructura. Guárdalo en el almacenamiento de tu aplicación antes de que el entorno expire o lo elimines.

Los archivos de entornos autoalojados no se publican a través de la API de artefactos, incluidos los archivos ubicados en /workspace/outputs. Consulta Proveedores de sandbox para obtener información sobre el acceso a archivos específico de cada proveedor.

Desde un entorno alojado por OpenAI

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

Pasa a esta función tu cliente de API, el ID de la sesión, el ID del turno finalizado, la ruta del artefacto y el destino local. La función enumera los 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 las referencias de Listar artefactos, Recuperar metadatos y Descargar contenido para conocer los campos de las solicitudes y respuestas.

Descargar varios archivos

La API descarga un artefacto por solicitud; no ofrece un punto de acceso para descargas por lotes. Para descargar varios archivos, enumera los artefactos y solicita el content de cada archivo. Para realizar 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 único artefacto.

Vida útil de los archivos

Los artefactos publicados se conservan después de que expire el entorno. Descarga todo lo que necesites conservar antes de eliminar la sesión.

Los artefactos no se pueden subir ni editar a través de esta API. 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. La eliminación deja intacto el archivo en el entorno.

Límites de archivos