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
md 233 lines 9.71 KB
Rendered Raw
1 # Composio Class
2
3 The `Composio` class is the main entry point to the Composio SDK. It initializes the SDK and provides access to all the core functionality.
4
5 ## Initialization
6
7 ```typescript
8 import { Composio } from '@composio/core';
9
10 const composio = new Composio({
11 apiKey: 'your-api-key',
12 baseURL: 'https://api.composio.dev', // Optional: Custom API endpoint
13 allowTracking: true, // Optional: Enable/disable telemetry
14 dangerouslyAllowAutoUploadDownloadFiles: false, // Optional: set to true to opt in to automatic file handling (default: false)
15 sensitiveFileUploadProtection: true, // Optional: block uploads from sensitive paths (Node; default true)
16 fileUploadPathDenySegments: undefined, // Optional: extra path component denylist
17 fileUploadDirs: undefined, // Optional: allowlist for automatic upload (defaults to [~/.composio/temp])
18 fileDownloadDir: undefined, // Optional: where auto-downloaded files are written (defaults to ~/.composio/files)
19 provider: new OpenAIProvider(), // Optional: Custom provider
20 });
21 ```
22
23 ## Configuration Options
24
25 The `Composio` constructor accepts a configuration object with the following properties:
26
27 | Property | Type | Required | Default | Description |
28 | ----------------------- | ------------------------ | -------- | -------------------------- | ---------------------------------------------- |
29 | `apiKey` | string | Yes | - | Your Composio API key |
30 | `baseURL` | string | No | `https://api.composio.dev` | The base URL for the Composio API |
31 | `allowTracking` | boolean | No | `true` | Whether to allow analytics/tracking |
32 | `dangerouslyAllowAutoUploadDownloadFiles` | boolean | No | `false` | Opt in to automatic file upload/download during tool execution |
33 | `sensitiveFileUploadProtection` | `boolean` | No | `true` (Node) | When true, local upload paths are checked against a denylist of sensitive segments and credential-like names before read/upload. |
34 | `fileUploadPathDenySegments` | `string[]` | No | `undefined` | Additional path *components* merged with the built-in denylist. |
35 | `fileUploadDirs` | `string[] \| false` | No | `[~/.composio/temp]` | Allowlist of directories from which the SDK may read local files during **automatic** upload (when `dangerouslyAllowAutoUploadDownloadFiles: true`). Pass `false` (or `[]`) to reject every local path; URLs and `File`/`Blob` objects still work. Providing a list **replaces** the default — include `~/.composio/temp` explicitly if you want the default staging dir to keep working. Does **not** affect manual `composio.files.upload()` calls. |
36 | `fileDownloadDir` | `string` | No | `~/.composio/files` | Directory where files downloaded during tool execution (and `composio.files.download()`) are written. Relative paths resolve against `process.cwd()` at SDK-init time. |
37 | `provider` | `BaseComposioProvider` | No | `new OpenAIProvider()` | The provider to use for this Composio instance |
38
39 ## Properties
40
41 The `Composio` class provides access to the following core models:
42
43 | Property | Type | Description |
44 | ------------------- | ---------------------- | ------------------------------------------ |
45 | `tools` | `Tools` | Access to tools functionality |
46 | `toolkits` | `Toolkits` | Access to toolkits functionality |
47 | `triggers` | `Triggers` | Access to triggers functionality |
48 | `authConfigs` | `AuthConfigs` | Access to auth configs functionality |
49 | `connectedAccounts` | `ConnectedAccounts` | Access to connected accounts functionality |
50 | `files` | `Files` | Access to file upload/download functionality|
51 | `provider` | `BaseComposioProvider` | The provider being used |
52
53
54 ## Methods
55
56 ### getClient()
57
58 Returns the internal Composio API client.
59
60 ```typescript
61 const client = composio.getClient();
62 ```
63
64 **Returns:** `ComposioClient`
65
66 **Throws:** Error if the client is not initialized
67
68 ## Examples
69
70 ### Basic Initialization
71
72 ```typescript
73 import { Composio } from '@composio/core';
74
75 const composio = new Composio({
76 apiKey: process.env.COMPOSIO_API_KEY,
77 });
78 ```
79
80 ### Custom Provider
81
82 ```typescript
83 import { Composio } from '@composio/core';
84 import { OpenAIProvider } from '@composio/openai';
85
86 const openaiProvider = new OpenAIProvider();
87 const composio = new Composio({
88 apiKey: process.env.COMPOSIO_API_KEY,
89 provider: openaiProvider,
90 });
91 ```
92
93 ### Disable Tracking
94
95 ```typescript
96 import { Composio } from '@composio/core';
97
98 const composio = new Composio({
99 apiKey: process.env.COMPOSIO_API_KEY,
100 allowTracking: false,
101 });
102 ```
103
104 ### Automatic file handling (opt-in)
105
106 Automatic upload/download of file-marked tool fields is **off** by default. Set `dangerouslyAllowAutoUploadDownloadFiles: true` only if you intend to use that behavior:
107
108 ```typescript
109 import { Composio } from '@composio/core';
110
111 const composio = new Composio({
112 apiKey: process.env.COMPOSIO_API_KEY,
113 dangerouslyAllowAutoUploadDownloadFiles: true,
114 });
115 ```
116
117 #### What the LLM sees vs. what the SDK does
118
119 The flag is a **contract between the SDK and the model**. The schema handed
120 to the LLM always reflects what will actually happen at runtime:
121
122 - **Flag `true`** — `composio.tools.get(...)` rewrites `file_uploadable`
123 inputs down to `{ type: 'string', format: 'path' }`. The model passes a
124 path or URL, the SDK stages it, the backend receives a proper
125 `{ name, mimetype, s3key }` object. Works end-to-end.
126 - **Flag `false`** (or omitted) — the raw backend shape
127 (`{ name, mimetype, s3key }`) is preserved. You are expected to stage
128 files yourself via `composio.files.upload(...)` and inject the returned
129 descriptor into the tool arguments before calling `tools.execute`. Handing
130 this shape directly to an LLM is not recommended — the model cannot
131 produce a valid `s3key`. On first execution of a file-uploadable tool in
132 this mode, the SDK emits a single warning per tool slug nudging you
133 toward either enabling the flag or staging manually.
134
135 Manual staging example (flag off):
136
137 ```typescript
138 const staged = await composio.files.upload({
139 file: '/tmp/report.pdf',
140 toolSlug: 'SOME_FILE_TOOL',
141 toolkitSlug: 'some-toolkit',
142 });
143
144 await composio.tools.execute('SOME_FILE_TOOL', {
145 userId: 'u',
146 arguments: { file: staged }, // { name, mimetype, s3key }
147 });
148 ```
149
150 ### Per-execution `beforeFileUpload` modifier
151
152 Use the **third argument** to `composio.tools.execute` to intercept each file read before upload (in addition to global `sensitiveFileUploadProtection` on the client):
153
154 ```typescript
155 import { Composio } from '@composio/core';
156
157 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! });
158
159 await composio.tools.execute(
160 'SOME_FILE_TOOL',
161 { userId: 'u', arguments: { file: '/tmp/report.pdf' }, dangerouslySkipVersionCheck: true },
162 {
163 beforeFileUpload: async ({ path, source, toolSlug, toolkitSlug }) => {
164 // `source` discriminates the input:
165 // 'path' — a local filesystem path
166 // 'url' — an http(s):// URL
167 // 'file' — a File object; `path` is `file.name` (filename only)
168 if (source !== 'path') return path; // let URLs / File objects through
169 // return path, a different path, or false to abort
170 return path;
171 },
172 }
173 );
174 ```
175
176 See [Auto upload and download](../advanced/auto-upload-download.md#security-sensitive-local-paths) for the security model and error types.
177
178 ### Restricting automatic uploads to specific directories
179
180 When `dangerouslyAllowAutoUploadDownloadFiles: true`, the SDK only reads local
181 files from directories in `fileUploadDirs`. This stacks with (it does NOT
182 replace) the sensitive-path denylist.
183
184 ```typescript
185 import { Composio } from '@composio/core';
186
187 const composio = new Composio({
188 apiKey: process.env.COMPOSIO_API_KEY!,
189 dangerouslyAllowAutoUploadDownloadFiles: true,
190 // User-provided list REPLACES the default `[~/.composio/temp]`.
191 // Include it explicitly if you want staged uploads to keep working.
192 fileUploadDirs: ['/srv/agent/uploads', '~/.composio/temp'],
193 });
194 ```
195
196 A local path is accepted if its symlink-resolved absolute path is inside one
197 of these directories on a path-component boundary. Paths outside the allowlist
198 throw `ComposioFileUploadPathNotAllowedError`. Missing files throw
199 `ComposioFileNotFoundError`. URLs (`http(s)://...`) and `File`/`Blob` objects
200 are not path-checked.
201
202 **Manual upload API (`composio.files.upload(...)`) is _not_ subject to this
203 allowlist** — it bypasses the allowlist check entirely. Use the allowlist to
204 constrain what models/agents can ask the SDK to upload during tool execution.
205
206 #### Blocking local paths entirely
207
208 Pass `false` to allow only URLs and in-memory `File`/`Blob` objects during
209 automatic upload:
210
211 ```typescript
212 const composio = new Composio({
213 apiKey: process.env.COMPOSIO_API_KEY!,
214 dangerouslyAllowAutoUploadDownloadFiles: true,
215 fileUploadDirs: false, // reject every filesystem path for auto-upload
216 });
217 ```
218
219 `fileUploadDirs: []` behaves identically; prefer `false` for readability.
220
221 ### Changing the download directory
222
223 ```typescript
224 import { Composio } from '@composio/core';
225
226 const composio = new Composio({
227 apiKey: process.env.COMPOSIO_API_KEY!,
228 fileDownloadDir: '/var/app/composio-downloads',
229 });
230 ```
231
232 Files returned by tools as `s3url` are streamed into this directory. The
233 default is `~/.composio/files`.