Aggiungere file

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



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



Montare 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.



Gestire i 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)



Elencare e scaricare i file di sessione

Usa la Files API per elencare i file associati a una sessione e scaricarli. 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. Scaricare un file non richiede un header beta.

# 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 /)