@devries-cameron20 / composio Mirror · read-only / commits / 28cc0c48b
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, 08:30 UTC

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