@devries-cameron20 / composio-1 / commits / 122fabe56
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: explain Instant costs and show runnable agent search

Palash Kala committed Sep 29, 2026 at 23:51 UTC 122fabe56911aba6c0926b6f0c18113eb87267db
1 file changed +50 -6
docs/content/docs/instant-tools.mdx
+50 -6
@@ -5,14 +5,18 @@ keywords: [Instant Tools, Sessions, Instant usage, Instant account]
5 experimental: true
6 ---
7
8 -Adding a capability to your agent can mean another provider account, API key, and bill or subscription. Instant Tools let your Session use supported actions without that setup. Composio supplies access and charges usage to your organization's available balance. Your users can still connect their own accounts when a task needs their provider identity.
8 +Instant Tools give your agent capabilities such as web search, scraping, and data enrichment, with more added regularly. Your users don't need to connect anything. Tools run on Composio's provider accounts, so there is no provider OAuth flow, API key, or signup. 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 <Callout type="warning" title="Experimental access">
11 - Turn on Instant in Dashboard → Project Settings. This sets `enable_instant: true` for your project. If the setting is unavailable during experimental access, email [support@composio.dev](mailto:support@composio.dev). A Session cannot override a project where Instant is off.
11 + Email [support@composio.dev](mailto:support@composio.dev) to enable Instant for your project during experimental access. A Session cannot override a project where Instant is off.
12 </Callout>
13
14 Once the project setting is enabled, new Sessions can use eligible Instant Tools by default, even if `instant` is omitted. Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session that must not incur Instant usage charges.
15
16 +## Balance and failed calls
17 +
18 +Developer organizations get a one-time $2 starter credit. Check your balance in [Dashboard → Organization Settings → Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). On Pro, add prepaid funds there; Hobby organizations must upgrade to Pro before adding funds. When Composio confirms that the balance is exhausted, an Instant call fails with HTTP 402 (`Metering_WalletBalanceExhausted`). It does not fall back to another account. Calls that select a user's connected account can still run. Balance verification is asynchronous, so $0 is not a strict per-call spending cap.
19 +
20 ## Find eligible tools
21
22 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.
@@ -58,7 +62,30 @@ const session = await composio.create("user_123", {
62
63 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 it leaves eligible tools 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. A toolkit that supports Instant can still contain tools that need a connected account.
64
61 -## Find and run a tool
65 +## Run a search with an agent
66 +
67 +Install `composio` and `openai-agents`, then set `COMPOSIO_API_KEY` and `OPENAI_API_KEY` as in the [Quickstart](/docs/quickstart). This small agent can choose when to search. The wrapper prints the Instant charge after each search call:
68 +
69 +```python
70 +from agents import Agent, Runner, function_tool
71 +from composio import Composio
72 +
73 +session = Composio().sessions.create(user_id="user_123", toolkits=["exa"], instant={"return_instant_charge": True})
74 +
75 +@function_tool
76 +def search(query: str) -> str:
77 + result = session.execute("EXA_SEARCH", arguments={"query": query})
78 + print("Instant charge:", result.instant_charge or "none")
79 + return str(result.data)
80 +
81 +agent = Agent(name="Researcher", instructions="Use search when you need current information.", tools=[search])
82 +while prompt := input("You: "):
83 + print(Runner.run_sync(agent, prompt).final_output)
84 +```
85 +
86 +The charge is present only if an Instant account served the call. A connected-account call prints `none`. Check the [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) if you change tools or arguments.
87 +
88 +## Find and run other tools
89
90 Pass `session.tools()` to your agent as in the [Quickstart](/docs/quickstart), so it can discover and run eligible tools. If your agent uses MCP, expose the same Session through `session.mcp` as described in [Using sessions via MCP](/docs/sessions-via-mcp). The Instant usage policy applies to that Session in either path; your agent does not need a separate Instant usage setting.
91
@@ -100,7 +127,7 @@ const result = await session.execute("EXA_SEARCH", { query: "Composio documentat
127
128 Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments. A tool appearing in a toolkit does not mean Instant account access is available for that tool. Confirm supported tools and rates during Experimental access.
129
103 -### Read charge details in Python
130 +### Read charge details
131
132 With `instant.return_instant_charge` enabled, `session.execute()` returns charge details when available in the typed `instant_charge` field on `ToolRouterSessionExecuteResponse`. Read it from the result above:
133
@@ -112,6 +139,21 @@ if charge is not None:
139
140 The `InstantCharge` type is exported from `composio.types` and includes `amount`, `currency`, and `charged_by`. Python provider integrations and mixed local/remote multi-tool execution also preserve these charge details.
141
142 +In TypeScript, read `instantCharge` from the result:
143 +
144 +```typescript
145 +// @noErrors
146 +import { Composio } from "@composio/core";
147 +
148 +const composio = new Composio();
149 +const session = await composio.create("user_123", {
150 + toolkits: ["exa"],
151 + instant: { returnInstantCharge: true },
152 +});
153 +const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
154 +console.log(result.instantCharge ?? "No Instant charge");
155 +```
156 +
157 ## Control Instant usage
158
159 `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.
@@ -173,13 +215,15 @@ await session.update({ instant: false });
215 </Tab>
216 </Tabs>
217
176 -On patch, omitted `instant` fields keep their existing values. Supplying any object after `false`, even one that only sets `return_instant_charge`, enables this Session policy again, provided the project allows it.
218 +<Callout type="warning" title="Updating a disabled Session">
219 + 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.
220 +</Callout>
221
222 ## Know which account runs the tool
223
224 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 Instant.
225
182 -If you select a connected account explicitly, that route wins and does not fall back to the Instant account on failure. Otherwise, available user or shared connections take priority over an Instant account. If the chosen tool is not supported by an Instant account, it follows the normal connection flow.
226 +You pay an Instant charge only when Composio's Instant account runs the tool. A call using the user's own connection has no Composio Instant charge; the provider may bill that user under their own plan. If you select a connected account explicitly, that route wins and does not fall back to the Instant account on failure. Otherwise, available user or shared connections take priority over an Instant account. If the chosen tool is not supported by an Instant account, it follows the normal connection flow.
227
228 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.
229