@devries-cameron20 / composio Mirror · read-only / commits / 3ad7f40a4
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 19:30 UTC

Versioning docs

Sushmithamallesh committed Oct 28, 2025 at 15:53 UTC 3ad7f40a4059b65671c2fc4de38a029de24bc63a
15 files changed +411 -11
fern/docs.yml
+15 -3
@@ -135,6 +135,9 @@ navigation:
135 - page: Custom tools
136 path: pages/dist/tool-calling/custom-tools.mdx
137 slug: custom-tools
138 + - page: Toolkit Versioning
139 + path: pages/dist/tool-calling/toolkit-versioning.mdx
140 + slug: toolkit-versioning
141 - section: Authentication
142 icon: lock
143 skip-slug: true
@@ -188,9 +191,18 @@ navigation:
191 - page: Debugging Info
192 path: pages/dist/debugging-info.mdx
193 slug: resources/debugging-info
191 - - page: Migration Guide
192 - path: pages/dist/migration-guide.mdx
193 - slug: migration
194 + - section: Migration Guides
195 + slug: migration-guide
196 + contents:
197 + - page: Overview
198 + path: pages/dist/migration-guide/index.mdx
199 + slug: overview
200 + - page: New SDK Migration
201 + path: pages/dist/migration-guide/new-sdk.mdx
202 + slug: new-sdk
203 + - page: Toolkit Versioning Migration
204 + path: pages/dist/migration-guide/toolkit-versioning.mdx
205 + slug: toolkit-versioning
206 - section: Troubleshooting
207 slug: troubleshooting
208 contents:
fern/pages/src/migration-guide/index.mdx new
+25
@@ -0,0 +1,25 @@
1 +---
2 +title: Migration guides
3 +subtitle: Guides for migrating to newer versions of Composio
4 +image: "https://og.composio.dev/api/og?title=Migration%20guides"
5 +keywords: "migration, upgrade, sdk, versioning"
6 +hide-nav-links: false
7 +---
8 +
9 +Find the appropriate migration guide for your use case:
10 +
11 +## Available migration guides
12 +
13 +<AccordionGroup>
14 + <Accordion title="New SDK migration">
15 + Migrate from the old Composio SDK to the new next-generation SDK, including breaking changes, new features, and updated APIs.
16 +
17 + [View SDK migration guide →](/resources/migration-guide/new-sdk)
18 + </Accordion>
19 +
20 + <Accordion title="Toolkit versioning migration">
21 + Migrate to the new toolkit versioning system introduced on October 22, 2025.
22 +
23 + [View versioning migration guide →](/resources/migration-guide/toolkit-versioning)
24 + </Accordion>
25 +</AccordionGroup>
\ No newline at end of file
fern/pages/src/migration-guide/new-sdk.mdx renamed
+4 -4
@@ -1,9 +1,9 @@
1 ---
2 -title: Our next generation SDKs
2 +title: New SDK migration
3 subtitle: Learn more about Composio's next generation SDKs and how to migrate
4 -image: "https://og.composio.dev/api/og?title=Our%20next%20generation%20SDKs" # image for socials
5 -keywords: ''
6 -hide-nav-links: true
4 +image: "https://og.composio.dev/api/og?title=New%20SDK%20migration"
5 +keywords: 'sdk, migration, next generation, upgrade'
6 +hide-nav-links: false
7 ---
8
9 In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
fern/pages/src/migration-guide/toolkit-versioning.mdx new
+134
@@ -0,0 +1,134 @@
1 +---
2 +title: Toolkit versioning migration
3 +subtitle: Migrate to the new toolkit versioning system
4 +image: "https://og.composio.dev/api/og?title=Toolkit%20versioning%20migration"
5 +keywords: "toolkit versioning, migration, breaking changes"
6 +hide-nav-links: false
7 +---
8 +
9 +Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.
10 +
11 +## Breaking change
12 +
13 +Manual tool execution now requires explicit version specification. The `tools.execute()` method will fail without a version.
14 +
15 +### Before (will fail)
16 +
17 +<CodeGroup>
18 +```python Python
19 +# Raises ToolVersionRequiredError
20 +result = composio.tools.execute(
21 + "GITHUB_CREATE_ISSUE",
22 + {"user_id": "user-123", "arguments": {...}}
23 +)
24 +```
25 +
26 +```typescript TypeScript
27 +// Throws ComposioToolVersionRequiredError
28 +const result = await composio.tools.execute({
29 + toolSlug: "GITHUB_CREATE_ISSUE",
30 + userId: "user-123",
31 + arguments: {...}
32 +});
33 +```
34 +</CodeGroup>
35 +
36 +### After (required)
37 +
38 +Choose one of three migration strategies:
39 +
40 +#### Option 1: Configure version at SDK level
41 +
42 +<CodeGroup>
43 +<SnippetCode
44 + src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
45 + title="Python"
46 +/>
47 +<SnippetCode
48 + src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
49 + title="TypeScript"
50 +/>
51 +</CodeGroup>
52 +
53 +#### Option 2: Pass version with each execution
54 +
55 +<CodeGroup>
56 +<SnippetCode
57 + src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
58 + startLine={5}
59 + endLine={16}
60 + title="Python"
61 +/>
62 +<SnippetCode
63 + src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
64 + startLine={5}
65 + endLine={14}
66 + title="TypeScript"
67 +/>
68 +</CodeGroup>
69 +
70 +#### Option 3: Use environment variables
71 +
72 +```bash
73 +export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
74 +```
75 +
76 +Then execute normally:
77 +
78 +<CodeGroup>
79 +```python Python
80 +result = composio.tools.execute(
81 + "GITHUB_CREATE_ISSUE",
82 + {"user_id": "user-123", "arguments": {...}}
83 +)
84 +```
85 +
86 +```typescript TypeScript
87 +const result = await composio.tools.execute({
88 + toolSlug: "GITHUB_CREATE_ISSUE",
89 + userId: "user-123",
90 + arguments: {...}
91 +});
92 +```
93 +</CodeGroup>
94 +
95 +## Migration checklist
96 +
97 +1. **Audit your code**: Find all `tools.execute()` calls in your codebase
98 +2. **Choose a strategy**: Select one of the three options above based on your needs
99 +3. **Test thoroughly**: Verify tools work correctly with pinned versions
100 +4. **Deploy gradually**: Roll out changes incrementally to minimize risk
101 +
102 +## Temporary workaround
103 +
104 +During migration, you can temporarily skip version checks (not recommended for production):
105 +
106 +<CodeGroup>
107 +```python Python
108 +result = composio.tools.execute(
109 + "GITHUB_CREATE_ISSUE",
110 + {
111 + "user_id": "user-123",
112 + "arguments": {...}
113 + },
114 + dangerously_skip_version_check=True
115 +)
116 +```
117 +
118 +```typescript TypeScript
119 +const result = await composio.tools.execute({
120 + toolSlug: "GITHUB_CREATE_ISSUE",
121 + userId: "user-123",
122 + arguments: {...},
123 + dangerouslySkipVersionCheck: true
124 +});
125 +```
126 +</CodeGroup>
127 +
128 +<Warning>
129 +The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.
130 +</Warning>
131 +
132 +## Next steps
133 +
134 +For complete documentation on toolkit versioning, including best practices and advanced configuration, see [Toolkit versioning](/docs/toolkit-versioning).
\ No newline at end of file
fern/pages/src/tool-calling/executing-tools.mdx
+13 -2
@@ -63,11 +63,22 @@ In case you just want to call a tool without using any framework or LLM provider
63 tab](https://platform.composio.dev?next_page=/auth-configs) → Select your toolkit → Tools &
64 Triggers → Select the tool to see its required and optional parameters, types, and descriptions.
65 </Tip>
66 +
67 <CodeGroup>
67 - <SnippetCode src="fern/snippets/tool-calling/python/direct-tool-call.py" title="Python" />
68 - <SnippetCode src="fern/snippets/tool-calling/typescript/direct-tool-call.ts" title="TypeScript" />
68 + <SnippetCode
69 + src="fern/snippets/tool-calling/python/direct-tool-call.py"
70 + title="Python"
71 + />
72 + <SnippetCode
73 + src="fern/snippets/tool-calling/typescript/direct-tool-call.ts"
74 + title="TypeScript"
75 + />
76 </CodeGroup>
77
78 +<Note>
79 +The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/toolkit-versioning) for all configuration options.
80 +</Note>
81 +
82 ### Proxy Execute -- Manually calling toolkit APIs
83
84 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.
fern/pages/src/tool-calling/fetching-tools.mdx
+4
@@ -94,6 +94,10 @@ const tools = await composio.tools.get(userId, {
94 ```
95 </CodeGroup>
96
97 +## Tool versions
98 +
99 +You can configure toolkit versions at SDK initialization to ensure consistent tool behavior across environments. When fetching tools, you can also [inspect which version each tool is using](/docs/toolkit-versioning#inspect-current-versions).
100 +
101 ## Filtering by tool
102 You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.
103
fern/pages/src/tool-calling/toolkit-versioning.mdx new
+118
@@ -0,0 +1,118 @@
1 +---
2 +title: Toolkit versioning
3 +image: "https://og.composio.dev/api/og?title=Toolkit%20versioning"
4 +keywords: "toolkit versioning, tool version, version pinning, stable tools"
5 +subtitle: "Pin specific tool versions for consistent behavior in production"
6 +hide-nav-links: false
7 +---
8 +
9 +Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back when needed.
10 +
11 +<Note>
12 +Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.
13 +</Note>
14 +
15 +## Configuration methods
16 +
17 +Configure toolkit versions using one of three methods:
18 +
19 +### SDK initialization
20 +
21 +<CodeGroup>
22 +<SnippetCode
23 + src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
24 + title="Python"
25 +/>
26 +<SnippetCode
27 + src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
28 + title="TypeScript"
29 +/>
30 +</CodeGroup>
31 +
32 +### Environment variables
33 +
34 +```bash
35 +# Set versions for specific toolkits
36 +export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
37 +export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
38 +export COMPOSIO_TOOLKIT_VERSION_GMAIL="20250115_00"
39 +```
40 +
41 +### Per-execution override
42 +
43 +<CodeGroup>
44 +<SnippetCode
45 + src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
46 + title="Python"
47 +/>
48 +<SnippetCode
49 + src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
50 + title="TypeScript"
51 +/>
52 +</CodeGroup>
53 +
54 +## Version format
55 +
56 +Versions follow the format `YYYYMMDD_NN`:
57 +- `YYYYMMDD`: Release date
58 +- `NN`: Sequential release number
59 +
60 +```python
61 +# Production
62 +toolkit_versions = {"github": "20250116_00"}
63 +
64 +# Development
65 +toolkit_versions = {"github": "latest"}
66 +```
67 +
68 +<Warning>
69 +Never use `latest` in production. It can introduce breaking changes.
70 +</Warning>
71 +
72 +## Version resolution order
73 +
74 +1. Per-execution version (highest priority)
75 +2. SDK initialization version
76 +3. Environment variable (toolkit-specific)
77 +
78 +## Managing versions
79 +
80 +### List available versions
81 +
82 +Check what versions are available for a toolkit:
83 +
84 +<CodeGroup>
85 +<SnippetCode
86 + src="fern/snippets/tool-calling/versioning/python/manage-versions.py"
87 + startLine={8}
88 + endLine={11}
89 + title="Python"
90 +/>
91 +<SnippetCode
92 + src="fern/snippets/tool-calling/versioning/typescript/manage-versions.ts"
93 + startLine={8}
94 + endLine={12}
95 + title="TypeScript"
96 +/>
97 +</CodeGroup>
98 +
99 +### Inspect current versions
100 +
101 +Check which version your tools are actually using:
102 +
103 +<CodeGroup>
104 +<SnippetCode
105 + src="fern/snippets/tool-calling/versioning/python/manage-versions.py"
106 + startLine={13}
107 + endLine={16}
108 + title="Python"
109 +/>
110 +<SnippetCode
111 + src="fern/snippets/tool-calling/versioning/typescript/manage-versions.ts"
112 + startLine={14}
113 + endLine={20}
114 + title="TypeScript"
115 +/>
116 +</CodeGroup>
117 +
118 +
fern/snippets/tool-calling/python/direct-tool-call.py
+5 -1
@@ -1,7 +1,11 @@
1 from composio import Composio
2
3 user_id = "user-k7334"
4 -composio = Composio(api_key="your_composio_key")
4 +# Configure toolkit versions at SDK level
5 +composio = Composio(
6 + api_key="your_composio_key",
7 + toolkit_versions={"github": "20250116_00"}
8 +)
9
10 # Find available arguments for any tool in the Composio dashboard
11 result = composio.tools.execute(
fern/snippets/tool-calling/typescript/direct-tool-call.ts
+5 -1
@@ -1,7 +1,11 @@
1 import { Composio } from "@composio/core";
2
3 const userId = "user-k7334";
4 -const composio = new Composio({apiKey: "your_composio_key"});
4 +// Configure toolkit versions at SDK level
5 +const composio = new Composio({
6 + apiKey: "your_composio_key",
7 + toolkitVersions: { github: "20250116_00" }
8 +});
9
10 // Find available arguments for any tool in the Composio dashboard
11 const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
fern/snippets/tool-calling/versioning/python/manage-versions.py new
+16
@@ -0,0 +1,16 @@
1 +from composio import Composio
2 +
3 +composio = Composio(
4 + api_key="YOUR_API_KEY",
5 + toolkit_versions={"github": "20250116_00"}
6 +)
7 +
8 +# List available versions for a toolkit
9 +versions = composio.tools.get_toolkit_versions("github")
10 +for version in versions[:3]:
11 + print(f"Version: {version['version']} - Status: {version['status']}")
12 +
13 +# Fetch tools and inspect their versions
14 +tools = composio.tools.get("user-123", toolkits=["github"])
15 +for tool in tools[:3]:
16 + print(f"{tool.slug}: v{tool.toolkit_version}")
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/per-execution-override.py new
+16
@@ -0,0 +1,16 @@
1 +from composio import Composio
2 +
3 +composio = Composio(api_key="YOUR_API_KEY")
4 +
5 +# Specify version directly in execute call
6 +result = composio.tools.execute(
7 + "GITHUB_CREATE_ISSUE",
8 + {
9 + "user_id": "user-123",
10 + "arguments": {
11 + "repo": "my-repo",
12 + "title": "Critical fix"
13 + },
14 + "toolkit_version": "20250116_00" # Version for this execution
15 + }
16 +)
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/sdk-initialization.py new
+11
@@ -0,0 +1,11 @@
1 +from composio import Composio
2 +
3 +# Pin specific versions for each toolkit
4 +composio = Composio(
5 + api_key="YOUR_API_KEY",
6 + toolkit_versions={
7 + "github": "20250116_00",
8 + "slack": "20250115_01",
9 + "gmail": "20250115_00"
10 + }
11 +)
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/manage-versions.ts new
+20
@@ -0,0 +1,20 @@
1 +import { Composio } from "@composio/core";
2 +
3 +const composio = new Composio({
4 + apiKey: "YOUR_API_KEY",
5 + toolkitVersions: { github: "20250116_00" }
6 +});
7 +
8 +// List available versions for a toolkit
9 +const versions = await composio.tools.getToolkitVersions("github");
10 +versions.slice(0, 3).forEach(version => {
11 + console.log(`Version: ${version.version} - Status: ${version.status}`);
12 +});
13 +
14 +// Fetch tools and inspect their versions
15 +const tools = await composio.tools.get("user-123", {
16 + toolkits: ["github"]
17 +});
18 +tools.slice(0, 3).forEach(tool => {
19 + console.log(`${tool.slug}: v${tool.toolkitVersion}`);
20 +});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts new
+14
@@ -0,0 +1,14 @@
1 +import { Composio } from "@composio/core";
2 +
3 +const composio = new Composio({ apiKey: "YOUR_API_KEY" });
4 +
5 +// Specify version directly in execute call
6 +const result = await composio.tools.execute({
7 + toolSlug: "GITHUB_CREATE_ISSUE",
8 + userId: "user-123",
9 + arguments: {
10 + repo: "my-repo",
11 + title: "Critical fix"
12 + },
13 + toolkitVersion: "20250116_00" // Version for this execution
14 +});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts new
+11
@@ -0,0 +1,11 @@
1 +import { Composio } from "@composio/core";
2 +
3 +// Pin specific versions for each toolkit
4 +const composio = new Composio({
5 + apiKey: "YOUR_API_KEY",
6 + toolkitVersions: {
7 + github: "20250116_00",
8 + slack: "20250115_01",
9 + gmail: "20250115_00"
10 + }
11 +});
\ No newline at end of file