1# File Operations
2 
3Manage files within a hosted agent session. All file operations require an active session with a running sandbox.
4 
5## Overview
6 
7Hosted agent sessions provide a persistent filesystem rooted at `$HOME` (`/home/session`). Files written to this path survive across requests within the same session. Use the session file tools to upload input data, download outputs, and manage the session filesystem externally.
8 
9> ⚠️ **Warning:** All file paths are relative to `$HOME`. For example, `filePath: '/data/input.csv'` maps to `/home/session/data/input.csv` inside the container.
10 
11## MCP Tool Details
12 
13### Upload File
14 
15Use `session_file_upload` to write a file into the session:
16 
17| Parameter | Required | Description |
18|-----------|----------|-------------|
19| `projectEndpoint` | ✅ | AI Foundry project endpoint |
20| `agentName` | ✅ | Name of the hosted agent |
21| `sessionId` | ✅ | Active session ID |
22| `filePath` | ✅ | Destination path (e.g., `/data/input.csv`) |
23| `contentBase64` | ✅ | File content as a base64-encoded string |
24 
25> 💡 **Tip:** For text files, encode the content to base64 before passing it. For binary files (images, PDFs), read the raw bytes and base64-encode them.
26 
27### Download File
28 
29Use `session_file_download` to retrieve a file from the session:
30 
31| Parameter | Required | Description |
32|-----------|----------|-------------|
33| `projectEndpoint` | ✅ | AI Foundry project endpoint |
34| `agentName` | ✅ | Name of the hosted agent |
35| `sessionId` | ✅ | Active session ID |
36| `filePath` | ✅ | Path to the file to download (e.g., `/data/output.csv`) |
37 
38Returns: File content as a base64-encoded string.
39 
40### List Files
41 
42Use `session_file_list` to browse the session filesystem:
43 
44| Parameter | Required | Description |
45|-----------|----------|-------------|
46| `projectEndpoint` | ✅ | AI Foundry project endpoint |
47| `agentName` | ✅ | Name of the hosted agent |
48| `sessionId` | ✅ | Active session ID |
49| `path` | ❌ | Directory path to list (defaults to root `/`) |
50 
51Returns: List of files and directories with metadata.
52 
53### Delete File
54 
55Use `session_file_delete` to remove a file or directory:
56 
57| Parameter | Required | Description |
58|-----------|----------|-------------|
59| `projectEndpoint` | ✅ | AI Foundry project endpoint |
60| `agentName` | ✅ | Name of the hosted agent |
61| `sessionId` | ✅ | Active session ID |
62| `filePath` | ✅ | Path to delete |
63| `recursive` | ❌ | Set `true` to recursively delete a directory and its contents (default `false`) |
64 
65> ⚠️ **Warning:** Non-recursive delete on a non-empty directory will fail. Use `recursive: true` for directories with contents.
66 
67### Get File Metadata
68 
69Use `session_file_stat` to inspect a file or directory:
70 
71| Parameter | Required | Description |
72|-----------|----------|-------------|
73| `projectEndpoint` | ✅ | AI Foundry project endpoint |
74| `agentName` | ✅ | Name of the hosted agent |
75| `sessionId` | ✅ | Active session ID |
76| `filePath` | ✅ | Path to inspect |
77 
78Returns: File name, size, whether it is a directory, and last modified time.
79 
80### Create Directory
81 
82Use `session_file_mkdir` to create directories:
83 
84| Parameter | Required | Description |
85|-----------|----------|-------------|
86| `projectEndpoint` | ✅ | AI Foundry project endpoint |
87| `agentName` | ✅ | Name of the hosted agent |
88| `sessionId` | ✅ | Active session ID |
89| `path` | ✅ | Directory path to create (e.g., `/data/results`) |
90| `createParents` | ❌ | Create parent directories if needed (default `true`) |
91| `mode` | ❌ | Unix permission mode (e.g., `755`). Uses system default if omitted |
92 
93## Common Patterns
94 
95### Upload Input → Invoke → Download Output
96 
97```text
981. session_create       → get sessionId
992. session_file_mkdir   → create /data/input/
1003. session_file_upload  → upload input files to /data/input/
1014. agent_invoke         → tell agent to process /data/input/
1025. session_file_list    → check /data/output/ for results
1036. session_file_download → retrieve output files
1047. session_delete       → clean up when done
105```
106 
107### Check Agent-Generated Files
108 
109```text
1101. session_file_list    → browse $HOME to see what the agent created
1112. session_file_stat    → check size/type of specific files
1123. session_file_download → retrieve files of interest
113```
114 
115## Storage Limits
116 
117- Maximum `$HOME` size: **10 GiB** per session
118- Files outside `$HOME` (e.g., `/tmp`) are ephemeral and may be cleared between requests
119 
120## Error Handling
121 
122| Error | Cause | Resolution |
123|-------|-------|------------|
124| Session not active | Session expired or not yet running | Use `session_get` to check status; create a new session if expired |
125| File not found | Invalid path or file does not exist | Use `session_file_list` to verify the path |
126| Directory not empty | Non-recursive delete on a directory with contents | Use `recursive: true` |
127| Storage limit exceeded | `$HOME` exceeds 10 GiB | Delete unnecessary files with `session_file_delete` |
128