Skip to content

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

Update docs

haxzie8fe6f538105a
diff --git a/fern/pages/src/tool-calling/executing-tools.mdx b/fern/pages/src/tool-calling/executing-tools.mdx
index 53777dcb1..269a23173 100644
--- a/fern/pages/src/tool-calling/executing-tools.mdx
+++ b/fern/pages/src/tool-calling/executing-tools.mdx
@@ -231,4 +231,126 @@ response = composio.tools.proxy(
```
</CodeGroup>
-If you're interested in extending toolkits and creating custom tools, see [Custom tools](/docs/custom-tools).
\ No newline at end of file
+If you're interested in extending toolkits and creating custom tools, see [Custom tools](/docs/custom-tools).
+
+## Automatic File Handling
+
+Composio SDK includes automatic file handling for tools that work with files. When enabled (default), the SDK automatically handles file uploads and downloads during tool execution.
+
+### File Upload
+
+When a tool accepts file inputs (marked with `file_uploadable: true`), you can pass local file paths or URLs. Here's an example using Google Drive upload:
+
+<CodeGroup>
+```typescript TypeScript maxLines=60 wordWrap
+import { Composio } from '@composio/core';
+import path from 'path';
+
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY
+});
+
+// Upload a local file to Google Drive
+const result = await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {
+ userId: 'default',
+ arguments: {
+ file_to_upload: path.join(__dirname, 'document.pdf') // Local file path
+ }
+});
+
+console.log(result.data); // Contains Google Drive file details
+```
+
+```python Python maxLines=60 wordWrap
+from composio import Composio
+import os
+
+composio = Composio()
+
+# Upload a local file to Google Drive
+result = composio.tools.execute(
+ "GOOGLEDRIVE_UPLOAD_FILE",
+ user_id="default",
+ arguments={
+ "file_to_upload": os.path.join(os.getcwd(), "document.pdf") # Local file path
+ }
+)
+
+print(result.data) # Contains Google Drive file details
+```
+</CodeGroup>
+
+The SDK automatically:
+1. Reads the file content
+2. Uploads it to secure storage
+3. Passes the file metadata to the tool
+
+### File Download
+
+When a tool returns file outputs, the SDK automatically:
+1. Downloads the file to a local temporary directory
+2. Provides the local file path in the response
+
+<CodeGroup>
+```typescript TypeScript maxLines=60 wordWrap
+// Download a file from Google Drive
+const result = await composio.tools.execute('GOOGLEDRIVE_DOWNLOAD_FILE', {
+ userId: 'default',
+ arguments: {
+ file_id: 'your_file_id'
+ }
+});
+
+// Result includes local file path
+console.log(result.data.file.uri); // "/path/to/downloaded/file.pdf"
+```
+
+```python Python maxLines=60 wordWrap
+# Download a file from Google Drive
+result = composio.tools.execute(
+ "GOOGLEDRIVE_DOWNLOAD_FILE",
+ user_id="default",
+ arguments={
+ "file_id": "your_file_id"
+ }
+)
+
+# Result includes local file path
+print(result.data["file"]["uri"]) # "/path/to/downloaded/file.pdf"
+```
+</CodeGroup>
+
+### Disabling Auto File Handling
+
+You can disable automatic file handling when initializing the SDK:
+
+<CodeGroup>
+```typescript TypeScript maxLines=60 wordWrap
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ autoUploadDownloadFiles: false
+});
+
+// Now you need to handle files manually using composio.files API
+const fileData = await composio.files.upload({
+ filePath: path.join(__dirname, 'document.pdf'),
+ toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE',
+ toolkitSlug: 'googledrive'
+});
+```
+
+```python Python maxLines=60 wordWrap
+composio = Composio(
+ auto_upload_download_files=False
+)
+
+# Now you need to handle files manually using composio.files API
+file_data = composio.files.upload(
+ file_path=os.path.join(os.getcwd(), "document.pdf"),
+ tool_slug="GOOGLEDRIVE_UPLOAD_FILE",
+ toolkit_slug="googledrive"
+)
+```
+</CodeGroup>
+
+For more details on file handling, see [Auto Upload and Download Files](/docs/advanced/auto-upload-download).
\ No newline at end of file
diff --git a/fern/pages/src/tool-calling/fetching-tools.mdx b/fern/pages/src/tool-calling/fetching-tools.mdx
index 2ea95becf..b4502e609 100644
--- a/fern/pages/src/tool-calling/fetching-tools.mdx
+++ b/fern/pages/src/tool-calling/fetching-tools.mdx
@@ -22,6 +22,7 @@ When you fetch tools from a toolkit, the most important tools are returned first
Composio determines the importance of a tool based on the usage and relevance of the tool.
</Tip>
+
<CodeGroup>
```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(
@@ -57,7 +58,38 @@ const tools = await composio.tools.get(userId, {
tools = composio.tools.get(
user_id,
toolkits=["GITHUB"],
- limit=5, # Returns the top 5 important tools from the toolkit
+ limit=5, // Returns the top 5 important tools from the toolkit
+)
+```
+</CodeGroup>
+
+**Filtering by scopes**
+
+When working with OAuth-based toolkits, you can filter tools based on their required scopes. This is useful when you want to:
+- Get tools that match specific permission levels
+- Ensure tools align with available user permissions
+- Filter tools based on their required OAuth scopes
+
+<Tip title="Single Toolkit Requirement" icon="warning">
+Scope filtering can only be used with a single toolkit at a time.
+</Tip>
+
+<CodeGroup>
+```typescript TypeScript maxLines=60 wordWrap
+// Get GitHub tools that require specific scopes
+const tools = await composio.tools.get(userId, {
+ toolkits: ["GITHUB"],
+ scopes: ["repo"], // Only get tools requiring these scopes
+ limit: 10
+});
+```
+```python Python maxLines=60 wordWrap
+# Get GitHub tools that require specific scopes
+tools = composio.tools.get(
+ user_id,
+ toolkits=["GITHUB"],
+ scopes=["repo",], // Only get tools requiring these scopes
+ limit=10
)
```
</CodeGroup>
@@ -118,11 +150,17 @@ You may also filter tools by searching for them. This is a good way to find tool
This step runs a semantic search on the tool names and descriptions and returns the most relevant tools.
<CodeGroup>
-
```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(userId, {
search: "hubspot organize contacts",
});
+
+// Search within a specific toolkit
+const tools = await composio.tools.get(userId, {
+ search: "repository issues",
+ toolkits: ["GITHUB"], // Optional: limit search to specific toolkit
+ limit: 5 // Optional: limit number of results
+});
```
```python Python maxLines=60 wordWrap
@@ -130,5 +168,39 @@ tools = composio.tools.get(
user_id,
search="hubspot organize contacts",
)
+
+# Search within a specific toolkit
+tools = composio.tools.get(
+ user_id,
+ search="repository issues",
+ toolkits=["GITHUB"], // Optional: limit search to specific toolkit
+ limit=5 // Optional: limit number of results
+)
```
-</CodeGroup>
\ No newline at end of file
+</CodeGroup>
+
+## Filter Combinations
+
+When fetching tools, you must use one of these filter combinations:
+
+1. **Tools Only**: Fetch specific tools by their slugs
+ ```typescript
+ { tools: ["TOOL_1", "TOOL_2"] }
+ ```
+
+2. **Toolkits Only**: Fetch tools from specific toolkits
+ ```typescript
+ { toolkits: ["TOOLKIT_1", "TOOLKIT_2"], limit?: number }
+ ```
+
+3. **Single Toolkit with Scopes**: Fetch tools requiring specific OAuth scopes
+ ```typescript
+ { toolkits: ["GITHUB"], scopes: ["read:repo"], limit?: number }
+ ```
+
+4. **Search**: Search across all tools or within specific toolkits
+ ```typescript
+ { search: "query", toolkits?: string[], limit?: number }
+ ```
+
+These combinations are mutually exclusive - you can't mix `tools` with `search` or use `scopes` with multiple toolkits.
\ No newline at end of file
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index 6086c5a63..eee673e48 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -178,13 +178,15 @@ type ToolsOnlyParams = {
toolkits?: never; // Cannot be used with tools
limit?: never;
search?: never;
-};
+ scopes?: never;
+}
type ToolkitsOnlyParams = {
tools?: never; // Cannot be used with toolkits
toolkits: string[]; // List of toolkit slugs to filter by
limit?: number; // Limit the number of results
- search?: never; // Cannot be used with important flag,
+ search?: never; // Cannot be used with important flag
+ scopes?: string[]; // Optional list of required OAuth scopes
};
type ToolkitSearchOnlyParams = {
@@ -192,6 +194,7 @@ type ToolkitSearchOnlyParams = {
toolkits?: string[]; // Optional list of toolkit slugs to filter by
limit?: number; // Limit the number of results
search: string; // Search term
+ scopes?: string[]; // Optional list of required OAuth scopes
};
type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitSearchOnlyParams;
@@ -202,6 +205,29 @@ Note: The parameters are organized into three mutually exclusive combinations:
1. Using `tools` array to fetch specific tools by their slugs
2. Using `toolkits` with optional `important` flag to fetch tools from specific toolkits
3. Using `search` with optional `toolkits` to search for tools by name/description
+4. Using `scopes` can only be done with a single `toolkits` slug
+
+You can also filter tools by their scopes:
+
+```typescript
+// Get tools with specific scopes
+const scopedTools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ scopes: ['read:repo', 'write:repo'], // Only get tools requiring these scopes
+});
+
+// Search tools with specific scopes
+const searchedScopedTools = await composio.tools.get('default', {
+ search: 'repository',
+ scopes: ['read:repo'], // Only get tools requiring read:repo scope
+ limit: 10,
+});
+```
+
+The `scopes` parameter allows you to:
+- Filter tools based on their required OAuth scopes
+- Get tools that match specific permission levels
+- Ensure tools align with available user permissions
Examples: