Files and artifacts

​

Upload a file

with open("sales.csv", "rb") as f:
    uploaded = client.files.create(file=("sales.csv", f), purpose="user_data")
print(uploaded.id)

​

Put files in the sandbox

• {"type": "file_id", "file_id": ..., "path": ...} copies an uploaded file.
• {"type": "inline", "data": <base64>, "path": ...} sends small content directly.

​

Get results back as artifacts

from pathlib import Path

agents = client.beta.agents

# 1. Upload the input once.
uploaded = client.files.create(
    file=("input.txt", b"source material"),
    purpose="user_data",
)

# 2. Copy it into a new sandbox.
session = agents.sessions.create(
    agent_id=agent.id,
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {"type": "file_id", "file_id": uploaded.id, "path": "/workspace/input.txt"},
        ],
    },
)

# 3. Ask for a result in /workspace/outputs and read the stream to the end.
prompt = "Read input.txt and write a summary to /workspace/outputs/summary.txt"
with agents.sessions.stream(session.id, input=prompt) as stream:
    for event in stream:
        pass

# 4. Download every artifact as raw bytes.
for artifact in agents.sessions.artifacts.list(session.id):
    content = agents.sessions.artifacts.content(artifact.id, session_id=session.id)
    Path(Path(artifact.path).name).write_bytes(content.content)

​

How capture works

• Only /workspace/outputs is captured. A file elsewhere in the workspace is not, even if the agent mentions it. For self-hosted environments the folder is outputs inside your workspace_directory.
• Only completed turns are captured. A failed or cancelled turn produces no artifacts.
• Artifacts never change. If the agent edits a file in a later turn, that turn gets a new artifact, and the old one keeps the old content.
• Symbolic links are skipped.
• Size limits apply: 64 MiB per file, 256 MiB and 4,096 entries per capture. If the outputs folder exceeds them, nothing from that turn is captured. The turn itself still completes, so an empty artifact list after a big job can mean this.

​

Tips

• Be explicit in your instructions. “Write the report to /workspace/outputs/report.md” works much better than “create a report”.
• Save bytes, not text. Artifacts can be images, PDFs, or archives. Write the raw content to disk rather than decoding it as UTF-8.
• Download before you delete. Deleting a session deletes its artifacts.
• Treat outputs as untrusted. The agent produced them, possibly from untrusted input. Check them before opening or executing them.
• Keep secrets out of staged files. Anything in the workspace is visible to the agent and to commands it runs. Use vaults for credentials.

​

Common mistakes