Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: include tested optional Instant Session setup helper
Shashwat Singh committed
Oct 28, 2026 at 19:08 UTC
8fa94ddd3119dc9404b2b9b35ea95c9ea6e4128b
2 files changed
+157
docs/content/docs/migration-guide/no-auth-to-instant.mdx
+23
@@ -94,3 +94,26 @@ Where supported, your users can connect their own provider credentials instead.
94
4. Check existing Sessions and pinned direct-tool versions. A successful replacement call doesn't prove every old workflow has migrated.
95
96
After the cutoff, affected legacy executions will stop working. If you need help mapping an action or adapting a workflow, contact [support@composio.dev](mailto:support@composio.dev).
97
+
98
+
99
+## Optional Session setup helper
100
+
101
+[Download the Python helper](/assets/migrations/migrate_no_auth_to_instant.py) if you want to preview and create a replacement Session with explicit toolkit and tool allowlists. It requires Python 3.10 or later and uses only the standard library.
102
+
103
+Save the file locally, inspect it, then preview a request:
104
+
105
+```bash
106
+python3 migrate_no_auth_to_instant.py --user-id user_123 --tool exa:EXA_SEARCH
107
+```
108
+
109
+Use your existing application user ID and repeat `--tool toolkit:TOOL_SLUG` for each required action. The preview makes no network requests. The helper does not guess equivalents for retired actions or adapt their arguments and responses.
110
+
111
+After enabling Instant and funding the intended project's organization, set `COMPOSIO_API_KEY` securely for that project. Review the selected actions and their published rates before creating a replacement Session:
112
+
113
+```bash
114
+python3 migrate_no_auth_to_instant.py --user-id user_123 --tool exa:EXA_SEARCH --apply
115
+```
116
+
117
+`--apply` verifies each tool's current identity, Instant support and published price, then creates one Session. It does not run provider tools, edit existing Sessions, change project settings, or rewrite your application. Use the returned Session ID in your application and test the workflow separately. Normal account-selection rules still apply.
118
+
119
+If creation times out or returns an ambiguous server error, inspect your project before trying again. The helper never retries automatically. This helper is for Sessions; direct-tool callers should follow the separate guidance above.
docs/public/assets/migrations/migrate_no_auth_to_instant.py
new
+134
@@ -0,0 +1,134 @@
1
+#!/usr/bin/env python3
2
+"""Preview or create a replacement Session with explicitly selected Instant tools.
3
+
4
+Default: print a plan, with no network requests. --apply reads COMPOSIO_API_KEY,
5
+verifies current tool metadata, and creates one Session. No provider tool runs.
6
+"""
7
+import argparse
8
+import json
9
+import os
10
+import re
11
+import sys
12
+import urllib.error
13
+import urllib.parse
14
+import urllib.request
15
+
16
+BASE = "https://backend.composio.dev"
17
+RETIRED = {
18
+ "browser_tool": "Choose supported browser_use tools.",
19
+ "composio_search": "Choose supported exa, tavily, or serpapi tools.",
20
+ "text_to_pdf": "Adapt the workflow. pdf_co URL conversion is not an inline text/Markdown replacement.",
21
+ "weathermap": "Choose supported accu_weather tools and adapt arguments and responses.",
22
+}
23
+
24
+
25
+def selected_tools(values):
26
+ selected = {}
27
+ for value in values:
28
+ parts = value.split(":")
29
+ if len(parts) != 2:
30
+ raise ValueError("Each --tool must be TOOLKIT:TOOL_SLUG, for example exa:EXA_SEARCH.")
31
+ toolkit, slug = parts
32
+ if not re.fullmatch(r"[a-z][a-z0-9_]*", toolkit) or not re.fullmatch(r"[A-Z][A-Z0-9_]*", slug):
33
+ raise ValueError("Use an exact lowercase toolkit slug and uppercase tool slug.")
34
+ if toolkit in RETIRED:
35
+ raise ValueError(toolkit + ": " + RETIRED[toolkit])
36
+ if slug in selected.setdefault(toolkit, []):
37
+ raise ValueError("Duplicate tool: " + value)
38
+ if any(slug in tools for name, tools in selected.items() if name != toolkit):
39
+ raise ValueError("A tool slug cannot be assigned to multiple toolkits.")
40
+ selected[toolkit].append(slug)
41
+ return {name: sorted(tools) for name, tools in sorted(selected.items())}
42
+
43
+
44
+def make_payload(user_id, selected):
45
+ filters = {name: {"enable": tools} for name, tools in selected.items()}
46
+ return {
47
+ "user_id": user_id,
48
+ "toolkits": {"enable": list(selected)},
49
+ "tools": filters,
50
+ "instant": {"toolkits": {"enable": list(selected)}, "tools": filters},
51
+ }
52
+
53
+
54
+def request(method, path, key, body=None):
55
+ data = None if body is None else json.dumps(body).encode("utf-8")
56
+ req = urllib.request.Request(
57
+ BASE + path,
58
+ data=data,
59
+ method=method,
60
+ headers={"x-api-key": key, "Content-Type": "application/json"},
61
+ )
62
+ try:
63
+ with urllib.request.urlopen(req, timeout=30) as response:
64
+ return json.load(response)
65
+ except urllib.error.HTTPError as error:
66
+ if method == "POST" and (error.code >= 500 or error.code in (408, 429)):
67
+ raise RuntimeError(f"POST returned HTTP {error.code}. Session creation outcome is unknown. Check your project before trying again. No automatic retry was made.") from None
68
+ raise RuntimeError(f"{method} returned HTTP {error.code}. Check the project and permissions; no retry was made.") from None
69
+ except (OSError, TimeoutError, json.JSONDecodeError, UnicodeError):
70
+ message = "Session creation outcome is unknown. Check your project before trying again." if method == "POST" else "Metadata could not be read. No Session was created."
71
+ raise RuntimeError(message + " No automatic retry was made.") from None
72
+
73
+
74
+def verify_tools(selected, key):
75
+ for toolkit, slugs in selected.items():
76
+ for slug in slugs:
77
+ path = "/api/v3.1/tools/" + urllib.parse.quote(slug, safe="") + "?toolkit_versions=latest&include_pricing=true"
78
+ tool = request("GET", path, key)
79
+ if not isinstance(tool, dict):
80
+ raise RuntimeError("Unexpected tool metadata; no Session was created.")
81
+ toolkit_info = tool.get("toolkit")
82
+ if not isinstance(toolkit_info, dict) or tool.get("slug") != slug or toolkit_info.get("slug") != toolkit:
83
+ raise RuntimeError("Tool identity mismatch for " + slug + "; no Session was created.")
84
+ instant = tool.get("instant") or {}
85
+ if not isinstance(instant, dict) or instant.get("supported") is not True:
86
+ raise RuntimeError(slug + " does not currently report Instant support; no Session was created.")
87
+ price = instant.get("price") or {}
88
+ if not isinstance(price, dict):
89
+ raise RuntimeError("Invalid published price for " + slug + "; no Session was created.")
90
+ description = price.get("description")
91
+ if not isinstance(description, str) or not description.strip():
92
+ raise RuntimeError("Missing published price for " + slug + "; no Session was created.")
93
+ print(slug + ": " + description)
94
+ if price.get("discount") is not None:
95
+ print("Published discount: " + str(price["discount"]))
96
+
97
+
98
+def main(argv=None):
99
+ parser = argparse.ArgumentParser(description=__doc__)
100
+ parser.add_argument("--user-id", required=True, help="Your application's existing user ID.")
101
+ parser.add_argument("--tool", action="append", required=True, help="Exact TOOLKIT:TOOL_SLUG; repeat for each allowed tool.")
102
+ parser.add_argument("--apply", action="store_true", help="Verify metadata and create one replacement Session. Does not execute tools.")
103
+ args = parser.parse_args(argv)
104
+ if not args.user_id.strip():
105
+ parser.error("--user-id must not be empty")
106
+ try:
107
+ selected = selected_tools(args.tool)
108
+ except ValueError as error:
109
+ parser.error(str(error))
110
+ payload = make_payload(args.user_id, selected)
111
+ print(json.dumps({"method": "POST", "url": BASE + "/api/v3.1/tool_router/session", "body": payload}, indent=2))
112
+ if not args.apply:
113
+ print("Preview only. No network requests made. Review tool schemas and published rates before using --apply.")
114
+ return 0
115
+ key = os.environ.get("COMPOSIO_API_KEY", "")
116
+ if not key:
117
+ parser.error("Set COMPOSIO_API_KEY for the intended project before using --apply.")
118
+ try:
119
+ verify_tools(selected, key)
120
+ result = request("POST", "/api/v3.1/tool_router/session", key, payload)
121
+ except RuntimeError as error:
122
+ print(str(error), file=sys.stderr)
123
+ return 1
124
+ session_id = result.get("session_id") if isinstance(result, dict) else None
125
+ if not isinstance(session_id, str) or not session_id:
126
+ print("Session creation response did not include session_id. Outcome is unknown; inspect your project before retrying.", file=sys.stderr)
127
+ return 1
128
+ print("Created replacement Session: " + session_id)
129
+ print("Use this Session in your application. Existing Sessions and application code were not changed. No provider tool was executed.")
130
+ return 0
131
+
132
+
133
+if __name__ == "__main__":
134
+ sys.exit(main())