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: make the Instant Tools first run easier to follow
palash-c committed
Oct 8, 2026 at 15:50 UTC
1c8a4faddd6f541de45c0b33e522fb6c126c2d9b
1 file changed
+83
-29
docs/content/docs/instant-tools.mdx
+83
-29
@@ -7,20 +7,29 @@ experimental: true
7
8
You can build an agent that enriches company records or creates media, but asking every user to sign up for another provider and supply an API key interrupts that workflow. Instant Tools run supported actions on Composio's provider accounts without that setup. Users still connect their own accounts when a task needs their identity or private data.
9
10
+Already using Sessions? Enable Instant for your project below. Your existing `session.tools()` or MCP integration can then use supported tools, subject to its Session restrictions.
11
+
12
## Enable Instant for your project
13
14
Get your `COMPOSIO_API_KEY` from [API keys](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). Use the project's key for the examples below.
15
16
In [project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs&utm_medium=content&utm_campaign=instant-tools), turn on **Instant Toolkits**. Developer projects start with this setting off. A Session cannot override a project where Instant is off.
17
18
+<details>
19
+<summary>Where to enable Instant</summary>
20
+
21
<Figure src="/images/instant-project-setting.jpg" alt="Instant Toolkits toggle in developer project settings, with a note that calls charge the organization's balance" caption="Enable Instant Toolkits for all Sessions in the project." />
22
23
+</details>
24
+
25
Calls through Instant accounts spend your organization's Composio balance. Once enabled, all Sessions in the project can use eligible Instant tools by default, including existing Sessions, even if `instant` is omitted. Session restrictions still apply. Set `instant=False` in Python or `instant: false` in TypeScript for a Session that must not incur Instant usage charges.
26
27
<Callout type="info" title="Experimental access">
28
If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
29
</Callout>
30
31
+Before running the example, check your balance in [Organization Settings → Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). You need available funds for Instant calls. See [funding](#fund-instant-usage) if you need to add funds.
32
+
33
## Build with Session tools
34
35
This uses the [Quickstart's OpenAI Agents integration](/docs/quickstart). Use Python 3.10 or newer, or Node.js 22.22.3 or newer with ESM imports.
@@ -30,11 +39,18 @@ This uses the [Quickstart's OpenAI Agents integration](/docs/quickstart). Use Py
39
<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
40
</Tab>
41
<Tab value="TypeScript">
33
-<PackageInstall packages="dotenv @composio/core @composio/openai-agents @openai/agents" />
42
+<PackageInstall packages="dotenv tsx @composio/core @composio/openai-agents @openai/agents" />
43
</Tab>
44
</Tabs>
45
37
-Set `COMPOSIO_API_KEY` and your model provider's `OPENAI_API_KEY` in `.env`. The model API key is separate from the provider credentials Instant supplies for tools.
46
+Create a `.env` file with your keys:
47
+
48
+```dotenv
49
+COMPOSIO_API_KEY=your_composio_project_key
50
+OPENAI_API_KEY=your_openai_key
51
+```
52
+
53
+The OpenAI key runs the model. Instant supplies the Firecrawl credentials for the tool. Both the model and tool calls can incur charges.
54
55
Use a test user ID without existing Firecrawl connections so a personal connection does not take priority. This example asks the agent to extract public company information without asking the user for a Firecrawl account.
56
@@ -95,25 +111,51 @@ console.log("Session:", session.sessionId);
111
</Tab>
112
</Tabs>
113
98
-Run `python instant_agent.py` or `npx tsx --env-file=.env instant_agent.ts`. The agent should discover a supported Firecrawl tool, read the page, and return a summary without a Connect Link. Inspect the printed Session ID in the [execution logs](#review-usage) and confirm `metadata.credential_source` is `instant_account`. A summary alone does not prove Instant ran the tool.
114
+Run `python instant_agent.py` or `npx tsx --env-file=.env instant_agent.ts`. The agent should discover a supported Firecrawl tool, read the page, and return a company summary without a Connect Link.
115
+
116
+### Check the result and charge
117
+
118
+The example prints the summary and Session ID. To confirm that Instant handled the call, inspect that Session's logs. Look for `metadata.credential_source: "instant_account"` and `metadata.instant_charge` on the provider tool's execution record. A summary alone does not prove Instant ran the tool.
119
+
120
+<details>
121
+<summary>Fetch the execution logs</summary>
122
+
123
+Use the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution). Replace `trs_your_session_id` with your Session ID:
124
+
125
+```bash
126
+curl 'https://backend.composio.dev/api/v3.1/logs/tool_execution' \
127
+ --header "x-api-key: $COMPOSIO_API_KEY" \
128
+ --header 'Content-Type: application/json' \
129
+ --data '{
130
+ "limit": 20,
131
+ "filters": [{"field": "session_id", "operator": "==", "value": "trs_your_session_id"}]
132
+ }'
133
+```
134
+
135
+The response contains `logs` and `next_cursor`. Send `cursor` in the next request to continue. Each log can include `metadata.credential_source` and `metadata.instant_charge`. The source `instant_account` identifies an Instant execution. The charge is an exact USD string, including `"0"` for a recorded zero charge. An absent charge means no charge was recorded, not that the call was free. These records remain available even when `return_instant_charge` is `false`.
136
+
137
+</details>
138
139
`session.tools()` supplies the agent's discovery and execution tools. For another framework, use the matching [provider adapter](/docs/providers). Reuse the Session for later turns as shown in the [Quickstart](/docs/quickstart).
140
141
Top-level `toolkits` controls what the Session can discover and run. Omit it to make all toolkits discoverable. The separate `instant` policy controls Instant usage, as shown under [usage controls](#control-instant-usage).
142
143
+<details>
144
+<summary>Call a tool directly with session.execute()</summary>
145
+
146
### Execute a known tool
147
106
-To call a known tool without an agent, use the Session's `execute` method. These examples use a Session with Exa available:
148
+To call a known tool without an agent, use the Session's `execute` method. These examples read the same public page with Firecrawl:
149
150
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
151
<Tab value="Python">
152
```python
153
session = composio.sessions.create(
154
user_id="instant_demo",
113
- toolkits=["exa"],
155
+ toolkits=["firecrawl"],
156
instant={"return_instant_charge": True},
157
)
116
-result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentation"})
158
+result = session.execute("FIRECRAWL_SCRAPE", arguments={"url": "https://composio.dev"})
159
```
160
</Tab>
161
<Tab value="TypeScript">
@@ -122,16 +164,21 @@ import { Composio } from "@composio/core";
164
const composio = new Composio();
165
// ---cut---
166
const session = await composio.create("instant_demo", {
125
- toolkits: ["exa"],
167
+ toolkits: ["firecrawl"],
168
instant: { returnInstantCharge: true },
169
});
128
-const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
170
+const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
171
```
172
</Tab>
173
</Tabs>
174
175
Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments.
176
177
+</details>
178
+
179
+<details>
180
+<summary>Use an MCP client instead</summary>
181
+
182
### Use MCP
183
184
For an MCP client, create the Session with `mcp=True` in Python or `mcp: true` in TypeScript. Pass both the URL and headers to your client. The same Instant policy applies over MCP.
@@ -141,7 +188,7 @@ For an MCP client, create the Session with `mcp=True` in Python or `mcp: true` i
188
```python
189
session = composio.sessions.create(
190
user_id="user_123",
144
- toolkits=["exa"],
191
+ toolkits=["firecrawl"],
192
instant={"return_instant_charge": True},
193
mcp=True,
194
)
@@ -155,7 +202,7 @@ import { Composio } from "@composio/core";
202
const composio = new Composio();
203
// ---cut---
204
const session = await composio.create("user_123", {
158
- toolkits: ["exa"],
205
+ toolkits: ["firecrawl"],
206
instant: { returnInstantCharge: true },
207
mcp: true,
208
});
@@ -167,6 +214,8 @@ const mcpHeaders = session.mcp.headers;
214
215
Treat `session.mcp.headers` as a secret. See [Using sessions via MCP](/docs/sessions-via-mcp) for client setup and credential scope.
216
217
+</details>
218
+
219
## Find supported tools and rates
220
221
Instant coverage is per tool, not per toolkit. A toolkit badge means at least one tool supports Instant. Use a connected account for actions Instant does not support. See [shared-account restrictions](#shared-account-restrictions-and-privacy).
@@ -177,6 +226,9 @@ In the dashboard, open **Toolkits** and select **Instant Toolkits**. A lightning
226
227
<Figure src="/images/instant-tool-eligibility.jpg" alt="Firecrawl's Instant tools tab lists Map multiple URLs, Scrape URL, and Search separately from its 29 total tools" caption="Open the Instant tools tab to see which tools support an Instant account." />
228
229
+<details>
230
+<summary>Discover supported tools and rates through the APIs</summary>
231
+
232
### List supported toolkits
233
234
Use the [toolkit listing API](/reference/api-reference/toolkits/getToolkits) to fetch a page, then filter its `items` by `instant.supported`. This example uses `jq` to keep eligible toolkits and the pagination cursor:
@@ -216,6 +268,8 @@ Follow `next_cursor` on tool listings as you do for toolkits. Eligible tools inc
268
269
Missing pricing does not mean a tool is free. Check the rate before running it. Instant metadata is absent for older toolkit versions and ineligible tools.
270
271
+</details>
272
+
273
## Control Instant usage
274
275
`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.
@@ -245,6 +299,13 @@ await session.update({ instant: false });
299
</Tab>
300
</Tabs>
301
302
+<Callout type="warning" title="Updating a disabled Session">
303
+ On patch, omitted `instant` fields keep their existing values. But supplying any `instant` object after `instant=false`, even `{ "return_instant_charge": true }`, silently re-enables Instant spending for that Session if the project allows it. Leave `instant` as `false` if the Session must not spend.
304
+</Callout>
305
+
306
+<details>
307
+<summary>Restrict Instant to selected toolkits or tools</summary>
308
+
309
### Restrict toolkits or tools
310
311
Omitted `instant` or `instant={}` permits eligible tools, subject to the project setting and normal Session filters. Omitting `instant.toolkits` does not restrict Instant usage.
@@ -311,13 +372,16 @@ const session = await composio.create("user_123", {
372
</Tab>
373
</Tabs>
374
314
-<Callout type="warning" title="Updating a disabled Session">
315
- On patch, omitted `instant` fields keep their existing values. But supplying any `instant` object after `instant=false`, even `{ "return_instant_charge": true }`, silently re-enables Instant spending for that Session if the project allows it. Leave `instant` as `false` if the Session must not spend.
316
-</Callout>
375
+
376
+
377
+</details>
378
+
379
+<details>
380
+<summary>Read charges from a session.execute() response</summary>
381
382
### Inspect charges
383
320
-With `instant.return_instant_charge` enabled (`instant.returnInstantCharge` in TypeScript), the response from `session.execute()` includes `instant_charge` (`instantCharge` in TypeScript) when an Instant account runs the tool. For the Exa execution example above, read it from the result:
384
+With `instant.return_instant_charge` enabled (`instant.returnInstantCharge` in TypeScript), the response from `session.execute()` includes `instant_charge` (`instantCharge` in TypeScript) when an Instant account runs the tool. For the `session.execute()` example above, read it from the result:
385
386
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
387
<Tab value="Python">
@@ -333,10 +397,10 @@ import { Composio } from "@composio/core";
397
398
const composio = new Composio();
399
const session = await composio.create("user_123", {
336
- toolkits: ["exa"],
400
+ toolkits: ["firecrawl"],
401
instant: { returnInstantCharge: true },
402
});
339
-const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
403
+const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
404
// ---cut---
405
console.log(result.instantCharge ?? "No Instant charge");
406
```
@@ -347,6 +411,8 @@ The charge contains `amount`, `currency`, and `charged_by`. `amount` is an exact
411
412
`return_instant_charge` defaults to `false`. Connected-account calls do not have an Instant charge. Setting `return_instant_charge` to `false` hides the immediate response charge, but does not prevent billing or remove charges from usage records.
413
414
+</details>
415
+
416
## Know which account runs the tool
417
418
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 available through Composio Instant.
@@ -386,19 +452,7 @@ curl 'https://backend.composio.dev/api/v3.1/project/usage/summary' \
452
453
Read the top-level `instant_charge` for the total Instant charge as an exact USD string. The separate `entities` object groups metering usage by entity type, with `unit`, `total_quantity`, and `event_count`. Do not treat all billable usage as Instant charges. To choose a window, supply `from` and `to` in Unix epoch milliseconds. `from` is inclusive and `to` is exclusive.
454
389
-For individual calls, use the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution). Replace `trs_your_session_id` with your Session ID:
390
-
391
-```bash
392
-curl 'https://backend.composio.dev/api/v3.1/logs/tool_execution' \
393
- --header "x-api-key: $COMPOSIO_API_KEY" \
394
- --header 'Content-Type: application/json' \
395
- --data '{
396
- "limit": 20,
397
- "filters": [{"field": "session_id", "operator": "==", "value": "trs_your_session_id"}]
398
- }'
399
-```
400
-
401
-The response contains `logs` and `next_cursor`. Send `cursor` in the next request to continue. Each log can include `metadata.credential_source` and `metadata.instant_charge`. The source `instant_account` identifies an Instant execution. The charge is an exact USD string, including `"0"` for a recorded zero charge. An absent charge means no charge was recorded, not that the call was free. These records remain available even when `return_instant_charge` is `false`.
455
+For individual calls, [inspect the Session's execution logs](#check-the-result-and-charge). These records remain available even when `return_instant_charge` is `false`.
456
457
## Troubleshoot access and charges
458