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)
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Musthaq Ahamad committed
Dec 4, 2025 at 16:03 UTC
31521bd1a5094069d2b1f2b22080743a8a756b0e
19 files changed
+73
-54
.changeset/silly-parrots-grab.md
new
+5
@@ -0,0 +1,5 @@
1
+---
2
+'@composio/core': patch
3
+---
4
+
5
+Update typedocs and examples for toolkit versions
.github/workflows/ts.test.yml
+2
@@ -14,6 +14,8 @@ jobs:
14
test:
15
name: Test Typescript SDK
16
runs-on: ubuntu-latest
17
+ permissions:
18
+ pull-requests: write
19
20
steps:
21
- name: Checkout Code
pnpm-lock.yaml
+7
-4
@@ -15,6 +15,9 @@ catalogs:
15
'@composio/client':
16
specifier: 0.1.0-alpha.46
17
version: 0.1.0-alpha.46
18
+ '@modelcontextprotocol/sdk':
19
+ specifier: ^1.22.0
20
+ version: 1.23.0
21
tsup:
22
specifier: ^8.5.0
23
version: 8.5.1
@@ -371,7 +374,7 @@ importers:
374
specifier: ^1.1.0
375
version: 1.30.0(@modelcontextprotocol/sdk@1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13))
376
'@modelcontextprotocol/sdk':
374
- specifier: ^1.18.0
377
+ specifier: 'catalog:'
378
version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
379
dotenv:
380
specifier: ^16.4.1
@@ -508,7 +511,7 @@ importers:
511
specifier: workspace:*
512
version: link:../../packages/providers/vercel
513
'@modelcontextprotocol/sdk':
511
- specifier: ^1.18.0
514
+ specifier: 'catalog:'
515
version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
516
ai:
517
specifier: '>=5.0.102'
@@ -558,7 +561,7 @@ importers:
561
specifier: workspace:*
562
version: link:../../packages/providers/openai-agents
563
'@modelcontextprotocol/sdk':
561
- specifier: ^1.18.0
564
+ specifier: 'catalog:'
565
version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
566
'@openai/agents':
567
specifier: ^0.1.4
@@ -729,7 +732,7 @@ importers:
732
specifier: workspace:*
733
version: link:../../packages/providers/vercel
734
'@modelcontextprotocol/sdk':
732
- specifier: ^1.18.0
735
+ specifier: 'catalog:'
736
version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
737
ai:
738
specifier: '>=5.0.102'
pnpm-workspace.yaml
+2
-1
@@ -16,7 +16,8 @@ catalog:
16
'@cloudflare/vitest-pool-workers': ^0.9.2
17
'@cloudflare/workers-types': ^4.20250917.0
18
'@composio/client': 0.1.0-alpha.46
19
- ai: ^5.0.102
19
+ '@modelcontextprotocol/sdk': ^1.22.0
20
+ ai: 5.0.52
21
openai: ^5.20.3
22
tsup: ^8.5.0
23
tsx: ^4.20.5
python/README.md
+1
-1
@@ -208,7 +208,7 @@ composio = Composio(
208
allow_tracking=True, # Enable/disable telemetry (default: True)
209
file_download_dir="./downloads", # Directory for file downloads
210
provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)
211
- toolkit_versions="latest" # Toolkit versions to use
211
+ toolkit_versions={ "github": "12202025_01" } # Toolkit versions to use
212
)
213
```
214
python/composio/core/types.py
+4
-5
@@ -6,12 +6,11 @@ import typing_extensions as te
6
7
# Tool versioning types
8
ToolkitLatestVersion = te.Literal["latest"]
9
-ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"
9
+ToolkitVersion = t.Union[
10
+ ToolkitLatestVersion, str
11
+] # Can be "latest" or any version string like "20250906_01"
12
ToolkitVersions = t.Dict[str, ToolkitVersion]
11
-ToolkitVersionParam = t.Union[
12
- str, ToolkitVersions, None
13
-] # String can be any global version
14
-
13
+ToolkitVersionParam = t.Union[ToolkitVersions, ToolkitLatestVersion, None]
14
15
__all__ = [
16
"ToolkitLatestVersion",
python/composio/sdk.py
+3
-3
@@ -73,10 +73,10 @@ class Composio(t.Generic[TProvider], WithLogger):
73
:param base_url: The base URL to use for the SDK.
74
:param timeout: The timeout to use for the SDK.
75
:param max_retries: The maximum number of retries to use for the SDK.
76
- :param toolkit_versions: The versions of the toolkits to use. Can be:
76
+ :param toolkit_versions: A dictionary mapping toolkit names to specific versions:
77
+ - A dictionary mapping toolkit names to specific versions
78
- A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits
78
- - A dict mapping toolkit names to specific versions
79
- - None to use 'latest' as default
79
+ - None or omitted to use 'latest' as default
80
"""
81
WithLogger.__init__(self)
82
api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
python/composio/utils/toolkit_version.py
+5
-8
@@ -38,19 +38,16 @@ def get_toolkit_versions(
38
Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
39
40
Priority order:
41
- 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")
41
+ 1. If default_versions is a string, use it as a global version for all toolkits
42
2. User-provided toolkit version mappings (default_versions dict)
43
3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
44
4. Fallback to 'latest' if no versions are configured
45
46
- :param default_versions: Optional default versions configuration (string for global version
47
- or dict mapping toolkit names to versions). String can be any version
48
- like "latest", "20250906_01", etc.
49
- :return: Toolkit versions configuration - either a global version string,
50
- toolkit-specific version mapping, or 'latest'
46
+ :param default_versions: Optional default versions configuration (string for global version or dict mapping toolkit names to versions)
47
+ :return: Toolkit versions configuration - either a string for global version or dict mapping toolkit names to versions
48
"""
52
- # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits
53
- if default_versions and isinstance(default_versions, str):
49
+ # If already set by user as a string, use it as global version for all toolkits
50
+ if isinstance(default_versions, str):
51
return default_versions
52
53
# Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
python/tests/test_core_types.py
+7
-3
@@ -16,9 +16,13 @@ class TestCoreTypes:
16
# Should be a Literal["latest"]
17
assert hasattr(ToolkitLatestVersion, "__origin__")
18
19
- def test_toolkit_version_is_string(self):
20
- """Test ToolkitVersion is string type."""
21
- assert ToolkitVersion is str
19
+ def test_toolkit_version_is_union(self):
20
+ """Test ToolkitVersion is a Union type."""
21
+ # ToolkitVersion should be Union[Literal["latest"], str]
22
+ import typing
23
+
24
+ assert hasattr(ToolkitVersion, "__origin__")
25
+ assert ToolkitVersion.__origin__ is typing.Union
26
27
def test_toolkit_versions_is_dict(self):
28
"""Test ToolkitVersions is dict type."""
python/tests/test_toolkit_version.py
+1
-1
@@ -136,7 +136,7 @@ class TestToolkitVersion:
136
with pytest.MonkeyPatch().context() as m:
137
# Test 1: String global version overrides everything
138
m.setenv("COMPOSIO_TOOLKIT_VERSION_GITHUB", "env_version")
139
- result = get_toolkit_versions("global_version")
139
+ result = get_toolkit_version("github", "global_version")
140
assert result == "global_version"
141
142
# Test 2: User dict overrides env vars
ts/docs/api/tools.md
+1
-1
@@ -63,7 +63,7 @@ const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
63
64
Executes a given tool with the provided parameters manually.
65
66
-> **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**.
66
+> **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**.
67
68
```typescript
69
// Execute with a pinned version (REQUIRED for workflows and manual execution)
ts/docs/api/triggers.md
+1
-1
@@ -280,7 +280,7 @@ const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
280
281
**Behavior:**
282
283
-- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
283
+- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'` if not provided)
284
- To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance
285
- See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
286
ts/docs/getting-started.md
+12
-15
@@ -62,20 +62,7 @@ Example: `12082025_00` represents version 00 released on August 12, 2025.
62
63
#### Configuration Options
64
65
-**Option 1: Global Version for All Toolkits**
66
-
67
-```typescript
68
-const composio = new Composio({
69
- toolkitVersions: 'latest' // Use latest version for all toolkits
70
-});
71
-
72
-// Or pin a specific version globally
73
-const composio = new Composio({
74
- toolkitVersions: '12082025_00' // All toolkits use this version
75
-});
76
-```
77
-
78
-**Option 2: Specific Versions per Toolkit (Recommended for Production)**
65
+**Option 1: Specific Versions per Toolkit (Recommended for Production)**
66
67
```typescript
68
const composio = new Composio({
@@ -87,7 +74,7 @@ const composio = new Composio({
74
});
75
```
76
90
-**Option 3: Using Environment Variables**
77
+**Option 2: Using Environment Variables**
78
79
You can set toolkit versions using environment variables:
80
@@ -107,6 +94,16 @@ const composio = new Composio({
94
});
95
```
96
97
+**Option 3: Latest version for all toolkits**
98
+If omitted, SDK will use `latest` version for all the toolkits
99
+
100
+```typescript
101
+const composio = new Composio({
102
+ apiKey: 'your-api-key',
103
+ // since omitted, this will use `latest` for all toolkits
104
+})
105
+```
106
+
107
#### Version Behavior
108
109
- **Tools & Triggers:** The toolkit version configuration applies to both tools and triggers
ts/examples/google/package.json
+1
-1
@@ -24,7 +24,7 @@
24
"@composio/core": "workspace:*",
25
"@composio/google": "workspace:*",
26
"@google/genai": "^1.1.0",
27
- "@modelcontextprotocol/sdk": "^1.18.0",
27
+ "@modelcontextprotocol/sdk": "catalog:",
28
"dotenv": "^16.4.1"
29
},
30
"devDependencies": {
ts/examples/mcp/package.json
+1
-1
@@ -21,7 +21,7 @@
21
"@ai-sdk/openai": "^2.0.35",
22
"@composio/core": "workspace:*",
23
"@composio/vercel": "workspace:*",
24
- "@modelcontextprotocol/sdk": "^1.18.0",
24
+ "@modelcontextprotocol/sdk": "catalog:",
25
"ai": "catalog:",
26
"dotenv": "^16.4.1"
27
},
ts/examples/openai/package.json
+1
-1
@@ -22,7 +22,7 @@
22
"@composio/core": "workspace:*",
23
"@composio/openai": "workspace:*",
24
"@composio/openai-agents": "workspace:*",
25
- "@modelcontextprotocol/sdk": "^1.18.0",
25
+ "@modelcontextprotocol/sdk": "catalog:",
26
"@openai/agents": "^0.1.4",
27
"dotenv": "^16.4.1",
28
"openai": "^5.16.0",
ts/examples/vercel/package.json
+1
-1
@@ -18,7 +18,7 @@
18
"@ai-sdk/openai": "^2.0.16",
19
"@composio/core": "workspace:*",
20
"@composio/vercel": "workspace:*",
21
- "@modelcontextprotocol/sdk": "^1.18.0",
21
+ "@modelcontextprotocol/sdk": "catalog:",
22
"ai": "catalog:",
23
"dotenv": "^16.5.0",
24
"zod-to-json-schema": "^3.24.6"
ts/packages/core/src/composio.ts
+3
-2
@@ -78,6 +78,7 @@ export type ComposioConfig<
78
disableVersionCheck?: boolean;
79
/**
80
* The versions of the toolkits to use for tool execution and retrieval.
81
+ * Omit to use 'latest' for all toolkits.
82
*
83
* **Version Control:**
84
* When executing tools manually (via `tools.execute()`), if this resolves to "latest",
@@ -89,9 +90,9 @@ export type ComposioConfig<
90
* Defaults to 'latest' if nothing is provided.
91
* You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
92
*
92
- * @example Global version for all toolkits
93
+ * @example Global version for all toolkits, omit to use 'latest'
94
* ```typescript
94
- * const composio = new Composio({ toolkitVersions: 'latest' });
95
+ * const composio = new Composio();
96
* ```
97
*
98
* @example Specific versions for different toolkits (recommended for production)
ts/packages/core/src/types/tool.types.ts
+15
-5
@@ -142,30 +142,40 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
142
*/
143
export type ToolList = Array<Tool>;
144
145
+export const ToolkitLatestVersionSchema = z.literal('latest');
146
/**
147
* latest toolkit version param
148
*/
148
-export type ToolkitLatestVersion = 'latest';
149
+export type ToolkitLatestVersion = z.infer<typeof ToolkitLatestVersionSchema>;
150
+
151
+export const ToolkitVersionSchema = z.union([ToolkitLatestVersionSchema, z.string()]);
152
/**
153
* Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'
154
* @example
155
* 'latest'
156
* '20250902_00'
157
*/
155
-export type ToolkitVersion = ToolkitLatestVersion | string;
158
+export type ToolkitVersion = z.infer<typeof ToolkitVersionSchema>;
159
+
160
+export const ToolkitVersionsSchema = z.record(z.string(), ToolkitVersionSchema);
161
/**
162
* Versioning multiple toolkits
163
* @example
164
* { 'github': 'latest', 'slack': '20250902_00' }
165
*/
166
export type ToolkitVersions = Record<string, ToolkitVersion>;
167
+
168
+export const ToolkitVersionParamSchema = z
169
+ .union([ToolkitVersionsSchema, ToolkitLatestVersionSchema, z.undefined()])
170
+ .describe('The versioning of the toolkits. eg: { "github": "latest", "slack": "20250902_00" }');
171
/**
163
- * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'
172
+ * Versioning a tool based on it's toolkit version
173
* @example
165
- * 'latest'
174
+ * ```json
175
* { 'github': 'latest', 'slack': '20250902_00' }
176
+ * ```
177
*/
168
-export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;
178
+export type ToolkitVersionParam = z.infer<typeof ToolkitVersionParamSchema>;
179
180
export const ToolListParamsSchema = z.object({
181
tools: z.array(z.string()).optional(),