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

next
mdx 448 lines 20.4 KB
Raw
1 ---
2 title: Instant Tools
3 description: Give your agent supported tools without asking every user to connect a provider account
4 keywords: [Composio Instant, instant tools, Sessions, Instant usage, Instant account]
5 experimental: true
6 ---
7
8 Instant Tools run supported actions on Composio's provider accounts and charge your organization's Composio balance. Your users don't need a separate provider account or API key.
9
10 - **Set up basic controls:** [Allow or exclude toolkits and tools](#allow-or-exclude-specific-toolkits-and-tools), or [turn Instant off](#turn-instant-off).
11 - **Want approval before spending?** Keep execution in your application and [ask before each call](#approve-a-tool-call-before-spending).
12 - **Need a Session spend cap?** There is no built-in dollar cap. Use an [application-side budget](#limit-session-spending), or disable Instant with `instant=False` in Python or `instant: false` in TypeScript.
13
14 New to Composio? Follow the [Quickstart](/docs/quickstart) for SDK installation and set `COMPOSIO_API_KEY` before running the examples.
15
16 ## Enable Instant
17
18 1. Turn on **Instant Toolkits** in [project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). It's off by default.
19 2. Check your organization's prepaid balance in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools).
20
21 Once enabled, eligible tools can use Instant in new and existing Sessions unless their Session policy prevents it. Omitting `instant` permits Instant usage; a Session cannot override a project where Instant is off.
22
23 <Callout type="info" title="Experimental access">
24 If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
25 </Callout>
26
27 ## Control Instant usage
28
29 The Session's top-level `toolkits` filter controls which toolkits your agent can use. The separate `instant` setting controls whether it can use Composio's Instant accounts for those tools.
30
31 ### Allow or exclude specific toolkits and tools
32
33 Keep Exa and Firecrawl available, but allow Instant only for `EXA_SEARCH`:
34
35 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
36 <Tab value="Python">
37 ```python
38 session = composio.sessions.create(
39 user_id="user_123",
40 toolkits=["exa", "firecrawl"],
41 instant={
42 "toolkits": {"enable": ["exa"]},
43 "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
44 },
45 )
46 ```
47 </Tab>
48 <Tab value="TypeScript">
49 ```typescript
50 import { Composio } from "@composio/core";
51 const composio = new Composio();
52 // ---cut---
53 const session = await composio.create("user_123", {
54 toolkits: ["exa", "firecrawl"],
55 instant: {
56 toolkits: { enable: ["exa"] },
57 tools: { exa: { enable: ["EXA_SEARCH"] } },
58 },
59 });
60 ```
61 </Tab>
62 <Tab value="API">
63 ```bash
64 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
65 -H "x-api-key: $COMPOSIO_API_KEY" \
66 -H "Content-Type: application/json" \
67 -d '{
68 "user_id": "user_123",
69 "toolkits": {"enable": ["exa", "firecrawl"]},
70 "instant": {
71 "toolkits": {"enable": ["exa"]},
72 "tools": {"exa": {"enable": ["EXA_SEARCH"]}}
73 }
74 }'
75 ```
76 </Tab>
77 </Tabs>
78
79 Use `disable` instead of `enable` to exclude the listed toolkits or tools. Each filter accepts one or the other, not both. Toolkit and tool filters intersect; they cannot enable anything excluded by the Session's top-level filters.
80
81 Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.
82
83 ### Turn Instant off
84
85 Your own connected accounts remain available when you disable Instant:
86
87 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
88 <Tab value="Python">
89 ```python
90 session.update(instant=False)
91 ```
92 </Tab>
93 <Tab value="TypeScript">
94 ```typescript
95 import { Composio } from "@composio/core";
96 const composio = new Composio();
97 const session = await composio.create("user_123");
98 // ---cut---
99 await session.update({ instant: false });
100 ```
101 </Tab>
102 <Tab value="API">
103 ```bash
104 curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
105 -H "x-api-key: $COMPOSIO_API_KEY" \
106 -H "Content-Type: application/json" \
107 -d '{"instant": false}'
108 ```
109 </Tab>
110 </Tabs>
111
112 <Callout type="warning" title="Updating a disabled Session">
113 Passing any `instant` object after `instant=false` re-enables Instant usage if the project allows it, even if you only set charge reporting. Keep `instant` as `false` when the Session must not spend. Omitting `instant` from an update preserves the existing policy.
114 </Callout>
115
116 ## Approve a tool call before spending
117
118 This human-in-the-loop (HITL) example asks you to approve one Firecrawl scrape before executing it. First, inspect the tool's current published rate:
119
120 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
121 <Tab value="Python">
122 ```python
123 from composio import Composio
124
125 composio = Composio()
126 tool = composio.client.get(
127 "/api/v3.1/tools/FIRECRAWL_SCRAPE",
128 cast_to=object,
129 query={"toolkit_versions": "latest", "include_pricing": True},
130 )
131 print(tool)
132 ```
133 </Tab>
134 <Tab value="TypeScript">
135 ```typescript
136 import { Composio } from '@composio/core';
137
138 const composio = new Composio();
139 const tool = await composio.getClient().get<unknown>('/api/v3.1/tools/FIRECRAWL_SCRAPE', {
140 query: { toolkit_versions: 'latest', include_pricing: true },
141 });
142 console.log(tool);
143 ```
144 </Tab>
145 <Tab value="API">
146 ```bash
147 curl -s -X GET "https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE?toolkit_versions=latest&include_pricing=true" \
148 -H "x-api-key: $COMPOSIO_API_KEY" \
149 | jq '{slug, instant, input_parameters}'
150 ```
151 </Tab>
152 </Tabs>
153
154 Check that `instant.supported` is `true`. Read `instant.price.description` and any `instant.price.discount` before approving. These are strings, not a machine-readable maximum cost; missing pricing does not mean the tool is free.
155
156 Then run the example. It shows the exact arguments, waits for `yes`, and makes one tool call. Any other answer exits without creating a Session or executing the tool.
157
158 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
159 <Tab value="Python">
160 ```python
161 import json
162 from composio import Composio
163
164 tool = "FIRECRAWL_SCRAPE"
165 arguments = {"url": "https://composio.dev"}
166
167 print(tool, json.dumps(arguments))
168 if input("Approve this call at the published rate? Type yes: ").strip().lower() != "yes":
169 raise SystemExit("Not approved. No tool call made.")
170
171 composio = Composio()
172 session = composio.sessions.create(
173 user_id="instant_demo",
174 toolkits=["firecrawl"],
175 instant={"return_instant_charge": True},
176 )
177 result = session.execute(tool, arguments=arguments, account="instant_account")
178 print(result)
179 print("Instant charge:", result.instant_charge)
180 ```
181 </Tab>
182 <Tab value="TypeScript">
183 ```typescript
184 import { createInterface } from "node:readline/promises";
185 import { Composio } from "@composio/core";
186
187 const tool = "FIRECRAWL_SCRAPE";
188 const args = { url: "https://composio.dev" };
189 const prompt = createInterface({ input: process.stdin, output: process.stdout });
190
191 console.log(tool, JSON.stringify(args));
192 let answer: string;
193 try {
194 answer = await prompt.question("Approve this call at the published rate? Type yes: ");
195 } finally {
196 prompt.close();
197 }
198 if (answer.trim().toLowerCase() !== "yes") {
199 throw new Error("Not approved. No tool call made.");
200 }
201
202 const composio = new Composio();
203 const session = await composio.create("instant_demo", {
204 toolkits: ["firecrawl"],
205 instant: { returnInstantCharge: true },
206 });
207 const result = await session.execute(tool, args, { account: "instant_account" });
208 console.log(result);
209 console.log("Instant charge:", result.instantCharge);
210 ```
211 </Tab>
212 <Tab value="API">
213 ```bash
214 echo 'FIRECRAWL_SCRAPE {"url": "https://composio.dev"}'
215 read -r -p "Approve this call at the published rate? Type yes: " ANSWER
216 if [ "$ANSWER" != "yes" ]; then
217 echo "Not approved. No tool call made."
218 exit 1
219 fi
220
221 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
222 -H "x-api-key: $COMPOSIO_API_KEY" \
223 -H "Content-Type: application/json" \
224 -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_instant_charge": true}}' \
225 | jq -r '.session_id')
226
227 curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
228 -H "x-api-key: $COMPOSIO_API_KEY" \
229 -H "Content-Type: application/json" \
230 -d '{"tool_slug": "FIRECRAWL_SCRAPE", "arguments": {"url": "https://composio.dev"}, "account": "instant_account"}' \
231 | jq '{result_type, data, instant_charge}'
232 ```
233 </Tab>
234 </Tabs>
235
236 `account="instant_account"` (Python) or `account: "instant_account"` (TypeScript) explicitly selects Instant rather than your user's provider connection. The response reports the charge when available. To verify billing, check `metadata.credential_source` and `metadata.instant_charge` in the [execution logs](/reference/api-reference/logs/postLogsToolExecution).
237
238 <Callout type="warning" title="Keep approval on the execution path">
239 This prompt protects only this `session.execute()` call. Keep the spending Session and MCP endpoint private to your executor, and require approval for each exact tool and arguments. Passing `session.tools()` or the MCP endpoint directly to an agent bypasses this gate. Agent instructions are not an enforcement boundary.
240 </Callout>
241
242 ## Limit Session spending
243
244 The Session API does not have a dollar spend-cap parameter. `return_instant_charge` / `returnInstantCharge` reports costs **after** execution; it does not authorize or limit spending. Your prepaid balance is not a hard cap either, because balance checks are asynchronous.
245
246 For a per-Session budget, enforce it in the same application-side executor that asks for approval:
247
248 1. Store the budget and outstanding reservations by Session ID.
249 2. Before each call, reserve a trusted upper bound for that call's cost. Reject the call if it would exceed the remaining budget or you cannot establish a bound. Do not parse the published price description as a guaranteed quote.
250 3. Reserve atomically so concurrent calls cannot spend the same remaining budget. Bind human approval to the tool, arguments, and reserved amount.
251 4. Reconcile the reservation against the actual charge in the execution log. Keep unresolved reservations after a timeout, failure, or missing charge, and check the log before retrying.
252
253 Use exact decimal arithmetic for USD amounts. Reject any call whose maximum cost you cannot bound if you need a strict dollar limit. For the simpler policy “no unapproved paid calls,” use the approval example above. To prevent all Instant spending in a Session, [turn Instant off](#turn-instant-off).
254
255 ## Report charges and use Instant tools
256
257 <Accordions>
258 <Accordion title="Report charges and show prices">
259 ### Return the charge with a call
260
261 Charge reporting is off by default. To include the charge in a `session.execute()` response, set `return_instant_charge` in Python or `returnInstantCharge` in TypeScript:
262
263 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
264 <Tab value="Python">
265 ```python
266 session = composio.sessions.create(
267 user_id="instant_demo",
268 toolkits=["firecrawl"],
269 instant={"return_instant_charge": True},
270 )
271 result = session.execute("FIRECRAWL_SCRAPE", arguments={"url": "https://composio.dev"})
272 if result.instant_charge is not None:
273 print(result.instant_charge.amount, result.instant_charge.currency)
274 ```
275 </Tab>
276 <Tab value="TypeScript">
277 ```typescript
278 import { Composio } from "@composio/core";
279 const composio = new Composio();
280 // ---cut---
281 const session = await composio.create("instant_demo", {
282 toolkits: ["firecrawl"],
283 instant: { returnInstantCharge: true },
284 });
285 const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
286 console.log(result.instantCharge);
287 ```
288 </Tab>
289 <Tab value="API">
290 ```bash
291 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
292 -H "x-api-key: $COMPOSIO_API_KEY" \
293 -H "Content-Type: application/json" \
294 -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_instant_charge": true}}' \
295 | jq -r '.session_id')
296
297 curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
298 -H "x-api-key: $COMPOSIO_API_KEY" \
299 -H "Content-Type: application/json" \
300 -d '{"tool_slug": "FIRECRAWL_SCRAPE", "arguments": {"url": "https://composio.dev"}}' \
301 | jq '.instant_charge'
302 ```
303 </Tab>
304 </Tabs>
305
306 The charge includes `amount`, `currency`, and `charged_by`. The amount is an exact USD decimal string. TypeScript exposes `instantCharge` as `unknown`. Turning charge reporting off does not stop billing or remove charges from logs and usage records.
307
308 ### Show prices in search
309
310 To see what an Instant tool costs before you call it, set `return_prices_in_search` in Python or `returnPricesInSearch` in TypeScript. This option is experimental and off by default. Search results then list each Instant tool's published price under the toolkit's Instant account, keyed by tool slug:
311
312 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
313 <Tab value="Python">
314 ```python
315 session = composio.sessions.create(
316 user_id="instant_demo",
317 toolkits=["firecrawl"],
318 instant={"return_prices_in_search": True},
319 )
320 results = session.search(query="scrape a web page")
321 for status in results.toolkit_connection_statuses:
322 if status.instant_account is not None:
323 print(status.toolkit, status.instant_account.prices)
324 ```
325 </Tab>
326 <Tab value="TypeScript">
327 ```typescript
328 // @noErrors
329 import { Composio } from "@composio/core";
330 const composio = new Composio();
331 // ---cut---
332 const session = await composio.create("instant_demo", {
333 toolkits: ["firecrawl"],
334 instant: { returnPricesInSearch: true },
335 });
336 const results = await session.search({ query: "scrape a web page" });
337 for (const status of results.toolkitConnectionStatuses) {
338 console.log(status.toolkit, status.instantAccount?.prices);
339 }
340 ```
341 </Tab>
342 <Tab value="API">
343 ```bash
344 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
345 -H "x-api-key: $COMPOSIO_API_KEY" \
346 -H "Content-Type: application/json" \
347 -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_prices_in_search": true}}' \
348 | jq -r '.session_id')
349
350 curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/search \
351 -H "x-api-key: $COMPOSIO_API_KEY" \
352 -H "Content-Type: application/json" \
353 -d '{"queries": [{"use_case": "scrape a web page"}]}' \
354 | jq '.toolkit_connection_statuses[] | select(.instant_account != null) | {toolkit, prices: .instant_account.prices}'
355 ```
356 </Tab>
357 </Tabs>
358
359 Each price has a `description` and, when one applies, a `discount`. Like charge reporting, this setting only controls what the response shows. It does not turn Instant usage on or off.
360
361 </Accordion>
362 <Accordion title="Pass Instant tools to your agent">
363
364 If your agent can spend without per-call approval, pass it the Session tools as usual:
365
366 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
367 <Tab value="Python">
368 ```python
369 session = composio.sessions.create(
370 user_id="instant_demo",
371 toolkits=["firecrawl"],
372 )
373 tools = session.tools()
374 ```
375 </Tab>
376 <Tab value="TypeScript">
377 ```typescript
378 import { Composio } from "@composio/core";
379 const composio = new Composio();
380 // ---cut---
381 const session = await composio.create("instant_demo", {
382 toolkits: ["firecrawl"],
383 });
384 const tools = await session.tools();
385 ```
386 </Tab>
387 <Tab value="API">
388 ```bash
389 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
390 -H "x-api-key: $COMPOSIO_API_KEY" \
391 -H "Content-Type: application/json" \
392 -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}}' \
393 | jq -r '.session_id')
394
395 curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
396 -H "x-api-key: $COMPOSIO_API_KEY"
397 ```
398 </Tab>
399 </Tabs>
400
401 Ask your agent: “Read https://composio.dev and summarize what the company offers.” With Instant enabled and no existing Firecrawl connection, it can use a supported tool without asking for a Firecrawl API key.
402
403 Instant works with `session.tools()`, `session.execute()`, and the Session's [MCP endpoint](/docs/sessions-via-mcp). For general filters and agent setup, see [Configuring Sessions](/docs/configuring-sessions) and the [Quickstart](/docs/quickstart).
404
405 </Accordion>
406 </Accordions>
407
408 ## Find supported tools and rates
409
410 Instant support is **per tool**. A toolkit supporting Instant does not mean every tool in that toolkit supports it.
411
412 - [List toolkits](/reference/api-reference/toolkits/getToolkits) and filter `items` by `instant.supported == true`.
413 - [List tools](/reference/api-reference/tools/getTools) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
414 - [Get a tool](/reference/api-reference/tools/getToolsByToolSlug) with `include_pricing=true` to check its support, rate, and input schema before executing it.
415
416 Follow `next_cursor` when listing tools or toolkits, including pages with no Instant matches. Instant metadata is absent for older toolkit versions and ineligible tools. Neither `no_auth` nor `composio_managed_auth_schemes` indicates Instant support.
417
418 You can also change price reporting on an existing Session with `session.update(instant={"return_prices_in_search": True})` in Python or `await session.update({ instant: { returnPricesInSearch: true } })` in TypeScript.
419
420 ## Know which account runs the tool
421
422 Composio uses your user's connection first, then an available shared connection, then an Instant account. Only calls through an Instant account incur an Instant charge. Your provider may separately bill calls made with your own account.
423
424 An explicitly selected account takes priority. A failed connected-account call does not fall back to Instant. Tools that don't support Instant use the normal connection flow.
425
426 Instant uses shared provider accounts, so tools exposing account history or other customers' data are excluded. Arbitrary proxy requests are not supported. Connect your own account for private data or account-specific actions. Inputs still go to the provider; Instant does not imply [zero data retention](/docs/security/zero-data-retention).
427
428 ### Inspect or explicitly select an Instant account
429
430 Session search returns `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript) for a toolkit served by an Instant account. Other tools in that toolkit need your own connection.
431
432 To select Instant explicitly, pass `account="instant_account"` to Python `session.execute()`, or `{ account: "instant_account" }` as TypeScript execution options. On a single-account project, this must match an active connection for the toolkit in the Session. Project policy, Session policy, and tool eligibility still apply. A failed call does not fall back to another account.
433
434 Composio-managed auth is different: Composio supplies the OAuth app credentials, but your user still connects their own account. It does not establish Instant support.
435
436 ## Balance, usage, and troubleshooting
437
438 Instant calls use your organization's prepaid balance, including on Enterprise. Check or add funds in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). If your plan doesn't allow adding funds, upgrade or contact support.
439
440 - **Usage totals:** call the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary). Its top-level `instant_charge` is the total Instant charge as a USD string. An empty request body selects the last 30 days; use `from` and `to` in Unix milliseconds for another window.
441 - **Individual calls:** query the [execution logs API](/reference/api-reference/logs/postLogsToolExecution) with a `session_id` filter. Check `metadata.credential_source` and `metadata.instant_charge`. An absent charge is not proof that the call was free.
442 - **Instant unavailable:** check the project setting, Session restrictions, and the individual tool's eligibility on the latest version.
443 - **Balance exhausted:** Instant calls fail with HTTP 402 (`Metering_WalletBalanceExhausted`) once detected, without falling back to another account. Balance checks are asynchronous, not a strict spending cap. Calls using your own connected account can still run.
444 - **Failed or timed-out call:** check the execution log before retrying. The provider may have completed billable work. Contact [support@composio.dev](mailto:support@composio.dev) with the log ID if the result or charge is unclear.
445
446 <Callout type="info" title="Previous name">
447 Instant Tools were previously called Premium Tools.
448 </Callout>