Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 156 lines 6.81 KB
Raw
1 ---
2 title: 'SDKs remove legacy automatic file handling config'
3 description: 'SDKs remove deprecated `autoUploadDownloadFiles` / `auto_upload_download_files`. Automatic file handling is off unless you set `dangerouslyAllowAutoUploadDownloadFiles` / `dangerously_allow_auto_upload_download_files`. Minor releases.'
4 date: '2026-04-24'
5 ---
6
7 The Composio SDKs no longer accept the legacy flags that previously controlled automatic file upload and download during tool execution. Automatic handling of `file_uploadable` fields stays **off by default**; you opt in with the explicit `dangerously*` option only.
8
9 <Callout type="warn">
10 **Breaking change**
11
12 Those legacy properties are removed from the public constructors and config types. Code that still passes them must migrate. Anyone who **relied on the old default-on behavior** (no file flag in the constructor) must now **explicitly** set the `dangerously*` flag to `true` to keep automatic path/URL file handling.
13 </Callout>
14
15 ### SDK versions (minor releases)
16
17 | Package | Previous | This release |
18 | ------- | -------- | ------------ |
19 | TypeScript `@composio/core` | v0.6.11 | **v0.8.0** |
20 | Python `composio` | v0.11.6 | **v0.12.0** |
21
22 Other `@composio/*` npm packages that depend on core are published as **patch** bumps in the same release train (via the changesets `updateInternalDependencies: "patch"` setting) so they pick up the updated `ComposioConfig` surface — they have no public-API changes of their own.
23
24 ### Migration
25
26 Earlier SDK versions treated automatic file upload/download for `file_uploadable` tool fields as **on by default** (TypeScript: `autoUploadDownloadFiles` defaulted to `true` when unset; Python followed the same idea for `auto_upload_download_files` in prior releases). **That default is now off.** If you still want that behavior, you must **explicitly** set `dangerouslyAllowAutoUploadDownloadFiles: true` (TypeScript) or `dangerously_allow_auto_upload_download_files=True` (Python).
27
28 **TypeScript — before (legacy):**
29
30 ```typescript
31 // @noErrors
32 // If you omitted autoUploadDownloadFiles, it used to default to true
33 new Composio({
34 apiKey: process.env.COMPOSIO_API_KEY!,
35 });
36
37 // Equivalent when you set it explicitly:
38 new Composio({
39 apiKey: process.env.COMPOSIO_API_KEY!,
40 autoUploadDownloadFiles: true,
41 });
42 ```
43
44 **TypeScript — going forward** (set `true` to match either legacy pattern above):
45
46 ```typescript
47 // @noErrors
48 new Composio({
49 apiKey: process.env.COMPOSIO_API_KEY!,
50 dangerouslyAllowAutoUploadDownloadFiles: true,
51 });
52 ```
53
54 To leave automatic file handling **off** (new default), omit `dangerouslyAllowAutoUploadDownloadFiles` or set it to `false`.
55
56 **Python — before (legacy):**
57
58 ```python
59 # If you omitted auto_upload_download_files, it used to default to True (prior releases)
60 Composio(api_key="...")
61
62 # Equivalent when you set it explicitly:
63 Composio(api_key="...", auto_upload_download_files=True)
64 ```
65
66 **Python — going forward** (set `True` to match either legacy pattern above):
67
68 ```python
69 Composio(api_key="...", dangerously_allow_auto_upload_download_files=True)
70 ```
71
72 If you construct `ToolRouterSession` directly (unusual), the keyword argument is now `dangerously_allow_auto_upload_download_files` instead of `auto_upload_download_files`.
73
74 ### Local paths must live inside an allowlisted directory
75
76 Even with `dangerouslyAllowAutoUploadDownloadFiles` enabled, the SDK will **only** auto-upload local file paths that resolve inside an allowlisted directory. Paths outside the allowlist are rejected with `ComposioFileUploadPathNotAllowed` (TypeScript) / `FileUploadPathNotAllowed` (Python) before any file is read or sent.
77
78 This is a behavior change. Earlier SDK versions had no allowlist: any local path the legacy default-on flag saw was uploaded.
79
80 **Default allowlist:**
81
82 | `fileUploadDirs` value | Effective allowlist |
83 | ---------------------- | ------------------- |
84 | omitted / `undefined` | `[ <home>/.composio/temp ]` (default staging dir) |
85 | `false` | `[]` — **all** local paths rejected (URLs and `File` objects still work) |
86 | `[]` | `[]` — same as `false`; explicit "no local paths" |
87 | `[<dir1>, <dir2>, …]` | exactly those directories (replaces the default; `~` is expanded, paths are `realpath`-resolved, comparison is on a path-component boundary) |
88
89 URLs (`http://…` / `https://…`) and JavaScript `File` objects are **not** subject to the allowlist — only local string paths are.
90
91 **TypeScript:**
92
93 ```typescript
94 // @noErrors
95 // Match the *broadest* legacy behavior: auto-upload on, allowlist widened to
96 // the directories your code actually reads from. Set this scope as tightly
97 // as you can — every path inside these dirs becomes uploadable to Composio.
98 new Composio({
99 apiKey: process.env.COMPOSIO_API_KEY!,
100 dangerouslyAllowAutoUploadDownloadFiles: true,
101 fileUploadDirs: ['/srv/uploads', '~/data/inbox'],
102 });
103
104 // Disallow local-path uploads entirely; the SDK will only stage URLs and
105 // File objects, and reject string paths outright.
106 new Composio({
107 apiKey: process.env.COMPOSIO_API_KEY!,
108 dangerouslyAllowAutoUploadDownloadFiles: true,
109 fileUploadDirs: false,
110 });
111 ```
112
113 **Python:**
114
115 ```python
116 # Equivalent of the TypeScript example above.
117 Composio(
118 api_key="...",
119 dangerously_allow_auto_upload_download_files=True,
120 file_upload_dirs=["/srv/uploads", "~/data/inbox"],
121 )
122
123 # Reject all local paths.
124 Composio(
125 api_key="...",
126 dangerously_allow_auto_upload_download_files=True,
127 file_upload_dirs=False,
128 )
129 ```
130
131 **Manual staging (TypeScript only):**
132
133 If you don't want to widen the allowlist, the TypeScript SDK lets you stage files yourself via `composio.files.upload(...)`. That call **bypasses the allowlist** by design (the caller is expected to control the path), and the returned `{ name, mimetype, s3key }` descriptor can be passed straight into `tools.execute`:
134
135 ```typescript
136 // @noErrors
137 const staged = await composio.files.upload({
138 file: '/anywhere/on/disk/report.pdf',
139 toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE',
140 toolkitSlug: 'googledrive',
141 });
142
143 await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {
144 userId: 'user-1',
145 arguments: { file_to_upload: staged },
146 });
147 ```
148
149 The Python SDK does not currently expose a top-level manual-staging API; opt in with `dangerously_allow_auto_upload_download_files=True` and configure `file_upload_dirs` to cover the directories your code reads from.
150
151 ### What else changed
152
153 - TypeScript: `resolveAutoUploadDownloadFilesEnabled` only considers `dangerouslyAllowAutoUploadDownloadFiles`; the old deprecation warning for the legacy property is removed.
154 - Python: the small `composio.utils.auto_upload_download` helper that merged legacy + new flags is removed; `Tools` and `ToolRouter` take only the explicit opt-in boolean.
155
156 Documentation for [executing tools](/docs/tools-direct/executing-tools) and the TypeScript [Composio reference](/reference/sdk-reference/typescript/composio) is updated to describe defaults and the opt-in flag.