This guide covers migrating from the legacy SDK (v1) —
composio-core on PyPI and npm — to the current SDK (v3): composio on PyPI, @composio/core on npm. Provider packages such as composio-openai kept their names across the rewrite: current releases work with v3, v1-era releases don’t. The recommended way to use Composio is now through sessions — see Migrating from Direct Tools to Sessions or Configuring Sessions if you’re starting fresh.What’s new?
A lot of the changes are on the infra side, but from the SDK point of view, here is what you can expect:- Faster and more reliable tool execution
- A simpler but more opinionated SDK
- Much more intuitive and consistent naming conventions
- A vastly improved TypeScript SDK that is meaningfully more type-safe and has full feature parity with the Python SDK
State of the new SDK and what is happening with the old SDKs?
Currently, the new SDKs are in a preview release. These new SDKs come almost fully formed, we do not expect many breaking changes to them but are releasing them in a preview state to get feedback and make necessary changes before locking them in. As we lock the new SDKs in place, we will deprecate support for the old SDKs. They will continue to work for the foreseeable future but are no longer actively maintained. We will continue to push security updates and fix any critical bugs but will not support any new functionality in them. We urge you to upgrade to the new SDKs as soon as possible.Nomenclature
We have updated several key terms in the SDK and API to improve clarity and consistency. The following table summarizes these changes:Switch to nano IDs from UUIDs
We have transitioned from UUIDs to nano IDs throughout the platform for the following reasons:- Improved readability: UUIDs are lengthy and difficult to read
- Better usability: Easier to copy with a single double-click
- Better organization: Nano IDs allow us to distinguish between different resource types through prefixes
Nano IDs are short, unique, and prefixed to indicate the resource type.
SDK Changes
Upgrade to the latest SDK version using the appropriate package manager:- Python
- TypeScript
UserID scoping
The concept ofentity_id has been expanded and renamed to user_id.
All operations are now scoped to a userID, including:
- Fetching tools
- Initiating connections
- Executing tools
- Managing triggers
Replacing ToolSets with Providers
We have deprecated “toolsets” in favor of “providers”. This change allows Composio to provide deeper standardization for tool implementation across different frameworks. Previously, you needed to import and use a framework-specificComposioToolSet class:
- Python (previous)
- TypeScript (previous)
- Python (current)
- TypeScript (current)
- API
Fetching and filtering tools
Previously, you could filter tools by:- Apps
- Action names (tool names)
- Tags
important flag to retrieve the most important tools:
- Python (previous)
- TypeScript (previous)
- Toolkits
- Tool slugs
- Limit parameter
- Search query
important flag has been removed. Instead, tools are returned in order of importance by default:
Since
user_id is now explicitly required, the check_connected_accounts flag is no longer necessary.- Python (current)
- TypeScript (current)
- API
Fetching raw tool data
To examine the raw schema definition of a tool for understanding input/output parameters or building custom logic around tool definitions, use the following methods:- Python (current)
- TypeScript (current)
- API
Executing tools
Tool execution remains largely unchanged, withuser_id now explicitly required.
For agentic frameworks, the tool object returned from tools.get is now the respective framework’s native tool object. Tool call execution is handled by the agentic framework itself.
For non-agentic frameworks, Composio provides a helper function to execute tool calls.
- Python v3
- TypeScript v3
Tool Modifiers (formerly Tool Processors)
Tool processors have been renamed to tool modifiers and now provide an improved developer experience. The implementation is now available in TypeScript too! (previously Python-only).Python (previous)
The modifiers now leverage language-specific features to provide a more natural developer experience.
While tool processors could previously be applied during SDK initialization, tool fetching, and tool execution, we have restructured them as follows:
- Chat Completion providers: Modifiers are specified and applied during tool execution
- Agentic frameworks: Modifiers are specified and applied during tool fetching
Schema Modifiers
The following example demonstrates schema modifier usage, applicable across all providers:- Python (current)
- TypeScript (current)
Before Modifiers
The following example shows creating and using a before modifier for a Chat Completion provider. For agentic frameworks, view the complete before modifier documentation:- Python (current)
- TypeScript (current)
After Modifiers
The following example shows creating and using an after modifier for a Chat Completion provider. For agentic frameworks, view the complete after modifier documentation:- Python (current)
- TypeScript (current)
Custom Tools
Custom tools are now session-scoped. Define local tools with the experimental custom-tools API and attach them when creating or reusing a session.- Python
- TypeScript
Auth configs (formerly integrations)
Integrations are now called auth configs. While the terminology has changed, the underlying concept remains the same. Auth configs store the configuration required for authentication with a given toolkit, including OAuth developer credentials, configurable base URLs, and scopes. Auth configs now use nano IDs instead of UUIDs:
We recommend storing auth config nano IDs in your database for connecting users to the appropriate auth configuration.
For most use cases, you will create auth configs through the dashboard, and this process remains unchanged. Read more about creating auth configs and customizing auth configs.
Creating auth configs programmatically in the previous SDK:
- Python (previous)
- TypeScript (previous)
- Python (current)
- TypeScript (current)
- API
The callback URL for creating custom OAuth configs is now
https://backend.composio.dev/api/v3/toolkits/auth/callback. The previous URL was https://backend.composio.dev/api/v1/auth-apps/add.Connected accounts / User IDs
The primary change in connected accounts and user IDs is that user IDs are now a more prominent concept compared to entities in previous versions. We have simplified the process of connecting a user to a toolkit. Instead of multiple methods and parameters for initiating a connection, both the SDK and API now require only auser_id and auth_config_id to initiate a connection.
This approach is more explicit and works well with the ability for developers to have multiple auth configs for a given toolkit.
Connected accounts now use nano IDs instead of UUIDs:
Previously, you might have initiated a connection like this:
- Python (previous)
- TypeScript (previous)
- Python (current)
- TypeScript (current)
- API
Triggers
Composio continues to support listening to application events using triggers through WebSockets and webhooks.Creating triggers
The process for creating triggers and specifying their configuration has been redesigned for improved clarity and intuitiveness. Some triggers require configuration, such as repository names for GitHub triggers or channel names for Slack triggers. The process usually follows the pattern of fetching the trigger type and then creating the trigger with the appropriate configuration.- Python (current)
- TypeScript (current)
- API
Enabling/Disabling triggers
You can enable or disable triggers through either the SDK or the dashboard. The dashboard process remains unchanged. Managing triggers with the SDK:- Python
- TypeScript
- API
- Python
- TypeScript
- API
Listening to triggers
We recommend listening to triggers through webhooks. The following are example routes for Next.js and FastAPI. For development, you can also listen to triggers through the SDK.- FastAPI
- Next.js
app/route.py
Coming Soon
Local tools
Previously, the Python SDK included local tools. These were tools defined within the SDK and consisted of local shell and code-related tools such as “clipboard”, “sqltool”, and “shelltool”. This feature is currently in development for both Python and TypeScript SDKs, with newly created tools built for improved agent accuracy. This feature is currently in development for both Python and TypeScript SDKs.API Endpoints
The following table lists important API endpoints that have changed. You can use this reference to quickly find the new v3 API endpoint for migration:This list is not exhaustive. Please refer to the API Reference for the complete list of endpoints.