@devries-cameron20 / composio-1 / commits / 71abc8e7a
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: use hosted-account terminology and SDK workflows

Palash Kala committed Sep 23, 2026 at 17:50 UTC 71abc8e7ab50420ebadadf1974f30f6bff4152e0
1 file changed +112 -66
docs/content/docs/instant-tools.mdx
+112 -66
@@ -1,110 +1,156 @@
1 ---
2 title: Instant Tools (Experimental)
3 description: Use supported tools in a Session without asking every user to connect a provider account
4 -keywords: [Instant Tools, Sessions, premium usage, Composio-managed account]
4 +keywords: [Instant Tools, Sessions, premium usage, hosted account]
5 ---
6
7 -Instant Tools let your Session run supported tools without an end-user provider connection. For these tools, a Composio-managed account supplies the provider access and eligible calls incur a `premium_usage` charge against your organization's Composio balance.
7 +Instant Tools let your Session run supported tools without an end-user provider connection. A Composio hosted account provides access for eligible tools. Premium usage charges for those calls come from your organization's available balance.
8
9 <Callout type="warning" title="Experimental access">
10 This feature requires a project setting that is not yet self-service. Email [support@composio.dev](mailto:support@composio.dev) to enable it for your project and confirm which tools and rates are available. Session configuration cannot override a project where the setting is off.
11 </Callout>
12
13 -Once the project setting is enabled, new Sessions can use eligible billed tools by default, even if `premium_usage` is omitted. Send `"premium_usage": false` on Session creation if that Session must not use Composio-billed access.
13 +Once the project setting is enabled, new Sessions can use eligible Instant Tools by default, even if `premium_usage` is omitted. Set `premium_usage=False` in Python or `premiumUsage: false` in TypeScript when creating a Session that must not incur premium usage charges.
14
15 ## Create a Session
16
17 -After your project is enabled, create a Session with an explicit `premium_usage` policy. This example makes Exa available to the Session and permits Composio-billed access for Exa:
18 -
19 -```bash
20 -curl --request POST \
21 - --url https://backend.composio.dev/api/v3.1/tool_router/session \
22 - --header "x-api-key: $COMPOSIO_API_KEY" \
23 - --header "content-type: application/json" \
24 - --data '{
25 - "user_id": "user_123",
26 - "toolkits": { "enable": ["exa"] },
27 - "premium_usage": {
28 - "toolkits": { "enable": ["exa"] },
29 - "return_premium_charge": true
30 - }
31 - }'
17 +After your project is enabled, create a Session. This example makes Exa available and permits premium usage for its eligible tools:
18 +
19 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20 +<Tab value="Python">
21 +```python
22 +from composio import Composio
23 +
24 +composio = Composio()
25 +session = composio.sessions.create(
26 + user_id="user_123",
27 + toolkits=["exa"],
28 + premium_usage={
29 + "toolkits": {"enable": ["exa"]},
30 + "return_premium_charge": True,
31 + },
32 +)
33 ```
34 +</Tab>
35 +<Tab value="TypeScript">
36 +```typescript
37 +import { Composio } from "@composio/core";
38 +
39 +const composio = new Composio();
40 +const session = await composio.create("user_123", {
41 + toolkits: ["exa"],
42 + premiumUsage: {
43 + toolkits: { enable: ["exa"] },
44 + returnPremiumCharge: true,
45 + },
46 +});
47 +```
48 +</Tab>
49 +</Tabs>
50
34 -The response includes a `session_id` and the effective `config`. Use the `session_id` for Session-scoped tool search and execution.
35 -
36 -The two toolkit lists control different things. Top-level `toolkits` controls which tools the Session can discover and run. `premium_usage.toolkits` controls which of those toolkits can use a Composio-billed route. A toolkit must pass *both* filters. An eligible toolkit can still contain tools that require a connected account.
51 +Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `premium_usage.toolkits` (or `premiumUsage.toolkits` in TypeScript) separately restricts which eligible tools can incur premium usage charges. Omit that filter to permit all eligible toolkits. An Instant toolkit can still contain tools that need a connected account; hosted account coverage is tool-specific.
52
53 ## Find and run a tool
54
40 -You can inspect a tool's input schema with the [get tool endpoint](/reference/api-reference/tools/getToolsByToolSlug). For example:
55 +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 premium usage policy applies to that Session in either path; your agent does not need a separate premium usage setting.
56
42 -```bash
43 -curl --request GET \
44 - --url https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH \
45 - --header "x-api-key: $COMPOSIO_API_KEY"
57 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
58 +<Tab value="Python">
59 +```python
60 +tools = session.tools() # Pass these to your agent framework.
61 ```
62 +</Tab>
63 +<Tab value="TypeScript">
64 +```typescript
65 +const tools = await session.tools(); // Pass these to your agent framework.
66 +```
67 +</Tab>
68 +</Tabs>
69 +
70 +To run a known tool yourself, use the Session's `execute` method:
71
48 -Then execute a tool through the Session using the [Session execute endpoint](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute):
49 -
50 -```bash
51 -curl --request POST \
52 - --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute" \
53 - --header "x-api-key: $COMPOSIO_API_KEY" \
54 - --header "content-type: application/json" \
55 - --data '{
56 - "tool_slug": "EXA_SEARCH",
57 - "arguments": { "query": "Composio documentation" }
58 - }'
72 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
73 +<Tab value="Python">
74 +```python
75 +result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentation"})
76 ```
77 +</Tab>
78 +<Tab value="TypeScript">
79 +```typescript
80 +const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
81 +```
82 +</Tab>
83 +</Tabs>
84 +
85 +Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments. A tool appearing in a toolkit does not mean hosted account access is available for that tool. Confirm supported tools and rates during Experimental access.
86
61 -Check the current tool schema before constructing `arguments`; fields can change with the tool version. The current tools API does *not* provide a structured Instant eligibility or price field. A tool appearing in a toolkit does not mean Composio-billed access is available for that tool. Confirm the supported tool list and rates during Experimental access.
87 +## Control premium usage
88
63 -## Control billed access
89 +`premium_usage` is a Session policy (`premiumUsage` in TypeScript). It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
90
65 -`premium_usage` is a Session policy. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
91 +The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable premium usage for other eligible toolkits. Use `premium_usage.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
92
67 -The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable billed access for other eligible toolkits. Use `premium_usage.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
93 +The examples below use Python and REST field names. In TypeScript, use `premiumUsage` and `returnPremiumCharge`.
94
95 | Session value | Effect |
96 |---|---|
71 -| Omitted or `{}` | Permits eligible Composio-billed tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
72 -| `false` | Disables Composio-billed access for that Session. Your own connected-account routes remain available. |
73 -| `{ "toolkits": { "enable": ["exa"] } }` | Permits billed access only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
74 -| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows billed access to selected tools within a toolkit. |
97 +| Omitted or `{}` | Permits premium usage for eligible tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
98 +| `false` | Disables premium usage for that Session. Your own connected-account routes remain available. |
99 +| `{ "toolkits": { "enable": ["exa"] } }` | Permits premium usage only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
100 +| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows premium usage to selected tools within a toolkit. |
101 | `{ "return_premium_charge": true }` | Requests the actual `premium_charge` in an eligible Session tool response. This changes charge visibility, not permission to spend. |
102
77 -For example, keep Exa and Firecrawl available, but permit billed access only for `EXA_SEARCH`:
78 -
79 -```json
80 -{
81 - "user_id": "user_123",
82 - "toolkits": { "enable": ["exa", "firecrawl"] },
83 - "premium_usage": {
84 - "toolkits": { "enable": ["exa"] },
85 - "tools": { "exa": { "enable": ["EXA_SEARCH"] } }
86 - }
87 -}
103 +For example, keep Exa and Firecrawl available, but permit premium usage only for `EXA_SEARCH`:
104 +
105 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
106 +<Tab value="Python">
107 +```python
108 +session = composio.sessions.create(
109 + user_id="user_123",
110 + toolkits=["exa", "firecrawl"],
111 + premium_usage={
112 + "toolkits": {"enable": ["exa"]},
113 + "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
114 + },
115 +)
116 ```
117 +</Tab>
118 +<Tab value="TypeScript">
119 +```typescript
120 +const session = await composio.create("user_123", {
121 + toolkits: ["exa", "firecrawl"],
122 + premiumUsage: {
123 + toolkits: { enable: ["exa"] },
124 + tools: { exa: { enable: ["EXA_SEARCH"] } },
125 + },
126 +});
127 +```
128 +</Tab>
129 +</Tabs>
130
90 -To stop Composio-billed access on an existing Session, use the [Session patch endpoint](/reference/api-reference/tool-router/patchToolRouterSessionBySessionId):
131 +To stop premium usage on an existing Session, update its policy:
132
92 -```bash
93 -curl --request PATCH \
94 - --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID" \
95 - --header "x-api-key: $COMPOSIO_API_KEY" \
96 - --header "content-type: application/json" \
97 - --data '{ "premium_usage": false }'
133 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
134 +<Tab value="Python">
135 +```python
136 +session.update(premium_usage=False)
137 +```
138 +</Tab>
139 +<Tab value="TypeScript">
140 +```typescript
141 +await session.update({ premiumUsage: false });
142 ```
143 +</Tab>
144 +</Tabs>
145
146 On patch, omitted `premium_usage` fields keep their existing values. Supplying an object after `false` enables this Session policy again, provided the project allows it.
147
148 ## Know which account runs the tool
149
104 -A Composio-managed 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.
150 +A hosted 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.
151
106 -If you select a connected account explicitly, that route wins and does not fall back to Composio's account on failure. Otherwise, available user, shared, or developer connections take priority over a Composio-managed account. If the chosen tool is not supported by a Composio-managed account, it follows the normal connection flow.
152 +If you select a connected account explicitly, that route wins and does not fall back to the hosted account on failure. Otherwise, available user, shared, or developer connections take priority over a hosted account. If the chosen tool is not supported by a hosted account, it follows the normal connection flow.
153
108 -Composio-managed accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
154 +Hosted accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
155
156 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.