Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 214 lines 5.48 KB
Raw
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 frequently used tools into `session.tools()` and
8 the session MCP tool list, so agents can call them without searching each time.
9 This works for Composio-managed tools, while SDK custom tools can be exposed
10 directly from `session.tools()` with `preload: true`.
11
12 Keep the preloaded set focused, generally fewer than 20 tools, to avoid context
13 bloat.
14
15 ### SDK versions
16
17 | SDK | Minimum version |
18 | --- | --- |
19 | TypeScript `@composio/core` | `0.9.0` |
20 | Python `composio` | `0.13.0` |
21
22 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
23 <Tab value="Python">
24 ```python
25 from composio import Composio
26 from composio_openai_agents import OpenAIAgentsProvider
27
28 composio = Composio(
29 api_key="your_api_key",
30 provider=OpenAIAgentsProvider(),
31 )
32
33 session = composio.create(
34 user_id="user_123",
35 toolkits=["gmail"],
36 preload={
37 "tools": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
38 },
39 )
40
41 tools = session.tools()
42 print([tool.name for tool in tools])
43 # GMAIL_FETCH_EMAILS
44 # GMAIL_CREATE_EMAIL_DRAFT
45 # COMPOSIO_SEARCH_TOOLS
46 # ... other default meta tools
47 ```
48 </Tab>
49 <Tab value="TypeScript">
50 ```typescript
51 import { Composio } from '@composio/core';
52 import { OpenAIAgentsProvider } from '@composio/openai-agents';
53
54 const composio = new Composio({
55 apiKey: 'your_api_key',
56 provider: new OpenAIAgentsProvider(),
57 });
58
59 const session = await composio.create('user_123', {
60 toolkits: ['gmail'],
61 preload: {
62 tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
63 },
64 });
65
66 const tools = await session.tools();
67 console.log(tools.map((tool) => tool.name));
68 // GMAIL_FETCH_EMAILS
69 // GMAIL_CREATE_EMAIL_DRAFT
70 // COMPOSIO_SEARCH_TOOLS
71 // ... other default meta tools
72 ```
73 </Tab>
74 </Tabs>
75
76 ### Direct tools preset
77
78 Specialized agents with a narrow tool set can use the direct tools preset to
79 load every tool allowed by session filters into the session's tool list and
80 disable session meta tools by default.
81
82 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
83 <Tab value="Python">
84 ```python
85 from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
86 from composio_openai_agents import OpenAIAgentsProvider
87
88 composio = Composio(
89 api_key="your_api_key",
90 provider=OpenAIAgentsProvider(),
91 )
92
93 session = composio.create(
94 user_id="user_123",
95 toolkits=["gmail"],
96 tools={
97 "gmail": {
98 "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
99 },
100 },
101 session_preset=SESSION_PRESET_DIRECT_TOOLS,
102 )
103
104 tools = session.tools()
105 print([tool.name for tool in tools])
106 # GMAIL_FETCH_EMAILS
107 # GMAIL_CREATE_EMAIL_DRAFT
108 ```
109 </Tab>
110 <Tab value="TypeScript">
111 ```typescript
112 import { Composio, SessionPreset } from '@composio/core';
113 import { OpenAIAgentsProvider } from '@composio/openai-agents';
114
115 const composio = new Composio({
116 apiKey: 'your_api_key',
117 provider: new OpenAIAgentsProvider(),
118 });
119
120 const session = await composio.create('user_123', {
121 toolkits: ['gmail'],
122 tools: {
123 gmail: {
124 enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
125 },
126 },
127 sessionPreset: SessionPreset.DIRECT_TOOLS,
128 });
129
130 const tools = await session.tools();
131 console.log(tools.map((tool) => tool.name));
132 // GMAIL_FETCH_EMAILS
133 // GMAIL_CREATE_EMAIL_DRAFT
134 ```
135 </Tab>
136 </Tabs>
137
138 For agents that still need selected helper behavior, supported meta tool groups
139 can be enabled alongside the preset:
140
141 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
142 <Tab value="Python">
143 ```python
144 from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
145 from composio_openai_agents import OpenAIAgentsProvider
146
147 composio = Composio(
148 api_key="your_api_key",
149 provider=OpenAIAgentsProvider(),
150 )
151
152 session = composio.create(
153 user_id="user_123",
154 toolkits=["gmail"],
155 tools={
156 "gmail": {
157 "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
158 },
159 },
160 session_preset=SESSION_PRESET_DIRECT_TOOLS,
161 manage_connections={"enable": True},
162 workbench={"enable": True},
163 )
164
165 tools = session.tools()
166 print([tool.name for tool in tools])
167 # GMAIL_FETCH_EMAILS
168 # GMAIL_CREATE_EMAIL_DRAFT
169 # COMPOSIO_MANAGE_CONNECTIONS
170 # COMPOSIO_REMOTE_WORKBENCH
171 # COMPOSIO_REMOTE_BASH_TOOL
172 ```
173 </Tab>
174 <Tab value="TypeScript">
175 ```typescript
176 import { Composio, SessionPreset } from '@composio/core';
177 import { OpenAIAgentsProvider } from '@composio/openai-agents';
178
179 const composio = new Composio({
180 apiKey: 'your_api_key',
181 provider: new OpenAIAgentsProvider(),
182 });
183
184 const session = await composio.create('user_123', {
185 toolkits: ['gmail'],
186 tools: {
187 gmail: {
188 enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
189 },
190 },
191 sessionPreset: SessionPreset.DIRECT_TOOLS,
192 manageConnections: {
193 enable: true,
194 },
195 workbench: {
196 enable: true,
197 },
198 });
199
200 const tools = await session.tools();
201 console.log(tools.map((tool) => tool.name));
202 // GMAIL_FETCH_EMAILS
203 // GMAIL_CREATE_EMAIL_DRAFT
204 // COMPOSIO_MANAGE_CONNECTIONS
205 // COMPOSIO_REMOTE_WORKBENCH
206 // COMPOSIO_REMOTE_BASH_TOOL
207 ```
208 </Tab>
209 </Tabs>
210
211 See [Preloading tools](/docs/configuring-sessions#preloading-tools),
212 [Direct tools preset](/docs/configuring-sessions#direct-tools-preset), and
213 [Preloading custom tools](/docs/extending-sessions/local-tools-and-toolkits#preloading-local-tools)
214 for Python examples and full guidance.