5
experimental: true
6
---
7
8
-Adding enrichment, scraping, or media creation to your agent shouldn't mean asking every user to sign up for another provider, manage an API key, or buy a separate subscription. Instant tools run supported actions on Composio's provider accounts and charge your organization's Composio balance. Your users still connect their own accounts when a task needs their identity or private data.
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
-Instant works through [Sessions](/docs/how-composio-works). New to Composio? Follow the [Quickstart](/docs/quickstart) for SDK and agent setup, then return here.
10
+- **Want approval before spending?** Keep execution in your application and [ask before each call](#approve-a-tool-call-before-spending).
11
+- **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.
12
+
13
+New to Composio? Follow the [Quickstart](/docs/quickstart) for SDK installation and set `COMPOSIO_API_KEY` before running the examples.
14
15
## Enable Instant
16
14
-In [project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs&utm_medium=content&utm_campaign=instant-tools), turn on **Instant Toolkits**. Check that your organization has an available balance in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools) before running a tool.
17
+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.
18
+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).
19
16
-- **Project default:** off. A Session cannot override a project where Instant is off.
17
-- **Once enabled:** eligible tools can use Instant in all Sessions, including existing Sessions. Existing Session restrictions still apply.
18
-- **Session default:** omitting `instant` permits Instant usage. Set `instant=False` in Python or `instant: false` in TypeScript to prevent Instant charges for that Session.
20
+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.
21
22
<Callout type="info" title="Experimental access">
23
If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
24
</Callout>
25
24
-## Use Instant in your agent
26
+## Approve a tool call before spending
27
+
28
+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:
29
+
30
+```bash
31
+curl --get 'https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE' \
32
+ --header "x-api-key: $COMPOSIO_API_KEY" \
33
+ --data-urlencode 'toolkit_versions=latest' \
34
+ --data-urlencode 'include_pricing=true' \
35
+ | jq '{slug, instant, input_parameters}'
36
+```
37
+
38
+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.
39
26
-Keep your existing Composio client and agent integration. For example, create a Session with Firecrawl available and pass its tools to your agent as usual:
40
+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.
41
42
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
43
<Tab value="Python">
44
```python
45
+import json
46
+from composio import Composio
47
+
48
+tool = "FIRECRAWL_SCRAPE"
49
+arguments = {"url": "https://composio.dev"}
50
+
51
+print(tool, json.dumps(arguments))
52
+if input("Approve this call at the published rate? Type yes: ").strip().lower() != "yes":
53
+ raise SystemExit("Not approved. No tool call made.")
54
+
55
+composio = Composio()
56
session = composio.sessions.create(
57
user_id="instant_demo",
58
toolkits=["firecrawl"],
59
+ instant={"return_instant_charge": True},
60
)
35
-tools = session.tools()
61
+result = session.execute(tool, arguments=arguments, account="instant_account")
62
+print(result)
63
+print("Instant charge:", result.instant_charge)
64
```
65
</Tab>
66
<Tab value="TypeScript">
67
```typescript
68
+import { createInterface } from "node:readline/promises";
69
import { Composio } from "@composio/core";
70
+
71
+const tool = "FIRECRAWL_SCRAPE";
72
+const args = { url: "https://composio.dev" };
73
+const prompt = createInterface({ input: process.stdin, output: process.stdout });
74
+
75
+console.log(tool, JSON.stringify(args));
76
+let answer: string;
77
+try {
78
+ answer = await prompt.question("Approve this call at the published rate? Type yes: ");
79
+} finally {
80
+ prompt.close();
81
+}
82
+if (answer.trim().toLowerCase() !== "yes") {
83
+ throw new Error("Not approved. No tool call made.");
84
+}
85
+
86
const composio = new Composio();
42
-// ---cut---
87
const session = await composio.create("instant_demo", {
88
toolkits: ["firecrawl"],
89
+ instant: { returnInstantCharge: true },
90
});
46
-const tools = await session.tools();
91
+const result = await session.execute(tool, args, { account: "instant_account" });
92
+console.log(result);
93
+console.log("Instant charge:", result.instantCharge);
94
```
95
</Tab>
96
</Tabs>
97
51
-Ask your agent: “Read https://composio.dev and summarize what the company offers.” With Instant enabled and no existing Firecrawl connection, the agent can use a supported tool without asking you for a Firecrawl API key.
98
+`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).
99
53
-You don't need a separate Instant execution method. It works with `session.tools()`, `session.execute()`, and the Session's [MCP endpoint](/docs/sessions-via-mcp). For general toolkit filters and agent setup, see [Configuring Sessions](/docs/configuring-sessions) and the [Quickstart](/docs/quickstart).
100
+<Callout type="warning" title="Keep approval on the execution path">
101
+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.
102
+</Callout>
103
55
-To verify the call, find the Session's tool execution in the [logs API](/reference/api-reference/logs/postLogsToolExecution). `metadata.credential_source` should be `instant_account`; `metadata.instant_charge` records the charge. An agent's summary alone doesn't prove the tool ran through Instant.
104
+## Limit Session spending
105
57
-## Find supported tools and rates
106
+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.
107
59
-Instant support is **per tool**. A toolkit supporting Instant does not mean every tool in that toolkit supports it.
108
+For a per-Session budget, enforce it in the same application-side executor that asks for approval:
109
61
-- [List toolkits](/reference/api-reference/toolkits/getToolkits) and filter `items` by `instant.supported == true` to find toolkits with Instant tools.
62
-- [List tools](/reference/api-reference/tools/getTools) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
63
-- [Get a tool](/reference/api-reference/tools/getToolsByToolSlug) with `include_pricing=true` to check its support, rate, and input schema before executing it.
110
+1. Store the budget and outstanding reservations by Session ID.
111
+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.
112
+3. Reserve atomically so concurrent calls cannot spend the same remaining budget. Bind human approval to the tool, arguments, and reserved amount.
113
+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.
114
65
-For example, check Firecrawl's scrape tool:
66
-
67
-```bash
68
-curl --get 'https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE' \
69
- --header "x-api-key: $COMPOSIO_API_KEY" \
70
- --data-urlencode 'toolkit_versions=latest' \
71
- --data-urlencode 'include_pricing=true' \
72
- | jq '{slug, instant, input_parameters}'
73
-```
74
-
75
-Read the rate from `instant.price.description` and any discount from `instant.price.discount`. Both are strings when present; `discount` can be null. Missing pricing does not mean the tool is free.
76
-
77
-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.
115
+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).
116
117
## Control Instant usage
118
143
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.
144
</Callout>
145
108
-### Allow or exclude specific toolkits and tools
146
+<Accordions>
147
+<Accordion title="Allow or exclude specific toolkits and tools">
148
149
Keep Exa and Firecrawl available, but allow Instant only for `EXA_SEARCH`:
150
181
182
Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.
183
184
+</Accordion>
185
+<Accordion title="Report charges and show prices">
186
### Return the charge with a call
187
188
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:
255
256
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.
257
258
+</Accordion>
259
+<Accordion title="Pass Instant tools to your agent">
260
+
261
+If your agent can spend without per-call approval, pass it the Session tools as usual:
262
+
263
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
264
+<Tab value="Python">
265
+```python
266
+session = composio.sessions.create(
267
+ user_id="instant_demo",
268
+ toolkits=["firecrawl"],
269
+)
270
+tools = session.tools()
271
+```
272
+</Tab>
273
+<Tab value="TypeScript">
274
+```typescript
275
+import { Composio } from "@composio/core";
276
+const composio = new Composio();
277
+// ---cut---
278
+const session = await composio.create("instant_demo", {
279
+ toolkits: ["firecrawl"],
280
+});
281
+const tools = await session.tools();
282
+```
283
+</Tab>
284
+</Tabs>
285
+
286
+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.
287
+
288
+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).
289
+
290
+</Accordion>
291
+</Accordions>
292
+
293
+## Find supported tools and rates
294
+
295
+Instant support is **per tool**. A toolkit supporting Instant does not mean every tool in that toolkit supports it.
296
+
297
+- [List toolkits](/reference/api-reference/toolkits/getToolkits) and filter `items` by `instant.supported == true`.
298
+- [List tools](/reference/api-reference/tools/getTools) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
299
+- [Get a tool](/reference/api-reference/tools/getToolsByToolSlug) with `include_pricing=true` to check its support, rate, and input schema before executing it.
300
+
301
+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.
302
+
303
## Know which account runs the tool
304
305
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.