@devries-cameron20 / composio-1 / commits / d8cff4235
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.

docs(instant): lead with a complete Session workflow

palash-c committed Oct 8, 2026 at 02:06 UTC d8cff4235f8127bfa5c0b1f02120c50a8cd3a102
1 file changed +163 -130
docs/content/docs/instant-tools.mdx
+163 -130
@@ -5,135 +5,114 @@ keywords: [Composio Instant, instant tools, Sessions, Instant usage, Instant acc
5 experimental: true
6 ---
7
8 -Instant Tools give your agent capabilities beyond what your users have connected, including web search, scraping, data enrichment, and image and video generation. Supported tools run on Composio's provider accounts, so your users don't need OAuth, provider API keys, or per-provider signups. Calls through those accounts charge your Composio balance. When a task needs a user's own identity, they can still connect their account.
9 -
10 -Instant Tools were previously called Premium Tools.
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 ## Enable Instant for your project
11
12 +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.
13 +
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**. Developer projects start with this setting off. A Session cannot override a project where Instant is off.
15
16 <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." />
17
18 -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.
18 +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.
19
20 <Callout type="info" title="Experimental access">
21 If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
22 </Callout>
23
24 -## Create a Session
24 +## Build with Session tools
25
26 -After your project is enabled, create a Session. This example makes Exa available and permits Instant usage for its eligible tools:
26 +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.
27
28 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
29 <Tab value="Python">
30 -```python
30 +<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
31 +</Tab>
32 +<Tab value="TypeScript">
33 +<PackageInstall packages="dotenv @composio/core @composio/openai-agents @openai/agents" />
34 +</Tab>
35 +</Tabs>
36 +
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.
38 +
39 +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.
40 +
41 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
42 +<Tab value="Python">
43 +```python title="instant_agent.py"
44 +from dotenv import load_dotenv
45 from composio import Composio
46 +from composio_openai_agents import OpenAIAgentsProvider
47 +from agents import Agent, Runner
48
33 -composio = Composio()
49 +load_dotenv()
50 +composio = Composio(provider=OpenAIAgentsProvider())
51 session = composio.sessions.create(
35 - user_id="user_123",
36 - toolkits=["exa"],
37 - instant={
38 - "toolkits": {"enable": ["exa"]},
39 - "return_instant_charge": True,
40 - },
52 + user_id="instant_demo",
53 + toolkits=["firecrawl"],
54 + instant={"return_instant_charge": True},
55 +)
56 +agent = Agent(
57 + name="Company researcher",
58 + model="gpt-5.2",
59 + instructions="Use an eligible Instant tool to read the page. Do not invent results.",
60 + tools=session.tools(),
61 )
62 +result = Runner.run_sync(
63 + agent,
64 + "Read https://composio.dev and summarize what the company offers.",
65 +)
66 +print(result.final_output)
67 +print("Session:", session.session_id)
68 ```
69 </Tab>
70 <Tab value="TypeScript">
45 -```typescript
71 +```typescript title="instant_agent.ts"
72 +import "dotenv/config";
73 import { Composio } from "@composio/core";
74 +import { OpenAIAgentsProvider } from "@composio/openai-agents";
75 +import { Agent, run } from "@openai/agents";
76
48 -const composio = new Composio();
49 -const session = await composio.create("user_123", {
50 - toolkits: ["exa"],
51 - instant: {
52 - toolkits: { enable: ["exa"] },
53 - returnInstantCharge: true,
54 - },
77 +const composio = new Composio({ provider: new OpenAIAgentsProvider() });
78 +const session = await composio.create("instant_demo", {
79 + toolkits: ["firecrawl"],
80 + instant: { returnInstantCharge: true },
81 +});
82 +const agent = new Agent({
83 + name: "Company researcher",
84 + model: "gpt-5.2",
85 + instructions: "Use an eligible Instant tool to read the page. Do not invent results.",
86 + tools: await session.tools(),
87 });
88 +const result = await run(
89 + agent,
90 + "Read https://composio.dev and summarize what the company offers.",
91 +);
92 +console.log(result.finalOutput);
93 +console.log("Session:", session.sessionId);
94 ```
95 </Tab>
96 </Tabs>
97
60 -Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `instant.toolkits` separately restricts which eligible tools can incur Instant usage charges. Omitting `instant.toolkits` does not restrict Instant usage. Eligible tools remain available when the project and Session permit them. `return_instant_charge` defaults to `false` and only controls whether the actual charge appears in the immediate tool response.
61 -
62 -## Find eligible tools
63 -
64 -Instant coverage is per tool, not per toolkit. A toolkit may support instant tools without every tool in it being eligible. Composio's provider account can be shared across customers, so only reviewed actions can run through it. Actions that could reveal shared account history or send arbitrary proxy requests are excluded. Use a connected account for actions Instant does not support.
65 -
66 -In the dashboard, open **Toolkits** and select **Instant Toolkits**. A lightning icon marks toolkits with Instant support. Open a toolkit's **Instant tools** tab to see its eligible tools.
67 -
68 -<Figure src="/images/instant-toolkit-filter.jpg" alt="Developer toolkit catalog with the Instant Toolkits filter selected and lightning icons beside eligible toolkits" caption="Filter the toolkit catalog to find Instant support." />
69 -
70 -<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." />
71 -
72 -### List supported toolkits
73 -
74 -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:
75 -
76 -```bash
77 -curl --get 'https://backend.composio.dev/api/v3.1/toolkits' \
78 - --header "x-api-key: $COMPOSIO_API_KEY" \
79 - --data-urlencode 'limit=100' \
80 - | jq '{items: [.items[] | select(.instant.supported == true)], next_cursor}'
81 -```
82 -
83 -Fetch subsequent pages with `--data-urlencode "cursor=$NEXT_CURSOR"`, where `NEXT_CURSOR` is the previous response's `next_cursor`. Continue until `next_cursor` is empty or null, even if a page has no matching toolkits. A toolkit's `instant.supported` means at least one tool supports Instant, not every tool.
84 -
85 -Do not infer Instant support from `no_auth` or `composio_managed_auth_schemes`. They describe different access routes.
86 -
87 -### Check tool eligibility and rates
88 -
89 -Request `include_pricing=true` when [listing tools](/reference/api-reference/tools/getTools) or [reading a tool](/reference/api-reference/tools/getToolsByToolSlug). Select the latest toolkit version to receive Instant metadata:
90 -
91 -```bash
92 -curl --get 'https://backend.composio.dev/api/v3.1/tools' \
93 - --header "x-api-key: $COMPOSIO_API_KEY" \
94 - --data-urlencode 'toolkit_slug=exa' \
95 - --data-urlencode 'toolkit_versions=latest' \
96 - --data-urlencode 'include_pricing=true' \
97 - --data-urlencode 'limit=100' \
98 - | jq '{items: [.items[] | select(.instant.supported == true) | {slug, instant}], next_cursor}'
99 -
100 -curl --get 'https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH' \
101 - --header "x-api-key: $COMPOSIO_API_KEY" \
102 - --data-urlencode 'toolkit_versions=latest' \
103 - --data-urlencode 'include_pricing=true' \
104 - | jq '{slug, instant, input_parameters}'
105 -```
106 -
107 -Follow `next_cursor` on tool listings as you do for toolkits. Eligible tools include `instant.supported: true`. When published pricing is available, `instant.price.description` contains the human-readable rate and `instant.price.discount` contains the discount. Both values are strings when present, and `discount` can be null. Do not treat them as numeric prices or infer an expiry date. Discounts may change.
108 -
109 -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.
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.
99
111 -## Use Session tools
100 +`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).
101
113 -Pass `session.tools()` to your agent as in the [Quickstart](/docs/quickstart), so it can discover and run eligible tools. The examples below continue from the Session above.
102 +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).
103
115 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
116 -<Tab value="Python">
117 -```python
118 -tools = session.tools()
119 -```
120 -</Tab>
121 -<Tab value="TypeScript">
122 -```typescript
123 -import { Composio } from "@composio/core";
124 -const composio = new Composio();
125 -const session = await composio.create("user_123", { toolkits: ["exa"], instant: { returnInstantCharge: true } });
126 -// ---cut---
127 -const tools = await session.tools();
128 -```
129 -</Tab>
130 -</Tabs>
104 +### Execute a known tool
105
132 -To run a known tool yourself, use the Session's `execute` method:
106 +To call a known tool without an agent, use the Session's `execute` method. These examples use a Session with Exa available:
107
108 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
109 <Tab value="Python">
110 ```python
111 +session = composio.sessions.create(
112 + user_id="instant_demo",
113 + toolkits=["exa"],
114 + instant={"return_instant_charge": True},
115 +)
116 result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentation"})
117 ```
118 </Tab>
@@ -141,8 +120,11 @@ result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentati
120 ```typescript
121 import { Composio } from "@composio/core";
122 const composio = new Composio();
144 -const session = await composio.create("user_123", { toolkits: ["exa"], instant: { returnInstantCharge: true } });
123 // ---cut---
124 +const session = await composio.create("instant_demo", {
125 + toolkits: ["exa"],
126 + instant: { returnInstantCharge: true },
127 +});
128 const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
129 ```
130 </Tab>
@@ -185,53 +167,87 @@ const mcpHeaders = session.mcp.headers;
167
168 Treat `session.mcp.headers` as a secret. See [Using sessions via MCP](/docs/sessions-via-mcp) for client setup and credential scope.
169
188 -### Read charge details
170 +## Find supported tools and rates
171 +
172 +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).
173
190 -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. Read it from the result above:
174 +In the dashboard, open **Toolkits** and select **Instant Toolkits**. A lightning icon marks toolkits with Instant support. Open a toolkit's **Instant tools** tab to see its eligible tools.
175 +
176 +<Figure src="/images/instant-toolkit-filter.jpg" alt="Developer toolkit catalog with the Instant Toolkits filter selected and lightning icons beside eligible toolkits" caption="Filter the toolkit catalog to find Instant support." />
177 +
178 +<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." />
179 +
180 +### List supported toolkits
181 +
182 +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:
183 +
184 +```bash
185 +curl --get 'https://backend.composio.dev/api/v3.1/toolkits' \
186 + --header "x-api-key: $COMPOSIO_API_KEY" \
187 + --data-urlencode 'limit=100' \
188 + | jq '{items: [.items[] | select(.instant.supported == true)], next_cursor}'
189 +```
190 +
191 +Fetch subsequent pages with `--data-urlencode "cursor=$NEXT_CURSOR"`, where `NEXT_CURSOR` is the previous response's `next_cursor`. Continue until `next_cursor` is empty or null, even if a page has no matching toolkits. A toolkit's `instant.supported` means at least one tool supports Instant, not every tool.
192 +
193 +Do not infer Instant support from `no_auth` or `composio_managed_auth_schemes`. They describe different access routes.
194 +
195 +### Check tool eligibility and rates
196 +
197 +Request `include_pricing=true` when [listing tools](/reference/api-reference/tools/getTools) or [reading a tool](/reference/api-reference/tools/getToolsByToolSlug). Select the latest toolkit version to receive Instant metadata:
198 +
199 +```bash
200 +curl --get 'https://backend.composio.dev/api/v3.1/tools' \
201 + --header "x-api-key: $COMPOSIO_API_KEY" \
202 + --data-urlencode 'toolkit_slug=exa' \
203 + --data-urlencode 'toolkit_versions=latest' \
204 + --data-urlencode 'include_pricing=true' \
205 + --data-urlencode 'limit=100' \
206 + | jq '{items: [.items[] | select(.instant.supported == true) | {slug, instant}], next_cursor}'
207 +
208 +curl --get 'https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH' \
209 + --header "x-api-key: $COMPOSIO_API_KEY" \
210 + --data-urlencode 'toolkit_versions=latest' \
211 + --data-urlencode 'include_pricing=true' \
212 + | jq '{slug, instant, input_parameters}'
213 +```
214 +
215 +Follow `next_cursor` on tool listings as you do for toolkits. Eligible tools include `instant.supported: true`. When published pricing is available, `instant.price.description` contains the human-readable rate and `instant.price.discount` contains the discount. Both values are strings when present, and `discount` can be null. Do not treat them as numeric prices or infer an expiry date. Discounts may change.
216 +
217 +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.
218 +
219 +## Control Instant usage
220 +
221 +`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.
222 +
223 +The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable Instant usage for other eligible toolkits. Use `instant.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
224 +
225 +### Disable Instant usage
226 +
227 +Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session to prevent Instant charges. Your own connected-account routes remain available.
228 +
229 +To stop Instant usage on an existing Session, update its policy:
230
231 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
232 <Tab value="Python">
233 ```python
195 -charge = result.instant_charge
196 -if charge is not None:
197 - print(charge["amount"], charge["currency"], charge["charged_by"])
234 +session.update(instant=False)
235 ```
236 </Tab>
237 <Tab value="TypeScript">
238 ```typescript
239 import { Composio } from "@composio/core";
203 -
240 const composio = new Composio();
205 -const session = await composio.create("user_123", {
206 - toolkits: ["exa"],
207 - instant: { returnInstantCharge: true },
208 -});
209 -const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
241 +const session = await composio.create("user_123");
242 // ---cut---
211 -console.log(result.instantCharge ?? "No Instant charge");
243 +await session.update({ instant: false });
244 ```
245 </Tab>
246 </Tabs>
247
216 -The charge contains `amount`, `currency`, and `charged_by`. `amount` is an exact USD decimal string. Python exports `InstantCharge` from `composio.types`. TypeScript exposes `instantCharge` as `unknown`.
217 -
218 -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.
219 -
220 -## Control Instant usage
221 -
222 -`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.
223 -
224 -The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable Instant usage for other eligible toolkits. Use `instant.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
248 +### Restrict toolkits or tools
249
226 -The examples below use Python and REST field names. In TypeScript, use `instant` and `returnInstantCharge`, and read the charge from `instantCharge` on the tool result.
227 -
228 -| Session value | Effect |
229 -|---|---|
230 -| Omitted or `{}` | Permits Instant usage for eligible tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
231 -| `false` | Disables Instant usage for that Session. Your own connected-account routes remain available. |
232 -| `{ "toolkits": { "enable": ["exa"] } }` | Permits Instant usage only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
233 -| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows Instant usage to selected tools within a toolkit. |
234 -| `{ "return_instant_charge": true }` | Requests the actual `instant_charge` in an eligible Session tool response. On create, this changes charge visibility, not permission to spend. On update, it also re-enables Instant usage on a Session set to `false`, like any other object. |
250 +Omitted `instant` or `instant={}` permits eligible tools, subject to the project setting and normal Session filters. Omitting `instant.toolkits` does not restrict Instant usage.
251
252 For example, keep Exa and Firecrawl available, but permit Instant usage only for `EXA_SEARCH`:
253
@@ -295,28 +311,41 @@ const session = await composio.create("user_123", {
311 </Tab>
312 </Tabs>
313
298 -To stop Instant usage on an existing Session, update its policy:
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>
317 +
318 +### Inspect charges
319 +
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:
321
322 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
323 <Tab value="Python">
324 ```python
303 -session.update(instant=False)
325 +charge = result.instant_charge
326 +if charge is not None:
327 + print(charge["amount"], charge["currency"], charge["charged_by"])
328 ```
329 </Tab>
330 <Tab value="TypeScript">
331 ```typescript
332 import { Composio } from "@composio/core";
333 +
334 const composio = new Composio();
310 -const session = await composio.create("user_123");
335 +const session = await composio.create("user_123", {
336 + toolkits: ["exa"],
337 + instant: { returnInstantCharge: true },
338 +});
339 +const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
340 // ---cut---
312 -await session.update({ instant: false });
341 +console.log(result.instantCharge ?? "No Instant charge");
342 ```
343 </Tab>
344 </Tabs>
345
317 -<Callout type="warning" title="Updating a disabled Session">
318 - 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.
319 -</Callout>
346 +The charge contains `amount`, `currency`, and `charged_by`. `amount` is an exact USD decimal string. Python exports `InstantCharge` from `composio.types`. TypeScript exposes `instantCharge` as `unknown`.
347 +
348 +`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.
349
350 ## Know which account runs the tool
351
@@ -328,7 +357,7 @@ Without an explicit account selection, Composio prefers the user's own connectio
357
358 Session search tells you when an Instant account serves a toolkit. The toolkit's connection status includes `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript), which lists the tools that run on it. Any other tool in that toolkit needs the user's own connection.
359
331 -To choose the Instant account explicitly, pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. The project and Session must permit Instant, and the tool must support it. This route does not fall back to another credential if it fails.
360 +If your project has multi-account selection enabled, you can choose the Instant account explicitly. Pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. The project and Session must permit Instant, and the tool must support it. This route does not fall back to another credential if it fails.
361
362 ### Shared-account restrictions and privacy
363
@@ -380,3 +409,7 @@ The response contains `logs` and `next_cursor`. Send `cursor` in the next reques
409 - Before retrying a failed or timed-out call, check its execution log. A provider may have completed billable work even if your client did not receive the result. Contact [support@composio.dev](mailto:support@composio.dev) with the log ID if the result or charge is unclear.
410
411 See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/api-reference/tool-router/postToolRouterSession) for the complete request schema.
412 +
413 +<Callout type="info" title="Previous name">
414 + Instant Tools were previously called Premium Tools.
415 +</Callout>