@devries-cameron20 / composio Mirror · read-only / commits / 3d383bcf1
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 21, 11:00 UTC

docs: use Instant contract names throughout guide

Palash Kala committed Sep 29, 2026 at 20:04 UTC 3d383bcf1add46070659f977ed0199cf0175d43a
1 file changed +39 -35
docs/content/docs/instant-tools.mdx
+39 -35
@@ -1,7 +1,7 @@
1 ---
2 title: Instant Tools
3 description: Use supported tools in a Session without asking every user to connect a provider account
4 -keywords: [Instant Tools, Sessions, premium usage, hosted account]
4 +keywords: [Instant Tools, Sessions, Instant usage, Instant account]
5 experimental: true
6 ---
7
@@ -11,17 +11,19 @@ Adding a capability to your agent can mean another provider account, API key, an
11 The project setting `enable_instant` must be `true`. It is off by default and 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.
12 </Callout>
13
14 -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 +Once the project setting is enabled, new Sessions can use eligible Instant Tools by default, even if `instant` is omitted. Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session that must not incur Instant usage charges.
15 +
16 +Project configuration uses `enable_instant` in API requests and responses. The SDK has no project-settings setter; configure the project before creating a Session. Existing project and Session settings saved under the previous names must be saved again under the Instant names. The previous names are not aliases.
17
18 ## Find eligible tools
19
20 Instant coverage is per tool, not per toolkit. A toolkit may support Instant Tools without every tool in it being eligible. Composio's provider account can be shared across customers, so only reviewed actions can run through it. Actions that could reveal shared account history or send arbitrary proxy requests are excluded. Use a connected account for actions Instant does not support.
21
20 -The current [toolkit listing API](/reference/api-reference/toolkits/getToolkits) does not return Instant availability or offer an Instant filter. Its `no_auth` and `composio_managed_auth_schemes` fields mean different things and should not be used as substitutes. During Experimental access, ask [support@composio.dev](mailto:support@composio.dev) for the supported tools and rates before allowing them in a production Session.
22 +The current [toolkit listing API](/reference/api-reference/toolkits/getToolkits) does not return Instant availability or offer an Instant filter. Its `no_auth` and `composio_managed_auth_schemes` fields mean different things and should not be used as substitutes. Catalogs that expose Instant account coverage use `instant_account_available`; that describes coverage, not permission to execute. During Experimental access, ask [support@composio.dev](mailto:support@composio.dev) for the supported tools and rates before allowing them in a production Session.
23
24 ## Create a Session
25
24 -After your project is enabled, create a Session. This example makes Exa available and permits premium usage for its eligible tools:
26 +After your project is enabled, create a Session. This example makes Exa available and permits Instant usage for its eligible tools:
27
28 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
29 <Tab value="Python">
@@ -32,9 +34,9 @@ composio = Composio()
34 session = composio.sessions.create(
35 user_id="user_123",
36 toolkits=["exa"],
35 - premium_usage={
37 + instant={
38 "toolkits": {"enable": ["exa"]},
37 - "return_premium_charge": True,
39 + "return_instant_charge": True,
40 },
41 )
42 ```
@@ -47,20 +49,20 @@ import { Composio } from "@composio/core";
49 const composio = new Composio();
50 const session = await composio.create("user_123", {
51 toolkits: ["exa"],
50 - premiumUsage: {
52 + instant: {
53 toolkits: { enable: ["exa"] },
52 - returnPremiumCharge: true,
54 + returnInstantCharge: true,
55 },
56 });
57 ```
58 </Tab>
59 </Tabs>
60
59 -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. Omitting `premium_usage.toolkits` does not restrict premium usage: eligible tools remain available when the project and Session permit them. `return_premium_charge` defaults to `false` and only controls whether the actual charge appears in the immediate tool response. An Instant toolkit can still contain tools that need a connected account; hosted account coverage is tool-specific.
61 +Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `instant.toolkits` separately restricts which eligible tools can incur Instant usage charges. Omitting it leaves eligible tools available when the project and Session permit them. `return_instant_charge` defaults to `false` and only controls whether the actual charge appears in the immediate tool response. A toolkit that supports Instant can still contain tools that need a connected account.
62
63 ## Find and run a tool
64
63 -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.
65 +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 Instant usage policy applies to that Session in either path; your agent does not need a separate Instant usage setting.
66
67 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
68 <Tab value="Python">
@@ -98,37 +100,37 @@ const result = await session.execute("EXA_SEARCH", { query: "Composio documentat
100 </Tab>
101 </Tabs>
102
101 -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.
103 +Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments. A tool appearing in a toolkit does not mean Instant account access is available for that tool. Confirm supported tools and rates during Experimental access.
104
105 ### Read charge details in Python
106
105 -With `premium_usage.return_premium_charge` enabled, `session.execute()` returns charge details when available in the typed `premium_charge` field on `ToolRouterSessionExecuteResponse`. Read it from the result above:
107 +With `instant.return_instant_charge` enabled, `session.execute()` returns charge details when available in the typed `instant_charge` field on `ToolRouterSessionExecuteResponse`. Read it from the result above:
108
109 ```python
108 -charge = result.premium_charge
110 +charge = result.instant_charge
111 if charge is not None:
112 print(charge["amount"], charge["currency"], charge["charged_by"])
113 ```
114
113 -The `PremiumCharge` type is exported from `composio.types` and includes `amount`, `currency`, and `charged_by`. Python provider integrations and mixed local/remote multi-tool execution also preserve these charge details.
115 +The `InstantCharge` type is exported from `composio.types` and includes `amount`, `currency`, and `charged_by`. Python provider integrations and mixed local/remote multi-tool execution also preserve these charge details.
116
115 -## Control premium usage
117 +## Control Instant usage
118
117 -`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.
119 +`instant` is a Session policy in both SDKs. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
120
119 -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.
121 +The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable Instant usage for other eligible toolkits. Use `instant.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
122
121 -The examples below use Python and REST field names. In TypeScript, use `premiumUsage` and `returnPremiumCharge`, and read the charge from `premiumCharge` on the tool result.
123 +The examples below use Python and REST field names. In TypeScript, use `instant` and `returnInstantCharge`, and read the charge from `instantCharge` on the tool result.
124
125 | Session value | Effect |
126 |---|---|
125 -| 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. |
126 -| `false` | Disables premium usage for that Session. Your own connected-account routes remain available. |
127 -| `{ "toolkits": { "enable": ["exa"] } }` | Permits premium usage only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
128 -| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows premium usage to selected tools within a toolkit. |
129 -| `{ "return_premium_charge": true }` | Requests the actual `premium_charge` in an eligible Session tool response. On create, this changes charge visibility, not permission to spend. On update, it also re-enables premium usage on a Session set to `false`, like any other object. |
127 +| Omitted or `{}` | Permits Instant usage for eligible tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
128 +| `false` | Disables Instant usage for that Session. Your own connected-account routes remain available. |
129 +| `{ "toolkits": { "enable": ["exa"] } }` | Permits Instant usage only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
130 +| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows Instant usage to selected tools within a toolkit. |
131 +| `{ "return_instant_charge": true }` | Requests the actual `instant_charge` in an eligible Session tool response. On create, this changes charge visibility, not permission to spend. On update, it also re-enables Instant usage on a Session set to `false`, like any other object. |
132
131 -For example, keep Exa and Firecrawl available, but permit premium usage only for `EXA_SEARCH`:
133 +For example, keep Exa and Firecrawl available, but permit Instant usage only for `EXA_SEARCH`:
134
135 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
136 <Tab value="Python">
@@ -136,7 +138,7 @@ For example, keep Exa and Firecrawl available, but permit premium usage only for
138 session = composio.sessions.create(
139 user_id="user_123",
140 toolkits=["exa", "firecrawl"],
139 - premium_usage={
141 + instant={
142 "toolkits": {"enable": ["exa"]},
143 "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
144 },
@@ -148,7 +150,7 @@ session = composio.sessions.create(
150 // @noErrors
151 const session = await composio.create("user_123", {
152 toolkits: ["exa", "firecrawl"],
151 - premiumUsage: {
153 + instant: {
154 toolkits: { enable: ["exa"] },
155 tools: { exa: { enable: ["EXA_SEARCH"] } },
156 },
@@ -157,36 +159,38 @@ const session = await composio.create("user_123", {
159 </Tab>
160 </Tabs>
161
160 -To stop premium usage on an existing Session, update its policy:
162 +To stop Instant usage on an existing Session, update its policy:
163
164 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
165 <Tab value="Python">
166 ```python
165 -session.update(premium_usage=False)
167 +session.update(instant=False)
168 ```
169 </Tab>
170 <Tab value="TypeScript">
171 ```typescript
172 // @noErrors
171 -await session.update({ premiumUsage: false });
173 +await session.update({ instant: false });
174 ```
175 </Tab>
176 </Tabs>
177
176 -On patch, omitted `premium_usage` fields keep their existing values. Supplying any object after `false`, even one that only sets `return_premium_charge`, enables this Session policy again, provided the project allows it.
178 +On patch, omitted `instant` fields keep their existing values. Supplying any object after `false`, even one that only sets `return_instant_charge`, enables this Session policy again, provided the project allows it.
179
180 ## Know which account runs the tool
181
180 -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.
182 +An Instant 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.
183 +
184 +If you select a connected account explicitly, that route wins and does not fall back to the Instant account on failure. Otherwise, available user or shared connections take priority over an Instant account. If the chosen tool is not supported by an Instant account, it follows the normal connection flow.
185
182 -If you select a connected account explicitly, that route wins and does not fall back to the hosted account on failure. Otherwise, available user or shared connections take priority over a hosted account. If the chosen tool is not supported by a hosted account, it follows the normal connection flow.
186 +Session search tells you when an Instant account serves a toolkit. The toolkit's connection status includes `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript), which lists the tools that run on it. Any other tool in that toolkit needs the user's own connection.
187
184 -Session search tells you when a hosted account serves a toolkit. The toolkit's connection status includes `hosted_account.allowed_tool_slugs` (`hostedAccount.allowedToolSlugs` in TypeScript), which lists the tools that run on it. Any other tool in that toolkit needs the user's own connection.
188 +To choose the Instant account explicitly, pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. This route does not fall back to another credential if it fails.
189
186 -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.
190 +Instant accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `instant` policy.
191
192 ## Review usage
193
190 -Use the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary) for totals and the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution) for individual calls. Filter logs by `session_id` when you need to trace a Session. These records remain available even when `return_premium_charge` is `false`.
194 +Use the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary) for totals and the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution) for individual calls. The summary's `instant_charge` is a top-level field; individual log charges appear in `metadata.instant_charge`. Both are exact USD strings. Filter logs by `session_id` when you need to trace a Session. These records remain available even when `return_instant_charge` is `false`.
195
196 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.