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 21, 11:00 UTC
docs: use hosted-account terminology and SDK workflows
Palash Kala committed
Sep 23, 2026 at 17:50 UTC
71abc8e7ab50420ebadadf1974f30f6bff4152e0
1 file changed
+112
-66
docs/content/docs/instant-tools.mdx
+112
-66
@@ -1,110 +1,156 @@
1
---
2
title: Instant Tools (Experimental)
3
description: Use supported tools in a Session without asking every user to connect a provider account
4
-keywords: [Instant Tools, Sessions, premium usage, Composio-managed account]
4
+keywords: [Instant Tools, Sessions, premium usage, hosted account]
5
---
6
7
-Instant Tools let your Session run supported tools without an end-user provider connection. For these tools, a Composio-managed account supplies the provider access and eligible calls incur a `premium_usage` charge against your organization's Composio balance.
7
+Instant Tools let your Session run supported tools without an end-user provider connection. A Composio hosted account provides access for eligible tools. Premium usage charges for those calls come from your organization's available balance.
8
9
<Callout type="warning" title="Experimental access">
10
This feature requires a project setting that is not yet self-service. Email [support@composio.dev](mailto:support@composio.dev) to enable it for your project and confirm which tools and rates are available. Session configuration cannot override a project where the setting is off.
11
</Callout>
12
13
-Once the project setting is enabled, new Sessions can use eligible billed tools by default, even if `premium_usage` is omitted. Send `"premium_usage": false` on Session creation if that Session must not use Composio-billed access.
13
+Once the project setting is enabled, new Sessions can use eligible Instant Tools by default, even if `premium_usage` is omitted. Set `premium_usage=False` in Python or `premiumUsage: false` in TypeScript when creating a Session that must not incur premium usage charges.
14
15
## Create a Session
16
17
-After your project is enabled, create a Session with an explicit `premium_usage` policy. This example makes Exa available to the Session and permits Composio-billed access for Exa:
18
-
19
-```bash
20
-curl --request POST \
21
- --url https://backend.composio.dev/api/v3.1/tool_router/session \
22
- --header "x-api-key: $COMPOSIO_API_KEY" \
23
- --header "content-type: application/json" \
24
- --data '{
25
- "user_id": "user_123",
26
- "toolkits": { "enable": ["exa"] },
27
- "premium_usage": {
28
- "toolkits": { "enable": ["exa"] },
29
- "return_premium_charge": true
30
- }
31
- }'
17
+After your project is enabled, create a Session. This example makes Exa available and permits premium usage for its eligible tools:
18
+
19
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20
+<Tab value="Python">
21
+```python
22
+from composio import Composio
23
+
24
+composio = Composio()
25
+session = composio.sessions.create(
26
+ user_id="user_123",
27
+ toolkits=["exa"],
28
+ premium_usage={
29
+ "toolkits": {"enable": ["exa"]},
30
+ "return_premium_charge": True,
31
+ },
32
+)
33
```
34
+</Tab>
35
+<Tab value="TypeScript">
36
+```typescript
37
+import { Composio } from "@composio/core";
38
+
39
+const composio = new Composio();
40
+const session = await composio.create("user_123", {
41
+ toolkits: ["exa"],
42
+ premiumUsage: {
43
+ toolkits: { enable: ["exa"] },
44
+ returnPremiumCharge: true,
45
+ },
46
+});
47
+```
48
+</Tab>
49
+</Tabs>
50
34
-The response includes a `session_id` and the effective `config`. Use the `session_id` for Session-scoped tool search and execution.
35
-
36
-The two toolkit lists control different things. Top-level `toolkits` controls which tools the Session can discover and run. `premium_usage.toolkits` controls which of those toolkits can use a Composio-billed route. A toolkit must pass *both* filters. An eligible toolkit can still contain tools that require a connected account.
51
+Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `premium_usage.toolkits` (or `premiumUsage.toolkits` in TypeScript) separately restricts which eligible tools can incur premium usage charges. Omit that filter to permit all eligible toolkits. An Instant toolkit can still contain tools that need a connected account; hosted account coverage is tool-specific.
52
53
## Find and run a tool
54
40
-You can inspect a tool's input schema with the [get tool endpoint](/reference/api-reference/tools/getToolsByToolSlug). For example:
55
+Pass `session.tools()` to your agent as in the [Quickstart](/docs/quickstart), so it can discover and run eligible tools. If your agent uses MCP, expose the same Session through `session.mcp` as described in [Using sessions via MCP](/docs/sessions-via-mcp). The premium usage policy applies to that Session in either path; your agent does not need a separate premium usage setting.
56
42
-```bash
43
-curl --request GET \
44
- --url https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH \
45
- --header "x-api-key: $COMPOSIO_API_KEY"
57
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
58
+<Tab value="Python">
59
+```python
60
+tools = session.tools() # Pass these to your agent framework.
61
```
62
+</Tab>
63
+<Tab value="TypeScript">
64
+```typescript
65
+const tools = await session.tools(); // Pass these to your agent framework.
66
+```
67
+</Tab>
68
+</Tabs>
69
+
70
+To run a known tool yourself, use the Session's `execute` method:
71
48
-Then execute a tool through the Session using the [Session execute endpoint](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute):
49
-
50
-```bash
51
-curl --request POST \
52
- --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute" \
53
- --header "x-api-key: $COMPOSIO_API_KEY" \
54
- --header "content-type: application/json" \
55
- --data '{
56
- "tool_slug": "EXA_SEARCH",
57
- "arguments": { "query": "Composio documentation" }
58
- }'
72
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
73
+<Tab value="Python">
74
+```python
75
+result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentation"})
76
```
77
+</Tab>
78
+<Tab value="TypeScript">
79
+```typescript
80
+const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
81
+```
82
+</Tab>
83
+</Tabs>
84
+
85
+Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments. A tool appearing in a toolkit does not mean hosted account access is available for that tool. Confirm supported tools and rates during Experimental access.
86
61
-Check the current tool schema before constructing `arguments`; fields can change with the tool version. The current tools API does *not* provide a structured Instant eligibility or price field. A tool appearing in a toolkit does not mean Composio-billed access is available for that tool. Confirm the supported tool list and rates during Experimental access.
87
+## Control premium usage
88
63
-## Control billed access
89
+`premium_usage` is a Session policy (`premiumUsage` in TypeScript). It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
90
65
-`premium_usage` is a Session policy. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
91
+The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable premium usage for other eligible toolkits. Use `premium_usage.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
92
67
-The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable billed access for other eligible toolkits. Use `premium_usage.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
93
+The examples below use Python and REST field names. In TypeScript, use `premiumUsage` and `returnPremiumCharge`.
94
95
| Session value | Effect |
96
|---|---|
71
-| Omitted or `{}` | Permits eligible Composio-billed tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
72
-| `false` | Disables Composio-billed access for that Session. Your own connected-account routes remain available. |
73
-| `{ "toolkits": { "enable": ["exa"] } }` | Permits billed access only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
74
-| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows billed access to selected tools within a toolkit. |
97
+| Omitted or `{}` | Permits premium usage for eligible tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
98
+| `false` | Disables premium usage for that Session. Your own connected-account routes remain available. |
99
+| `{ "toolkits": { "enable": ["exa"] } }` | Permits premium usage only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
100
+| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows premium usage to selected tools within a toolkit. |
101
| `{ "return_premium_charge": true }` | Requests the actual `premium_charge` in an eligible Session tool response. This changes charge visibility, not permission to spend. |
102
77
-For example, keep Exa and Firecrawl available, but permit billed access only for `EXA_SEARCH`:
78
-
79
-```json
80
-{
81
- "user_id": "user_123",
82
- "toolkits": { "enable": ["exa", "firecrawl"] },
83
- "premium_usage": {
84
- "toolkits": { "enable": ["exa"] },
85
- "tools": { "exa": { "enable": ["EXA_SEARCH"] } }
86
- }
87
-}
103
+For example, keep Exa and Firecrawl available, but permit premium usage only for `EXA_SEARCH`:
104
+
105
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
106
+<Tab value="Python">
107
+```python
108
+session = composio.sessions.create(
109
+ user_id="user_123",
110
+ toolkits=["exa", "firecrawl"],
111
+ premium_usage={
112
+ "toolkits": {"enable": ["exa"]},
113
+ "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
114
+ },
115
+)
116
```
117
+</Tab>
118
+<Tab value="TypeScript">
119
+```typescript
120
+const session = await composio.create("user_123", {
121
+ toolkits: ["exa", "firecrawl"],
122
+ premiumUsage: {
123
+ toolkits: { enable: ["exa"] },
124
+ tools: { exa: { enable: ["EXA_SEARCH"] } },
125
+ },
126
+});
127
+```
128
+</Tab>
129
+</Tabs>
130
90
-To stop Composio-billed access on an existing Session, use the [Session patch endpoint](/reference/api-reference/tool-router/patchToolRouterSessionBySessionId):
131
+To stop premium usage on an existing Session, update its policy:
132
92
-```bash
93
-curl --request PATCH \
94
- --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID" \
95
- --header "x-api-key: $COMPOSIO_API_KEY" \
96
- --header "content-type: application/json" \
97
- --data '{ "premium_usage": false }'
133
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
134
+<Tab value="Python">
135
+```python
136
+session.update(premium_usage=False)
137
+```
138
+</Tab>
139
+<Tab value="TypeScript">
140
+```typescript
141
+await session.update({ premiumUsage: false });
142
```
143
+</Tab>
144
+</Tabs>
145
146
On patch, omitted `premium_usage` fields keep their existing values. Supplying an object after `false` enables this Session policy again, provided the project allows it.
147
148
## Know which account runs the tool
149
104
-A Composio-managed account is a provider account held by Composio for specific tools. It is different from **Composio-managed auth**, where Composio supplies OAuth application credentials but your user still connects their own account. Composio-managed auth alone does not make a tool Instant.
150
+A hosted account is a provider account held by Composio for specific tools. It is different from **Composio-managed auth**, where Composio supplies OAuth application credentials but your user still connects their own account. Composio-managed auth alone does not make a tool Instant.
151
106
-If you select a connected account explicitly, that route wins and does not fall back to Composio's account on failure. Otherwise, available user, shared, or developer connections take priority over a Composio-managed account. If the chosen tool is not supported by a Composio-managed account, it follows the normal connection flow.
152
+If you select a connected account explicitly, that route wins and does not fall back to the hosted account on failure. Otherwise, available user, shared, or developer connections take priority over a hosted account. If the chosen tool is not supported by a hosted account, it follows the normal connection flow.
153
108
-Composio-managed accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
154
+Hosted accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
155
156
See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/api-reference/tool-router/postToolRouterSession) for the complete request schema.