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: explain Instant controls before spending limits
Brendan O'Leary [zen] committed
Oct 16, 2026 at 13:46 UTC
28cc0c48b73d997cf3eef9f6c2ae0ed9f48d675c
1 file changed
+68
-66
docs/content/docs/instant-tools.mdx
+68
-66
@@ -7,6 +7,7 @@ experimental: true
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
@@ -23,6 +24,72 @@ Once enabled, eligible tools can use Instant in new and existing Sessions unless
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']} 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
+</Tabs>
63
+
64
+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.
65
+
66
+Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.
67
+
68
+### Turn Instant off
69
+
70
+Your own connected accounts remain available when you disable Instant:
71
+
72
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
73
+<Tab value="Python">
74
+```python
75
+session.update(instant=False)
76
+```
77
+</Tab>
78
+<Tab value="TypeScript">
79
+```typescript
80
+import { Composio } from "@composio/core";
81
+const composio = new Composio();
82
+const session = await composio.create("user_123");
83
+// ---cut---
84
+await session.update({ instant: false });
85
+```
86
+</Tab>
87
+</Tabs>
88
+
89
+<Callout type="warning" title="Updating a disabled Session">
90
+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.
91
+</Callout>
92
+
93
## Approve a tool call before spending
94
95
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:
@@ -114,74 +181,9 @@ For a per-Session budget, enforce it in the same application-side executor that
181
182
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).
183
117
-## Control Instant usage
118
-
119
-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.
120
-
121
-### Turn Instant off
122
-
123
-Your own connected accounts remain available when you disable Instant:
124
-
125
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
126
-<Tab value="Python">
127
-```python
128
-session.update(instant=False)
129
-```
130
-</Tab>
131
-<Tab value="TypeScript">
132
-```typescript
133
-import { Composio } from "@composio/core";
134
-const composio = new Composio();
135
-const session = await composio.create("user_123");
136
-// ---cut---
137
-await session.update({ instant: false });
138
-```
139
-</Tab>
140
-</Tabs>
141
-
142
-<Callout type="warning" title="Updating a disabled Session">
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>
184
+## Report charges and use Instant tools
185
186
<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
-
151
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
152
-<Tab value="Python">
153
-```python
154
-session = composio.sessions.create(
155
- user_id="user_123",
156
- toolkits=["exa", "firecrawl"],
157
- instant={
158
- "toolkits": {"enable": ["exa"]},
159
- "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
160
- },
161
-)
162
-```
163
-</Tab>
164
-<Tab value="TypeScript">
165
-```typescript
166
-import { Composio } from "@composio/core";
167
-const composio = new Composio();
168
-// ---cut---
169
-const session = await composio.create("user_123", {
170
- toolkits: ["exa", "firecrawl"],
171
- instant: {
172
- toolkits: { enable: ["exa"] },
173
- tools: { exa: { enable: ["EXA_SEARCH"] } },
174
- },
175
-});
176
-```
177
-</Tab>
178
-</Tabs>
179
-
180
-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.
181
-
182
-Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.
183
-
184
-</Accordion>
187
<Accordion title="Report charges and show prices">
188
### Return the charge with a call
189