@devries-cameron20 / composio-1 / commits / 007afe63b
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: 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>