Legacy API: prefer sessionsThis guide covers legacy direct-execution methods, which remain supported for existing integrations. For new integrations, use sessions to manage tool fetching, authentication, and execution. If you use direct execution today, consider migrating to sessions. See Sessions vs direct execution for the tradeoffs.
GMAIL_SEND_EMAIL to actually send it. The tool’s results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.
In Composio, every tool is a single API action—fully described with schema, parameters, and return type. Tools live inside toolkits like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.
To run a specific tool version, pass version directly to composio.tools.execute(). See Pin a version for complete Python and TypeScript examples.
Canceling TypeScript requests
TypeScript SDK methods accept anAbortSignal in their trailing request options. Aborted requests throw ComposioRequestCancelledError, so cancellation can be handled separately from execution failures:
AbortController when application code decides when to cancel. Custom tools receive the same signal as ctx.signal and should pass it to cancellable work.
User Scoping: All tools are scoped to a specific user - that’s why every example includes a
user_id. Learn how to structure User IDs in User scoping. Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see Authentication.Using Chat Completions
Use the Composio SDK with providers like OpenAI, Anthropic, and Google AI. To learn how to set up these providers, see Providers.- Python
- TypeScript
Using Agentic Frameworks
Agentic frameworks automatically handle the tool execution loop. Composio provides support for frameworks like this by making sure the tools are formatted into the correct objects for the agentic framework to execute.- Python
- TypeScript
Direct Tool Execution
If you just want to call a tool without using any framework or LLM provider, you can use theexecute method directly.
Finding a toolkit and tool: browse the Toolkits catalog — each toolkit page lists its tool slugs and current version — or search by task from the CLI:
composio search "send an email". You can also search tools by action keywords from the SDK.Finding tool parameters and types:Platform UI: Auth Configs → Select your toolkit → Tools & Triggers → Select the tool to see its required and optional parametersCLI: For Python and TypeScript projects, run composio generate to generate types. Learn more →Pin a version
Passversion on the tools.execute() call to select a specific tool version. This overrides SDK initialization and environment defaults for that call without changing other executions.
Choose an available version from the GitHub toolkit page or look it up with the SDK. The examples below use 20250909_00. Replace it with the version you have tested, and keep that string in your code or configuration.
- Python
- TypeScript
- API
version satisfies the direct-execution version check. To set a default for all calls to a toolkit, configure SDK initialization or environment variables.
Use the latest version
If an LLM consumes the output and can handle schema changes, you can uselatest. Direct execution requires the explicit opt-in shown below.
- Python
- TypeScript
- API
Proxy Execute
You can proxy requests to any supported toolkit API and let Composio inject the authentication state. This is useful when you need an API endpoint that isn’t available as a predefined tool. Proxy execute requires auth context. Passconnected_account_id / connectedAccountId, or provide custom_connection_data if you’re supplying auth manually.
On projects with 2FA enabled, also pass user_id / userId. Composio checks it against the connected account and may reject a call that omits it.
The endpoint can be a relative path or absolute URL. Relative paths are resolved against the connected account’s base URL. Absolute URLs are only accepted when they use the same scheme and registrable domain as that base URL. Cross-subdomain requests on the same registrable domain still work.
- Python
- TypeScript
- API
Need an API that isn’t supported by any Composio toolkit, or want to extend an existing one? Learn how to create session custom tools.
Automatic File Handling
Automatic file handling is off by default. Enable it withdangerouslyAllowAutoUploadDownloadFiles: true (TypeScript) or dangerously_allow_auto_upload_download_files=True (Python). Once enabled, pass file paths to tools that accept files and get local paths back from tools that return files.
File Upload
Pass local file paths, URLs, or File objects to tools that accept files. The SDK uploads the file to Composio’s storage and converts it to the format the tool expects — you don’t need to construct the file metadata object (s3key, name, mimetype) yourself.
- Python
- TypeScript
- Python
- TypeScript
File Download
When tools return files, Composio downloads them to the local directory and provides the file path in the response:- Python
- TypeScript
_, an over-long name is truncated with its extension kept, and trailing dots and spaces are dropped. A name any of those rules changed also carries a short digest of the original, so two names that clean up the same way stay distinct. A name that can’t be written at all, one containing a NUL byte or with nothing usable left, fails the download instead. An existing file in the download directory is never replaced — the new download gets a number before its extension, so a second report.pdf lands as report-1.pdf. TypeScript names automatic downloads after the tool slug and a timestamp instead, so its names are already unique.
Automatic S3 downloads stop at 100 MiB, even when the server omits or reports an incorrect Content-Length. Python removes partial files for transport and filesystem failures and raises ErrorDownloadingFile; oversized responses raise ResponseTooLargeError. In TypeScript, failed automatic S3 downloads return file_downloaded: false. RemoteFile connection failures and streamed-body failures raise RemoteFileDownloadError.
URL-based file fetches validate the resolved address at each redirect and reject internal, reserved, and transition-network address ranges. Both SDKs follow standard HTTP redirect method and body rules and strip credentials on cross-origin redirects.
Security for local file paths
Automatic upload reads local paths (or uses them infiles.upload) and sends file content to Composio storage. To reduce the chance of accidentally uploading secrets (SSH keys, cloud credentials, .env files, or assistant project folders), the SDK checks local paths against a default denylist of path segments and file-name patterns. HTTP/HTTPS URLs and File objects are not matched like local path strings; only local string paths go through this check.
When sensitiveFileUploadProtection (TypeScript) or sensitive_file_upload_protection (Python) is enabled, each path is matched twice: once as written and once after resolving symlinks. A symlink can hide a denied name in either direction. For example, ~/link -> ~/nested/.aws/creds hides .aws from the path you wrote, while ~/.claude -> /state/claude hides .claude from the resolved target. Dotfile managers such as chezmoi, stow, and yadm can produce the second layout.
Matching both forms blocks these common single-symlink cases. Only the path as written and its fully resolved target are compared, so treat the denylist as a guardrail against accidental uploads, not a security boundary against a determined attacker.
Constructor options (defaults protect sensitive locations):
- Python
- TypeScript
false to abort, or throw). TypeScript passes beforeFileUpload on the third argument to tools.execute. In Python, add @before_file_upload functions to the modifiers list for get / execute (see Before file upload (Python)).
- Python
- TypeScript
ComposioSensitiveFilePathBlockedError / SensitiveFilePathBlockedError when a path is blocked; ComposioFileUploadAbortedError / FileUploadAbortedError when the hook returns false (or equivalent abort).
Automatic file handling (off by default)
Both SDKs ship with automatic file handling off. Opt in withdangerouslyAllowAutoUploadDownloadFiles: true (TypeScript) or dangerously_allow_auto_upload_download_files=True (Python). Even with the flag enabled, local paths must resolve inside an allowlisted directory — see the matrix in the legacy auto-upload removal changelog for the full fileUploadDirs / file_upload_dirs semantics.
When auto-handling is off, handle the staging yourself.
- Python
- TypeScript
The Python SDK does not expose a top-level manual-staging API. Either:
- Enable auto-handling and configure
file_upload_dirsto cover the directories your code reads from:
- Or keep auto-handling off and pass an already-staged
{ "name", "mimetype", "s3key" }dict directly intotools.execute. Pre-stage your files via your own pipeline (or an upstream tool) and inject the descriptor: