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
Document ToolRouter preloaded tools
Dhawal Upadhyay committed
May 7, 2026 at 18:44 UTC
dda8684cc19f310ea71bd137437d5d60cb5e13f1
3 files changed
+350
-1
docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
new
+73
@@ -0,0 +1,73 @@
1
+---
2
+title: "Sessions add preloaded tools and direct tools preset"
3
+description: "Sessions can now expose frequently used tools directly from session.tools(), and specialized agents can use a direct tools preset with selected meta tools enabled as needed."
4
+date: "2026-05-07"
5
+---
6
+
7
+Sessions now support preloading known tools into `session.tools()` and the
8
+session MCP tool list. This works for Composio-managed tools, while SDK custom
9
+tools can be exposed directly from `session.tools()` with `preload: true`.
10
+
11
+Use preloading for small, stable tool sets. Keep the preloaded set focused,
12
+generally fewer than 20 tools, to avoid context bloat.
13
+
14
+### SDK versions
15
+
16
+| SDK | Minimum version |
17
+| --- | --- |
18
+| TypeScript `@composio/core` | `TBD` |
19
+| Python `composio` | `TBD` |
20
+
21
+```typescript
22
+import { Composio } from '@composio/core';
23
+const composio = new Composio({ apiKey: 'your_api_key' });
24
+
25
+const session = await composio.create("user_123", {
26
+ toolkits: ["granola_mcp"],
27
+ preload: {
28
+ tools: [
29
+ "GRANOLA_MCP_LIST_MEETINGS",
30
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
31
+ ],
32
+ },
33
+});
34
+
35
+const tools = await session.tools();
36
+```
37
+
38
+### Direct tools preset
39
+
40
+Specialized agents with a narrow tool set can use the direct tools preset to
41
+load every tool allowed by session filters into the session's tool list and
42
+disable session meta tools by default.
43
+
44
+```typescript
45
+import { Composio, SessionPreset } from '@composio/core';
46
+const composio = new Composio({ apiKey: 'your_api_key' });
47
+
48
+const session = await composio.create("user_123", {
49
+ toolkits: ["granola_mcp"],
50
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
51
+});
52
+```
53
+
54
+For agents that still need selected helper behavior, supported meta tool groups
55
+can be enabled alongside the preset:
56
+
57
+```typescript
58
+const session = await composio.create("user_123", {
59
+ toolkits: ["granola_mcp"],
60
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
61
+ manageConnections: {
62
+ enable: true,
63
+ },
64
+ workbench: {
65
+ enable: true,
66
+ },
67
+});
68
+```
69
+
70
+See [Preloading tools](/docs/configuring-sessions#preloading-tools),
71
+[Direct tools preset](/docs/configuring-sessions#direct-tools-preset), and
72
+[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools)
73
+for Python examples and full guidance.
docs/content/docs/configuring-sessions.mdx
+155
@@ -89,6 +89,161 @@ const session = await composio.create("user_123", {
89
</Tab>
90
</Tabs>
91
92
+## Preloading tools
93
+
94
+By default, sessions expose [meta tools](/reference/meta-tools) that let the agent
95
+discover app tools at runtime. Use `preload.tools` when you already know the
96
+small set of tools that should be returned directly from `session.tools()` and
97
+the session MCP tool list.
98
+
99
+Preloading is useful for frequently used tools because the agent can call them
100
+without going through search each time. Keep the preloaded set small, generally
101
+fewer than 20 tools, to avoid context bloat.
102
+
103
+<Callout type="info">
104
+Requires `@composio/core` ≥ `TBD` (TypeScript) or `composio` ≥ `TBD`
105
+(Python). Older SDKs do not support `preload.tools`,
106
+`sessionPreset` / `session_preset`, or custom-tool `preload`.
107
+</Callout>
108
+
109
+<Callout type="info">
110
+`preload.tools` is not supported when `multiAccount.enable` is true. See
111
+[Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
112
+</Callout>
113
+
114
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
115
+<Tab value="Python">
116
+```python
117
+session = composio.create(
118
+ user_id="user_123",
119
+ toolkits=["granola_mcp"],
120
+ preload={
121
+ "tools": [
122
+ "GRANOLA_MCP_LIST_MEETINGS",
123
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
124
+ ],
125
+ },
126
+)
127
+
128
+tools = session.tools()
129
+```
130
+</Tab>
131
+<Tab value="TypeScript">
132
+```typescript
133
+import { Composio } from '@composio/core';
134
+const composio = new Composio({ apiKey: 'your_api_key' });
135
+// ---cut---
136
+const session = await composio.create("user_123", {
137
+ toolkits: ["granola_mcp"],
138
+ preload: {
139
+ tools: [
140
+ "GRANOLA_MCP_LIST_MEETINGS",
141
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
142
+ ],
143
+ },
144
+});
145
+
146
+const tools = await session.tools();
147
+```
148
+</Tab>
149
+</Tabs>
150
+
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
153
+[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools).
154
+
155
+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.
158
+
159
+### Direct tools preset
160
+
161
+The direct tools preset preloads every tool allowed by session filters into the
162
+session's tool list and disables session meta tools by default. This can be
163
+useful for specialized agents with a narrow tool set that do not need dynamic
164
+tool discovery, in-chat auth, or workbench helpers.
165
+
166
+This is not the default mode for broad agents. The default session behavior keeps
167
+meta tools available so the agent can search for relevant tools and avoid
168
+context bloat.
169
+
170
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
171
+<Tab value="Python">
172
+```python
173
+from composio import SESSION_PRESET_DIRECT_TOOLS
174
+
175
+session = composio.create(
176
+ user_id="user_123",
177
+ toolkits=["granola_mcp"],
178
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
179
+)
180
+
181
+tools = session.tools()
182
+```
183
+</Tab>
184
+<Tab value="TypeScript">
185
+```typescript
186
+import { Composio, SessionPreset } from '@composio/core';
187
+const composio = new Composio({ apiKey: 'your_api_key' });
188
+// ---cut---
189
+const session = await composio.create("user_123", {
190
+ toolkits: ["granola_mcp"],
191
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
192
+});
193
+
194
+const tools = await session.tools();
195
+```
196
+</Tab>
197
+</Tabs>
198
+
199
+**Enable selected meta tools**
200
+
201
+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:
205
+
206
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
207
+<Tab value="Python">
208
+```python
209
+from composio import SESSION_PRESET_DIRECT_TOOLS
210
+
211
+session = composio.create(
212
+ user_id="user_123",
213
+ toolkits=["granola_mcp"],
214
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
215
+ manage_connections={
216
+ "enable": True,
217
+ },
218
+ workbench={
219
+ "enable": True,
220
+ },
221
+)
222
+
223
+tools = session.tools()
224
+```
225
+</Tab>
226
+<Tab value="TypeScript">
227
+```typescript
228
+import { Composio, SessionPreset } from '@composio/core';
229
+const composio = new Composio({ apiKey: 'your_api_key' });
230
+// ---cut---
231
+const session = await composio.create("user_123", {
232
+ toolkits: ["granola_mcp"],
233
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
234
+ manageConnections: {
235
+ enable: true,
236
+ },
237
+ workbench: {
238
+ enable: true,
239
+ },
240
+});
241
+
242
+const tools = await session.tools();
243
+```
244
+</Tab>
245
+</Tabs>
246
+
247
## Custom auth configs
248
249
Use your own OAuth credentials instead of Composio's defaults:
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+122
-1
@@ -393,7 +393,11 @@ A custom toolkit groups related standalone tools under a namespace. Tools inside
393
<Tab value="TypeScript">
394
```typescript
395
// @noErrors
396
-import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
396
+import {
397
+ Composio,
398
+ experimental_createTool,
399
+ experimental_createToolkit,
400
+} from "@composio/core";
401
import { z } from "zod/v3";
402
// ---cut---
403
@@ -491,6 +495,123 @@ tools = session.tools()
495
496
</IntegrationTabs>
497
498
+## Preloading custom tools
499
+
500
+Custom tools are searchable by default. Set `preload: true` / `preload=True` on a
501
+custom tool when it should be returned directly from `session.tools()`. For a
502
+custom toolkit, set preload on the toolkit to expose all of its tools, then use a
503
+tool-level `preload: false` / `preload=False` to opt out a specific tool.
504
+
505
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
506
+<Tab value="TypeScript">
507
+```typescript
508
+// @noErrors
509
+import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
510
+import { z } from "zod/v3";
511
+
512
+const composio = new Composio({ apiKey: "your_api_key" });
513
+
514
+const lookupAccount = experimental_createTool("LOOKUP_ACCOUNT", {
515
+ name: "Lookup account",
516
+ description: "Look up an account by email",
517
+ preload: true,
518
+ inputParams: z.object({
519
+ email: z.string().describe("Customer email address"),
520
+ }),
521
+ execute: async ({ email }) => ({ email, status: "active" }),
522
+});
523
+
524
+const supportTools = experimental_createToolkit("SUPPORT_TOOLS", {
525
+ name: "Support tools",
526
+ description: "Internal support workflows",
527
+ preload: true,
528
+ tools: [
529
+ experimental_createTool("GET_TICKET", {
530
+ name: "Get ticket",
531
+ description: "Fetch an internal support ticket",
532
+ inputParams: z.object({
533
+ ticketId: z.string().describe("Ticket ID"),
534
+ }),
535
+ execute: async ({ ticketId }) => ({ ticketId, priority: "high" }),
536
+ }),
537
+ experimental_createTool("ARCHIVE_TICKET", {
538
+ name: "Archive ticket",
539
+ description: "Archive an internal support ticket",
540
+ preload: false,
541
+ inputParams: z.object({
542
+ ticketId: z.string().describe("Ticket ID"),
543
+ }),
544
+ execute: async ({ ticketId }) => ({ ticketId, archived: true }),
545
+ }),
546
+ ],
547
+});
548
+
549
+const session = await composio.create("user_1", {
550
+ experimental: {
551
+ customTools: [lookupAccount],
552
+ customToolkits: [supportTools],
553
+ },
554
+});
555
+
556
+const tools = await session.tools();
557
+```
558
+</Tab>
559
+<Tab value="Python">
560
+```python
561
+from pydantic import BaseModel, Field
562
+
563
+from composio import Composio
564
+
565
+composio = Composio(api_key="your_api_key")
566
+
567
+
568
+class EmailInput(BaseModel):
569
+ email: str = Field(description="Customer email address")
570
+
571
+
572
+@composio.experimental.tool(preload=True)
573
+def lookup_account(input: EmailInput, ctx):
574
+ """Look up an account by email."""
575
+ return {"email": input.email, "status": "active"}
576
+
577
+
578
+support_tools = composio.experimental.Toolkit(
579
+ slug="SUPPORT_TOOLS",
580
+ name="Support tools",
581
+ description="Internal support workflows",
582
+ preload=True,
583
+)
584
+
585
+
586
+class TicketInput(BaseModel):
587
+ ticket_id: str = Field(description="Ticket ID")
588
+
589
+
590
+@support_tools.tool()
591
+def get_ticket(input: TicketInput, ctx):
592
+ """Fetch an internal support ticket."""
593
+ return {"ticket_id": input.ticket_id, "priority": "high"}
594
+
595
+
596
+@support_tools.tool(preload=False)
597
+def archive_ticket(input: TicketInput, ctx):
598
+ """Archive an internal support ticket."""
599
+ return {"ticket_id": input.ticket_id, "archived": True}
600
+
601
+
602
+session = composio.create(
603
+ user_id="user_1",
604
+ experimental={
605
+ "custom_tools": [lookup_account],
606
+ "custom_toolkits": [support_tools],
607
+ },
608
+)
609
+
610
+tools = session.tools()
611
+```
612
+</Tab>
613
+</Tabs>
614
+
615
## Meta tools integration
616
617
Custom tools work automatically with Composio's meta tools: