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, 21:00 UTC
docs: document tool preloading
Dhawal Upadhyay committed
May 8, 2026 at 12:47 UTC
007afe63b0042d2fc167ccbda58eba8adcc49fd8
3 files changed
+220
-96
docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
+126
-10
@@ -18,22 +18,51 @@ generally fewer than 20 tools, to avoid context bloat.
18
| TypeScript `@composio/core` | `0.9.0` |
19
| Python `composio` | `0.13.0` |
20
21
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22
+<Tab value="Python">
23
+```python
24
+from composio import Composio
25
+
26
+composio = Composio(api_key="your_api_key")
27
+
28
+session = composio.create(
29
+ user_id="user_123",
30
+ toolkits=["gmail"],
31
+ preload={
32
+ "tools": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
33
+ },
34
+)
35
+
36
+tools = session.tools()
37
+print([tool.name for tool in tools])
38
+# GMAIL_FETCH_EMAILS
39
+# GMAIL_CREATE_EMAIL_DRAFT
40
+# COMPOSIO_SEARCH_TOOLS
41
+# ... other default meta tools
42
+```
43
+</Tab>
44
+<Tab value="TypeScript">
45
```typescript
46
import { Composio } from '@composio/core';
47
+
48
const composio = new Composio({ apiKey: 'your_api_key' });
49
25
-const session = await composio.create("user_123", {
26
- toolkits: ["granola_mcp"],
50
+const session = await composio.create('user_123', {
51
+ toolkits: ['gmail'],
52
preload: {
28
- tools: [
29
- "GRANOLA_MCP_LIST_MEETINGS",
30
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
31
- ],
53
+ tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
54
},
55
});
56
57
const tools = await session.tools();
58
+console.log(tools.map((tool) => tool.name));
59
+// GMAIL_FETCH_EMAILS
60
+// GMAIL_CREATE_EMAIL_DRAFT
61
+// COMPOSIO_SEARCH_TOOLS
62
+// ... other default meta tools
63
```
64
+</Tab>
65
+</Tabs>
66
67
### Direct tools preset
68
@@ -41,22 +70,99 @@ Specialized agents with a narrow tool set can use the direct tools preset to
70
load every tool allowed by session filters into the session's tool list and
71
disable session meta tools by default.
72
73
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
74
+<Tab value="Python">
75
+```python
76
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
77
+
78
+composio = Composio(api_key="your_api_key")
79
+
80
+session = composio.create(
81
+ user_id="user_123",
82
+ toolkits=["gmail"],
83
+ tools={
84
+ "gmail": {
85
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
86
+ },
87
+ },
88
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
89
+)
90
+
91
+tools = session.tools()
92
+print([tool.name for tool in tools])
93
+# GMAIL_FETCH_EMAILS
94
+# GMAIL_CREATE_EMAIL_DRAFT
95
+```
96
+</Tab>
97
+<Tab value="TypeScript">
98
```typescript
99
import { Composio, SessionPreset } from '@composio/core';
100
+
101
const composio = new Composio({ apiKey: 'your_api_key' });
102
48
-const session = await composio.create("user_123", {
49
- toolkits: ["granola_mcp"],
103
+const session = await composio.create('user_123', {
104
+ toolkits: ['gmail'],
105
+ tools: {
106
+ gmail: {
107
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
108
+ },
109
+ },
110
sessionPreset: SessionPreset.DIRECT_TOOLS,
111
});
112
+
113
+const tools = await session.tools();
114
+console.log(tools.map((tool) => tool.name));
115
+// GMAIL_FETCH_EMAILS
116
+// GMAIL_CREATE_EMAIL_DRAFT
117
```
118
+</Tab>
119
+</Tabs>
120
121
For agents that still need selected helper behavior, supported meta tool groups
122
can be enabled alongside the preset:
123
124
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
125
+<Tab value="Python">
126
+```python
127
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
128
+
129
+composio = Composio(api_key="your_api_key")
130
+
131
+session = composio.create(
132
+ user_id="user_123",
133
+ toolkits=["gmail"],
134
+ tools={
135
+ "gmail": {
136
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
137
+ },
138
+ },
139
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
140
+ manage_connections={"enable": True},
141
+ workbench={"enable": True},
142
+)
143
+
144
+tools = session.tools()
145
+print([tool.name for tool in tools])
146
+# GMAIL_FETCH_EMAILS
147
+# GMAIL_CREATE_EMAIL_DRAFT
148
+# COMPOSIO_MANAGE_CONNECTIONS
149
+# COMPOSIO_REMOTE_WORKBENCH
150
+# COMPOSIO_REMOTE_BASH_TOOL
151
+```
152
+</Tab>
153
+<Tab value="TypeScript">
154
```typescript
58
-const session = await composio.create("user_123", {
59
- toolkits: ["granola_mcp"],
155
+import { Composio, SessionPreset } from '@composio/core';
156
+
157
+const composio = new Composio({ apiKey: 'your_api_key' });
158
+
159
+const session = await composio.create('user_123', {
160
+ toolkits: ['gmail'],
161
+ tools: {
162
+ gmail: {
163
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
164
+ },
165
+ },
166
sessionPreset: SessionPreset.DIRECT_TOOLS,
167
manageConnections: {
168
enable: true,
@@ -65,7 +171,17 @@ const session = await composio.create("user_123", {
171
enable: true,
172
},
173
});
174
+
175
+const tools = await session.tools();
176
+console.log(tools.map((tool) => tool.name));
177
+// GMAIL_FETCH_EMAILS
178
+// GMAIL_CREATE_EMAIL_DRAFT
179
+// COMPOSIO_MANAGE_CONNECTIONS
180
+// COMPOSIO_REMOTE_WORKBENCH
181
+// COMPOSIO_REMOTE_BASH_TOOL
182
```
183
+</Tab>
184
+</Tabs>
185
186
See [Preloading tools](/docs/configuring-sessions#preloading-tools),
187
[Direct tools preset](/docs/configuring-sessions#direct-tools-preset), and
docs/content/docs/configuring-sessions.mdx
+70
-19
@@ -116,16 +116,21 @@ Requires `@composio/core` ≥ `0.9.0` (TypeScript) or `composio` ≥ `0.13.0`
116
```python
117
session = composio.create(
118
user_id="user_123",
119
- toolkits=["granola_mcp"],
119
+ toolkits=["gmail"],
120
preload={
121
"tools": [
122
- "GRANOLA_MCP_LIST_MEETINGS",
123
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
122
+ "GMAIL_FETCH_EMAILS",
123
+ "GMAIL_CREATE_EMAIL_DRAFT",
124
],
125
},
126
)
127
128
tools = session.tools()
129
+print([tool.name for tool in tools])
130
+# GMAIL_FETCH_EMAILS
131
+# GMAIL_CREATE_EMAIL_DRAFT
132
+# COMPOSIO_SEARCH_TOOLS
133
+# ... other default meta tools
134
```
135
</Tab>
136
<Tab value="TypeScript">
@@ -134,27 +139,29 @@ import { Composio } from '@composio/core';
139
const composio = new Composio({ apiKey: 'your_api_key' });
140
// ---cut---
141
const session = await composio.create("user_123", {
137
- toolkits: ["granola_mcp"],
142
+ toolkits: ["gmail"],
143
preload: {
139
- tools: [
140
- "GRANOLA_MCP_LIST_MEETINGS",
141
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
142
- ],
144
+ tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
145
},
146
});
147
148
const tools = await session.tools();
149
+console.log(tools.map((tool) => tool.name));
150
+// GMAIL_FETCH_EMAILS
151
+// GMAIL_CREATE_EMAIL_DRAFT
152
+// COMPOSIO_SEARCH_TOOLS
153
+// ... other default meta tools
154
```
155
</Tab>
156
</Tabs>
157
151
-For SDK custom tools, set `preload: true` on the custom tool or custom toolkit
152
-instead of listing `LOCAL_*` slugs in `preload.tools`. See
158
+For SDK custom tools, set `preload: true` on the custom tool or custom toolkit. See
159
[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools).
160
161
Use the `preload.tools = "all"` shortcut (`preload={"tools": "all"}` in Python,
156
-`preload: { tools: "all" }` in TypeScript) to preload every Composio-managed
157
-tool allowed by the session filters.
162
+`preload: { tools: "all" }` in TypeScript) to preload every tool allowed by the
163
+session filters. The `all` shorthand works for both Composio tools and SDK
164
+custom tools.
165
166
### Direct tools preset
167
@@ -174,11 +181,22 @@ from composio import SESSION_PRESET_DIRECT_TOOLS
181
182
session = composio.create(
183
user_id="user_123",
177
- toolkits=["granola_mcp"],
184
+ toolkits=["gmail"],
185
+ tools={
186
+ "gmail": {
187
+ "enable": [
188
+ "GMAIL_FETCH_EMAILS",
189
+ "GMAIL_CREATE_EMAIL_DRAFT",
190
+ ],
191
+ },
192
+ },
193
session_preset=SESSION_PRESET_DIRECT_TOOLS,
194
)
195
196
tools = session.tools()
197
+print([tool.name for tool in tools])
198
+# GMAIL_FETCH_EMAILS
199
+# GMAIL_CREATE_EMAIL_DRAFT
200
```
201
</Tab>
202
<Tab value="TypeScript">
@@ -187,11 +205,19 @@ import { Composio, SessionPreset } from '@composio/core';
205
const composio = new Composio({ apiKey: 'your_api_key' });
206
// ---cut---
207
const session = await composio.create("user_123", {
190
- toolkits: ["granola_mcp"],
208
+ toolkits: ["gmail"],
209
+ tools: {
210
+ gmail: {
211
+ enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
212
+ },
213
+ },
214
sessionPreset: SessionPreset.DIRECT_TOOLS,
215
});
216
217
const tools = await session.tools();
218
+console.log(tools.map((tool) => tool.name));
219
+// GMAIL_FETCH_EMAILS
220
+// GMAIL_CREATE_EMAIL_DRAFT
221
```
222
</Tab>
223
</Tabs>
@@ -199,9 +225,9 @@ const tools = await session.tools();
225
**Enable selected meta tools**
226
227
When using the direct tools preset, you can selectively re-enable supported meta
202
-tool groups that your agent still needs. For example, this session loads Granola
203
-tools upfront while keeping connection management and workbench support
204
-available:
228
+tool groups that your agent still needs. For example, this session loads Gmail
229
+reply-drafting tools upfront while keeping connection management and workbench
230
+support available:
231
232
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
233
<Tab value="Python">
@@ -210,7 +236,15 @@ from composio import SESSION_PRESET_DIRECT_TOOLS
236
237
session = composio.create(
238
user_id="user_123",
213
- toolkits=["granola_mcp"],
239
+ toolkits=["gmail"],
240
+ tools={
241
+ "gmail": {
242
+ "enable": [
243
+ "GMAIL_FETCH_EMAILS",
244
+ "GMAIL_CREATE_EMAIL_DRAFT",
245
+ ],
246
+ },
247
+ },
248
session_preset=SESSION_PRESET_DIRECT_TOOLS,
249
manage_connections={
250
"enable": True,
@@ -221,6 +255,12 @@ session = composio.create(
255
)
256
257
tools = session.tools()
258
+print([tool.name for tool in tools])
259
+# GMAIL_FETCH_EMAILS
260
+# GMAIL_CREATE_EMAIL_DRAFT
261
+# COMPOSIO_MANAGE_CONNECTIONS
262
+# COMPOSIO_REMOTE_WORKBENCH
263
+# COMPOSIO_REMOTE_BASH_TOOL
264
```
265
</Tab>
266
<Tab value="TypeScript">
@@ -229,7 +269,12 @@ import { Composio, SessionPreset } from '@composio/core';
269
const composio = new Composio({ apiKey: 'your_api_key' });
270
// ---cut---
271
const session = await composio.create("user_123", {
232
- toolkits: ["granola_mcp"],
272
+ toolkits: ["gmail"],
273
+ tools: {
274
+ gmail: {
275
+ enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
276
+ },
277
+ },
278
sessionPreset: SessionPreset.DIRECT_TOOLS,
279
manageConnections: {
280
enable: true,
@@ -240,6 +285,12 @@ const session = await composio.create("user_123", {
285
});
286
287
const tools = await session.tools();
288
+console.log(tools.map((tool) => tool.name));
289
+// GMAIL_FETCH_EMAILS
290
+// GMAIL_CREATE_EMAIL_DRAFT
291
+// COMPOSIO_MANAGE_CONNECTIONS
292
+// COMPOSIO_REMOTE_WORKBENCH
293
+// COMPOSIO_REMOTE_BASH_TOOL
294
```
295
</Tab>
296
</Tabs>
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+24
-67
@@ -489,61 +489,39 @@ tools = session.tools()
489
## Preloading custom tools
490
491
Custom tools are searchable by default. Set `preload: true` / `preload=True` on a
492
-custom tool when it should be returned directly from `session.tools()`. For a
493
-custom toolkit, set preload on the toolkit to expose all of its tools, then use a
494
-tool-level `preload: false` / `preload=False` to opt out a specific tool.
492
+custom tool when it should be returned directly from `session.tools()`. Toolkit
493
+preload applies to all tools in that toolkit; set `preload: false` /
494
+`preload=False` on one tool to opt it out.
495
496
<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
497
<Tab value="TypeScript">
498
```typescript
499
-import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
499
+import { Composio, experimental_createTool } from "@composio/core";
500
import { z } from "zod/v3";
501
502
const composio = new Composio({ apiKey: "your_api_key" });
503
504
-const lookupAccount = experimental_createTool("LOOKUP_ACCOUNT", {
505
- name: "Lookup account",
506
- description: "Look up an account by email",
504
+const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {
505
+ name: "Get reply style guide",
506
+ description: "Return the team's email reply style guide",
507
preload: true,
508
inputParams: z.object({
509
- email: z.string().describe("Customer email address"),
509
+ topic: z.string().describe("Email topic"),
510
}),
511
- execute: async ({ email }) => ({ email, status: "active" }),
512
-});
513
-
514
-const supportTools = experimental_createToolkit("SUPPORT_TOOLS", {
515
- name: "Support tools",
516
- description: "Internal support workflows",
517
- preload: true,
518
- tools: [
519
- experimental_createTool("GET_TICKET", {
520
- name: "Get ticket",
521
- description: "Fetch an internal support ticket",
522
- inputParams: z.object({
523
- ticketId: z.string().describe("Ticket ID"),
524
- }),
525
- execute: async ({ ticketId }) => ({ ticketId, priority: "high" }),
526
- }),
527
- experimental_createTool("ARCHIVE_TICKET", {
528
- name: "Archive ticket",
529
- description: "Archive an internal support ticket",
530
- preload: false,
531
- inputParams: z.object({
532
- ticketId: z.string().describe("Ticket ID"),
533
- }),
534
- execute: async ({ ticketId }) => ({ ticketId, archived: true }),
535
- }),
536
- ],
511
+ execute: async ({ topic }) => ({ topic, tone: "concise and helpful" }),
512
});
513
514
const session = await composio.create("user_1", {
515
experimental: {
541
- customTools: [lookupAccount],
542
- customToolkits: [supportTools],
516
+ customTools: [replyGuide],
517
},
518
});
519
520
const tools = await session.tools();
521
+console.log(tools.map((tool) => tool.name));
522
+// LOCAL_GET_REPLY_STYLE_GUIDE
523
+// COMPOSIO_SEARCH_TOOLS
524
+// ... other default meta tools
525
```
526
</Tab>
527
<Tab value="Python">
@@ -555,49 +533,28 @@ from composio import Composio
533
composio = Composio(api_key="your_api_key")
534
535
558
-class EmailInput(BaseModel):
559
- email: str = Field(description="Customer email address")
536
+class ReplyGuideInput(BaseModel):
537
+ topic: str = Field(description="Email topic")
538
539
540
@composio.experimental.tool(preload=True)
563
-def lookup_account(input: EmailInput, ctx):
564
- """Look up an account by email."""
565
- return {"email": input.email, "status": "active"}
566
-
567
-
568
-support_tools = composio.experimental.Toolkit(
569
- slug="SUPPORT_TOOLS",
570
- name="Support tools",
571
- description="Internal support workflows",
572
- preload=True,
573
-)
574
-
575
-
576
-class TicketInput(BaseModel):
577
- ticket_id: str = Field(description="Ticket ID")
578
-
579
-
580
-@support_tools.tool()
581
-def get_ticket(input: TicketInput, ctx):
582
- """Fetch an internal support ticket."""
583
- return {"ticket_id": input.ticket_id, "priority": "high"}
584
-
585
-
586
-@support_tools.tool(preload=False)
587
-def archive_ticket(input: TicketInput, ctx):
588
- """Archive an internal support ticket."""
589
- return {"ticket_id": input.ticket_id, "archived": True}
541
+def get_reply_style_guide(input: ReplyGuideInput, ctx):
542
+ """Return the team's email reply style guide."""
543
+ return {"topic": input.topic, "tone": "concise and helpful"}
544
545
546
session = composio.create(
547
user_id="user_1",
548
experimental={
595
- "custom_tools": [lookup_account],
596
- "custom_toolkits": [support_tools],
549
+ "custom_tools": [get_reply_style_guide],
550
},
551
)
552
553
tools = session.tools()
554
+print([tool.name for tool in tools])
555
+# LOCAL_GET_REPLY_STYLE_GUIDE
556
+# COMPOSIO_SEARCH_TOOLS
557
+# ... other default meta tools
558
```
559
</Tab>
560
</Tabs>