@devries-cameron20 / composio Mirror · read-only / commits / dda8684cc
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.

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: