Hosted Session File Operations with azd
Use azd ai agent files to manage files in a Hosted Agent session.
Resolve the Session
File commands use the last session saved by azd ai agent invoke or azd ai agent sessions create. Use --session-id <id> to select another session. Use --agent-name <service-name> when the project has multiple agent services.
Run a successful invoke first unless files must be uploaded before the first request. In that case, create a session explicitly and use the returned agent_session_id.
Commands
Upload a local file. The remote path defaults to the local filename:
azd ai agent files upload ./input.csv
azd ai agent files upload ./input.csv --target-path /data/input.csvDownload a remote file. The local path defaults to the remote basename:
azd ai agent files download /data/output.csv
azd ai agent files download /data/output.csv --target-path ./output.csvList paths and inspect metadata:
azd ai agent files list
azd ai agent files list /data --output table
azd ai agent files stat /data/output.csvmkdir will not automatically create missing parent directories. Create each missing parent directory first:
azd ai agent files mkdir /data
azd ai agent files mkdir /data/inputDelete a file or directory:
azd ai agent files delete /data/old.csv
azd ai agent files delete /data/temp --recursiveRecursive delete must be explicit. Do not add --recursive unless deleting the directory and all contents is intended.
Upload, Invoke, Download
azd ai agent sessions create
azd ai agent files mkdir /data/input
azd ai agent files upload ./input.csv --target-path /data/input/input.csv
azd ai agent invoke "Process /data/input/input.csv and write /data/output/result.csv"
azd ai agent files stat /data/output/result.csv
azd ai agent files download /data/output/result.csv --target-path ./result.csv
azd ai agent sessions stop <session-id>The create command persists the new session, so the later file and invoke commands reuse it without repeating --session-id.
Filesystem Rules
Hosted session files persist under $HOME for the session lifetime. Files outside $HOME, such as /tmp, are ephemeral. Deleting the session permanently removes its persistent filesystem.
Error Handling
| Error | Resolution |
|---|---|
| No saved session | Run azd ai agent invoke, create a session, or pass --session-id |
| Session is stopped or missing | Run azd ai agent sessions show <id> or list; invoke to resume a stopped session |
| File not found | Use azd ai agent files list and stat to verify the path |
| Directory is not empty | Repeat delete with --recursive only after confirming the intended path |
| Header-based isolation fails | Pass the same --user-identity used for invoke and session commands |