Skip to main content
Context

File Upload and Mounting

Files are independently managed resources that can be mounted to multiple sessions. Their lifecycle is decoupled from sessions. Upload and manage files via the Files menu in the console.

Quotas and Limits

  • Maximum size per file: 10 MB
  • Total file storage quota per workspace: 100 GB
  • File retention period: 30 days — files may be automatically cleaned up after expiration. For long-term retention, re-upload files periodically.

Uploading Files

On the Files page, click Upload File, then select and upload a local file. After upload, files enter a security review state (checking). They become available only after passing review and can then be mounted to sessions. Files failing review are marked as rejected or type_rejected. To upload files via API, submit using multipart/form-data. Full parameters and response fields are documented in the File API. 
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/files" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F "file=@./sales_2025.csv"

Session Isolation

When a file is mounted to a session, the service creates an internal copy and injects it into the session’s sandbox. The original file remains unaffected by any modifications made inside the session. You can view the actual mounted copy in the session details.

Mounting Files to Sessions

Mounting During Session Creation

In the New Session drawer, under the Mounted Resources section, click Add File, select an already-uploaded file, and specify its mount path—for example, /workspace/data.csv.

Mounting at Runtime

After a session has been created, go to the Resources panel on the right side of the session page and click Mount File to add more files. Mounting takes effect immediately—no session restart is required.

Path Prefix

All specified mount paths are automatically prefixed with /mnt/session/uploads. For example:
Specified PathActual Path (visible to the agent)
/workspace/data.csv→/mnt/session/uploads/workspace/data.csv
/data/sales.xlsx→/mnt/session/uploads/data/sales.xlsx
Agents must use the actual path when accessing files in tool calls. In system prompts, you may directly provide the full path—for example: “The data file is located at /mnt/session/uploads/workspace/data.csv.”

Unmounting

In the Resources panel, click Unmount next to the target file. This removes the session-specific copy; the original file remains unchanged. To mount files via API:
  • At session creation, include them in the resources field.
  • During runtime, send a POST request to /sessions/{session_id}/resources.
    Full parameter and response documentation is available in the Session API.
# Mount during session creation
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "environment_id": "env_xxx",
    "resources": [
      {"type": "file", "file_id": "file_xxx", "mount_path": "/workspace/data.csv"}
    ]
  }'

# Mount at runtime
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions/sesn_xxx/resources" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "file", "file_id": "file_xxx", "mount_path": "/workspace/late.csv"}'

Deleting Files

Files support only deletion—not archival. On the Files page, click Delete next to the target file to permanently delete it. This action is irreversible. Mounted copies in active sessions remain unaffected. 
curl -X DELETE "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/files/file_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Next Steps

Overview
Build Agent
Environment
Sessions
Context
Event Subscriptions
Billing
Changelog