Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Update docs
haxzie8fe6f538105a
diff --git a/fern/pages/src/tool-calling/executing-tools.mdx b/fern/pages/src/tool-calling/executing-tools.mdxindex 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 filediff --git a/fern/pages/src/tool-calling/fetching-tools.mdx b/fern/pages/src/tool-calling/fetching-tools.mdxindex 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 firstComposio determines the importance of a tool based on the usage and relevance of the tool.</Tip>+<CodeGroup>```typescript TypeScript maxLines=60 wordWrapconst 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 toolThis step runs a semantic search on the tool names and descriptions and returns the most relevant tools.<CodeGroup>-```typescript TypeScript maxLines=60 wordWrapconst 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 filediff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.mdindex 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 toolslimit?: never;search?: never;-};+ scopes?: never;+}type ToolkitsOnlyParams = {tools?: never; // Cannot be used with toolkitstoolkits: string[]; // List of toolkit slugs to filter bylimit?: 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 bylimit?: number; // Limit the number of resultssearch: 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 slugs2. Using `toolkits` with optional `important` flag to fetch tools from specific toolkits3. 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 permissionsExamples: