Aggiungere file

Puoi fornire file al tuo agente caricandoli tramite la Files API e montandoli nella sandbox della sessione.

Caricamento dei file

Per prima cosa, carica un file usando la Files API:

file = client.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

Montaggio dei file in una sessione

Monta i file caricati nella sandbox aggiungendoli all'array resources quando crei una sessione:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/data.csv",
        },
    ],
)

Con il mount_path precedente, l'agente legge il file in /mnt/session/uploads/data.csv (vedi Percorsi dei file).

Viene creato un nuovo file_id che fa riferimento all'istanza del file nella sessione. Queste copie non vengono conteggiate nei tuoi limiti di archiviazione.

File multipli

Monta più file aggiungendo voci all'array resources:

resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py"},
]

È supportato un massimo di 500 file per sessione.

Gestione dei file in una sessione in esecuzione

Puoi aggiungere o rimuovere file da una sessione dopo la creazione usando l'API delle risorse di sessione. Ogni risorsa ha un id restituito quando viene aggiunta (o elencata), che usi per le eliminazioni.

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

Elenca tutte le risorse di una sessione con resources.list. Per rimuovere un file, chiama resources.delete con l'ID della risorsa:

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

Elenco e download dei file di sessione

Usa la Files API per elencare i file associati a una sessione e scaricarli. I file che l'agente scrive in /mnt/session/outputs/ compaiono nell'elenco poco dopo che l'agente ha terminato di scriverli, a volte alcuni secondi dopo che la sessione diventa inattiva. Se un file di output che ti aspetti è mancante, ripeti l'elenco dopo un breve intervallo; una volta che compare nell'elenco, il suo caricamento è terminato.

Il filtraggio per scope_id richiede l'header beta managed-agents-2026-04-01, quindi gli esempi di elenco usano il namespace beta dei file e passano esplicitamente tale header.

# Elenca i file associati a una sessione
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for file in files:
    print(file.id, file.filename)

# Scarica un file
content = client.files.download(files.data[0].id)
content.write_to_file("output.txt")

Tipi di file supportati

L'agente può lavorare con qualsiasi tipo di file, inclusi:

• Codice sorgente (.py, .js, .ts, .go, .rs e altri)
• File di dati (.csv, .json, .xml, .yaml)
• Documenti (.txt, .md)
• Archivi (.zip, .tar.gz) - l'agente può estrarli usando bash
• File binari - l'agente può elaborarli con gli strumenti appropriati

Percorsi dei file

• Il percorso che specifichi ha come radice la directory uploads della sessione: un mount_path di /data.csv posiziona il file in /mnt/session/uploads/data.csv nella sandbox
• Se ometti mount_path, il file viene posizionato in /mnt/session/uploads/<file_id>
• Le directory padre vengono create automaticamente
• I percorsi devono essere assoluti (iniziare con /)
• I file che l'agente scrive in /mnt/session/outputs/ diventano disponibili tramite la Files API, associati alla sessione; vedi Elenco e download dei file di sessione