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.

Fix typedocs and examples for toolkit version (#2212)

Musthaq Ahamad31521bd1a509
diff --git a/.changeset/silly-parrots-grab.md b/.changeset/silly-parrots-grab.md
new file mode 100644
index 000000000..7c561d501
--- /dev/null
+++ b/.changeset/silly-parrots-grab.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Update typedocs and examples for toolkit versions
diff --git a/.github/workflows/ts.test.yml b/.github/workflows/ts.test.yml
index 7f87e03ef..e74ba3664 100644
--- a/.github/workflows/ts.test.yml
+++ b/.github/workflows/ts.test.yml
@@ -14,6 +14,8 @@ jobs:
test:
name: Test Typescript SDK
runs-on: ubuntu-latest
+ permissions:
+ pull-requests: write
steps:
- name: Checkout Code
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4f4359a53..5e448f2b4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -15,6 +15,9 @@ catalogs:
'@composio/client':
specifier: 0.1.0-alpha.46
version: 0.1.0-alpha.46
+ '@modelcontextprotocol/sdk':
+ specifier: ^1.22.0
+ version: 1.23.0
tsup:
specifier: ^8.5.0
version: 8.5.1
@@ -371,7 +374,7 @@ importers:
specifier: ^1.1.0
version: 1.30.0(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))
'@modelcontextprotocol/sdk':
- specifier: ^1.18.0
+ specifier: 'catalog:'
version: 1.23.0(@cfworker/[email protected])([email protected])
dotenv:
specifier: ^16.4.1
@@ -508,7 +511,7 @@ importers:
specifier: workspace:*
version: link:../../packages/providers/vercel
'@modelcontextprotocol/sdk':
- specifier: ^1.18.0
+ specifier: 'catalog:'
version: 1.23.0(@cfworker/[email protected])([email protected])
ai:
specifier: '>=5.0.102'
@@ -558,7 +561,7 @@ importers:
specifier: workspace:*
version: link:../../packages/providers/openai-agents
'@modelcontextprotocol/sdk':
- specifier: ^1.18.0
+ specifier: 'catalog:'
version: 1.23.0(@cfworker/[email protected])([email protected])
'@openai/agents':
specifier: ^0.1.4
@@ -729,7 +732,7 @@ importers:
specifier: workspace:*
version: link:../../packages/providers/vercel
'@modelcontextprotocol/sdk':
- specifier: ^1.18.0
+ specifier: 'catalog:'
version: 1.23.0(@cfworker/[email protected])([email protected])
ai:
specifier: '>=5.0.102'
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index f0cfb99b4..eb3ad20c3 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -16,7 +16,8 @@ catalog:
'@cloudflare/vitest-pool-workers': ^0.9.2
'@cloudflare/workers-types': ^4.20250917.0
'@composio/client': 0.1.0-alpha.46
- ai: ^5.0.102
+ '@modelcontextprotocol/sdk': ^1.22.0
+ ai: 5.0.52
openai: ^5.20.3
tsup: ^8.5.0
tsx: ^4.20.5
diff --git a/python/README.md b/python/README.md
index 0ea819db0..7c83f7082 100644
--- a/python/README.md
+++ b/python/README.md
@@ -208,7 +208,7 @@ composio = Composio(
allow_tracking=True, # Enable/disable telemetry (default: True)
file_download_dir="./downloads", # Directory for file downloads
provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)
- toolkit_versions="latest" # Toolkit versions to use
+ toolkit_versions={ "github": "12202025_01" } # Toolkit versions to use
)
```
diff --git a/python/composio/core/types.py b/python/composio/core/types.py
index 20d94ef16..cfc4ced0b 100644
--- a/python/composio/core/types.py
+++ b/python/composio/core/types.py
@@ -6,12 +6,11 @@ import typing_extensions as te
# Tool versioning types
ToolkitLatestVersion = te.Literal["latest"]
-ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"
+ToolkitVersion = t.Union[
+ ToolkitLatestVersion, str
+] # Can be "latest" or any version string like "20250906_01"
ToolkitVersions = t.Dict[str, ToolkitVersion]
-ToolkitVersionParam = t.Union[
- str, ToolkitVersions, None
-] # String can be any global version
-
+ToolkitVersionParam = t.Union[ToolkitVersions, ToolkitLatestVersion, None]
__all__ = [
"ToolkitLatestVersion",
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index 47b7f2f9e..d714ae565 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -73,10 +73,10 @@ class Composio(t.Generic[TProvider], WithLogger):
:param base_url: The base URL to use for the SDK.
:param timeout: The timeout to use for the SDK.
:param max_retries: The maximum number of retries to use for the SDK.
- :param toolkit_versions: The versions of the toolkits to use. Can be:
+ :param toolkit_versions: A dictionary mapping toolkit names to specific versions:
+ - A dictionary mapping toolkit names to specific versions
- A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits
- - A dict mapping toolkit names to specific versions
- - None to use 'latest' as default
+ - None or omitted to use 'latest' as default
"""
WithLogger.__init__(self)
api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
diff --git a/python/composio/utils/toolkit_version.py b/python/composio/utils/toolkit_version.py
index 06e92f604..1c96bdb5f 100644
--- a/python/composio/utils/toolkit_version.py
+++ b/python/composio/utils/toolkit_version.py
@@ -38,19 +38,16 @@ def get_toolkit_versions(
Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
Priority order:
- 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")
+ 1. If default_versions is a string, use it as a global version for all toolkits
2. User-provided toolkit version mappings (default_versions dict)
3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
4. Fallback to 'latest' if no versions are configured
- :param default_versions: Optional default versions configuration (string for global version
- or dict mapping toolkit names to versions). String can be any version
- like "latest", "20250906_01", etc.
- :return: Toolkit versions configuration - either a global version string,
- toolkit-specific version mapping, or 'latest'
+ :param default_versions: Optional default versions configuration (string for global version or dict mapping toolkit names to versions)
+ :return: Toolkit versions configuration - either a string for global version or dict mapping toolkit names to versions
"""
- # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits
- if default_versions and isinstance(default_versions, str):
+ # If already set by user as a string, use it as global version for all toolkits
+ if isinstance(default_versions, str):
return default_versions
# Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
diff --git a/python/tests/test_core_types.py b/python/tests/test_core_types.py
index 0827d167c..7e1e37c85 100644
--- a/python/tests/test_core_types.py
+++ b/python/tests/test_core_types.py
@@ -16,9 +16,13 @@ class TestCoreTypes:
# Should be a Literal["latest"]
assert hasattr(ToolkitLatestVersion, "__origin__")
- def test_toolkit_version_is_string(self):
- """Test ToolkitVersion is string type."""
- assert ToolkitVersion is str
+ def test_toolkit_version_is_union(self):
+ """Test ToolkitVersion is a Union type."""
+ # ToolkitVersion should be Union[Literal["latest"], str]
+ import typing
+
+ assert hasattr(ToolkitVersion, "__origin__")
+ assert ToolkitVersion.__origin__ is typing.Union
def test_toolkit_versions_is_dict(self):
"""Test ToolkitVersions is dict type."""
diff --git a/python/tests/test_toolkit_version.py b/python/tests/test_toolkit_version.py
index 2b19f89ba..30b76e1eb 100644
--- a/python/tests/test_toolkit_version.py
+++ b/python/tests/test_toolkit_version.py
@@ -136,7 +136,7 @@ class TestToolkitVersion:
with pytest.MonkeyPatch().context() as m:
# Test 1: String global version overrides everything
m.setenv("COMPOSIO_TOOLKIT_VERSION_GITHUB", "env_version")
- result = get_toolkit_versions("global_version")
+ result = get_toolkit_version("github", "global_version")
assert result == "global_version"
# Test 2: User dict overrides env vars
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index 88fcc5c13..8b8de1e37 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -63,7 +63,7 @@ const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
Executes a given tool with the provided parameters manually.
-> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if `'latest'` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
+> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if toolkitVersion is not provided or `latest` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
```typescript
// Execute with a pinned version (REQUIRED for workflows and manual execution)
diff --git a/ts/docs/api/triggers.md b/ts/docs/api/triggers.md
index c6f68fb0e..f4bee2a06 100644
--- a/ts/docs/api/triggers.md
+++ b/ts/docs/api/triggers.md
@@ -280,7 +280,7 @@ const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
**Behavior:**
-- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
+- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'` if not provided)
- To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance
- See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
diff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.md
index 4448c446f..e85ee7d7e 100644
--- a/ts/docs/getting-started.md
+++ b/ts/docs/getting-started.md
@@ -62,20 +62,7 @@ Example: `12082025_00` represents version 00 released on August 12, 2025.
#### Configuration Options
-**Option 1: Global Version for All Toolkits**
-
-```typescript
-const composio = new Composio({
- toolkitVersions: 'latest' // Use latest version for all toolkits
-});
-
-// Or pin a specific version globally
-const composio = new Composio({
- toolkitVersions: '12082025_00' // All toolkits use this version
-});
-```
-
-**Option 2: Specific Versions per Toolkit (Recommended for Production)**
+**Option 1: Specific Versions per Toolkit (Recommended for Production)**
```typescript
const composio = new Composio({
@@ -87,7 +74,7 @@ const composio = new Composio({
});
```
-**Option 3: Using Environment Variables**
+**Option 2: Using Environment Variables**
You can set toolkit versions using environment variables:
@@ -107,6 +94,16 @@ const composio = new Composio({
});
```
+**Option 3: Latest version for all toolkits**
+If omitted, SDK will use `latest` version for all the toolkits
+
+```typescript
+const composio = new Composio({
+ apiKey: 'your-api-key',
+ // since omitted, this will use `latest` for all toolkits
+})
+```
+
#### Version Behavior
- **Tools & Triggers:** The toolkit version configuration applies to both tools and triggers
diff --git a/ts/examples/google/package.json b/ts/examples/google/package.json
index 07b7e745b..b73974f86 100644
--- a/ts/examples/google/package.json
+++ b/ts/examples/google/package.json
@@ -24,7 +24,7 @@
"@composio/core": "workspace:*",
"@composio/google": "workspace:*",
"@google/genai": "^1.1.0",
- "@modelcontextprotocol/sdk": "^1.18.0",
+ "@modelcontextprotocol/sdk": "catalog:",
"dotenv": "^16.4.1"
},
"devDependencies": {
diff --git a/ts/examples/mcp/package.json b/ts/examples/mcp/package.json
index c791a392f..ad1e8682a 100644
--- a/ts/examples/mcp/package.json
+++ b/ts/examples/mcp/package.json
@@ -21,7 +21,7 @@
"@ai-sdk/openai": "^2.0.35",
"@composio/core": "workspace:*",
"@composio/vercel": "workspace:*",
- "@modelcontextprotocol/sdk": "^1.18.0",
+ "@modelcontextprotocol/sdk": "catalog:",
"ai": "catalog:",
"dotenv": "^16.4.1"
},
diff --git a/ts/examples/openai/package.json b/ts/examples/openai/package.json
index 1da3456d7..cca6c5155 100644
--- a/ts/examples/openai/package.json
+++ b/ts/examples/openai/package.json
@@ -22,7 +22,7 @@
"@composio/core": "workspace:*",
"@composio/openai": "workspace:*",
"@composio/openai-agents": "workspace:*",
- "@modelcontextprotocol/sdk": "^1.18.0",
+ "@modelcontextprotocol/sdk": "catalog:",
"@openai/agents": "^0.1.4",
"dotenv": "^16.4.1",
"openai": "^5.16.0",
diff --git a/ts/examples/vercel/package.json b/ts/examples/vercel/package.json
index c634b13f2..786d56c53 100644
--- a/ts/examples/vercel/package.json
+++ b/ts/examples/vercel/package.json
@@ -18,7 +18,7 @@
"@ai-sdk/openai": "^2.0.16",
"@composio/core": "workspace:*",
"@composio/vercel": "workspace:*",
- "@modelcontextprotocol/sdk": "^1.18.0",
+ "@modelcontextprotocol/sdk": "catalog:",
"ai": "catalog:",
"dotenv": "^16.5.0",
"zod-to-json-schema": "^3.24.6"
diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.ts
index 155891d77..690682bcd 100644
--- a/ts/packages/core/src/composio.ts
+++ b/ts/packages/core/src/composio.ts
@@ -78,6 +78,7 @@ export type ComposioConfig<
disableVersionCheck?: boolean;
/**
* The versions of the toolkits to use for tool execution and retrieval.
+ * Omit to use 'latest' for all toolkits.
*
* **Version Control:**
* When executing tools manually (via `tools.execute()`), if this resolves to "latest",
@@ -89,9 +90,9 @@ export type ComposioConfig<
* Defaults to 'latest' if nothing is provided.
* You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
*
- * @example Global version for all toolkits
+ * @example Global version for all toolkits, omit to use 'latest'
* ```typescript
- * const composio = new Composio({ toolkitVersions: 'latest' });
+ * const composio = new Composio();
* ```
*
* @example Specific versions for different toolkits (recommended for production)
diff --git a/ts/packages/core/src/types/tool.types.ts b/ts/packages/core/src/types/tool.types.ts
index b6d17c3bd..8504535ae 100644
--- a/ts/packages/core/src/types/tool.types.ts
+++ b/ts/packages/core/src/types/tool.types.ts
@@ -142,30 +142,40 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
*/
export type ToolList = Array<Tool>;
+export const ToolkitLatestVersionSchema = z.literal('latest');
/**
* latest toolkit version param
*/
-export type ToolkitLatestVersion = 'latest';
+export type ToolkitLatestVersion = z.infer<typeof ToolkitLatestVersionSchema>;
+
+export const ToolkitVersionSchema = z.union([ToolkitLatestVersionSchema, z.string()]);
/**
* Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'
* @example
* 'latest'
* '20250902_00'
*/
-export type ToolkitVersion = ToolkitLatestVersion | string;
+export type ToolkitVersion = z.infer<typeof ToolkitVersionSchema>;
+
+export const ToolkitVersionsSchema = z.record(z.string(), ToolkitVersionSchema);
/**
* Versioning multiple toolkits
* @example
* { 'github': 'latest', 'slack': '20250902_00' }
*/
export type ToolkitVersions = Record<string, ToolkitVersion>;
+
+export const ToolkitVersionParamSchema = z
+ .union([ToolkitVersionsSchema, ToolkitLatestVersionSchema, z.undefined()])
+ .describe('The versioning of the toolkits. eg: { "github": "latest", "slack": "20250902_00" }');
/**
- * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'
+ * Versioning a tool based on it's toolkit version
* @example
- * 'latest'
+ * ```json
* { 'github': 'latest', 'slack': '20250902_00' }
+ * ```
*/
-export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;
+export type ToolkitVersionParam = z.infer<typeof ToolkitVersionParamSchema>;
export const ToolListParamsSchema = z.object({
tools: z.array(z.string()).optional(),