Skip to content

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 Upadhyay007afe63b004
diff --git a/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx b/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
index cadb3ee97..da8d80cd1 100644
--- a/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
+++ b/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
@@ -18,22 +18,51 @@ generally fewer than 20 tools, to avoid context bloat.
| TypeScript `@composio/core` | `0.9.0` |
| Python `composio` | `0.13.0` |
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your_api_key")
+
+session = composio.create(
+ user_id="user_123",
+ toolkits=["gmail"],
+ preload={
+ "tools": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
+ },
+)
+
+tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
+# COMPOSIO_SEARCH_TOOLS
+# ... other default meta tools
+```
+</Tab>
+<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
+
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+const session = await composio.create('user_123', {
+ toolkits: ['gmail'],
preload: {
- tools: [
- "GRANOLA_MCP_LIST_MEETINGS",
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
- ],
+ tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
},
});
const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
+// COMPOSIO_SEARCH_TOOLS
+// ... other default meta tools
```
+</Tab>
+</Tabs>
### Direct tools preset
@@ -41,22 +70,99 @@ Specialized agents with a narrow tool set can use the direct tools preset to
load every tool allowed by session filters into the session's tool list and
disable session meta tools by default.
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
+
+composio = Composio(api_key="your_api_key")
+
+session = composio.create(
+ user_id="user_123",
+ toolkits=["gmail"],
+ tools={
+ "gmail": {
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
+ },
+ },
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
+)
+
+tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
+```
+</Tab>
+<Tab value="TypeScript">
```typescript
import { Composio, SessionPreset } from '@composio/core';
+
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+const session = await composio.create('user_123', {
+ toolkits: ['gmail'],
+ tools: {
+ gmail: {
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
+ },
+ },
sessionPreset: SessionPreset.DIRECT_TOOLS,
});
+
+const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
```
+</Tab>
+</Tabs>
For agents that still need selected helper behavior, supported meta tool groups
can be enabled alongside the preset:
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
+
+composio = Composio(api_key="your_api_key")
+
+session = composio.create(
+ user_id="user_123",
+ toolkits=["gmail"],
+ tools={
+ "gmail": {
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
+ },
+ },
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
+ manage_connections={"enable": True},
+ workbench={"enable": True},
+)
+
+tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
+# COMPOSIO_MANAGE_CONNECTIONS
+# COMPOSIO_REMOTE_WORKBENCH
+# COMPOSIO_REMOTE_BASH_TOOL
+```
+</Tab>
+<Tab value="TypeScript">
```typescript
-const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+import { Composio, SessionPreset } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your_api_key' });
+
+const session = await composio.create('user_123', {
+ toolkits: ['gmail'],
+ tools: {
+ gmail: {
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
+ },
+ },
sessionPreset: SessionPreset.DIRECT_TOOLS,
manageConnections: {
enable: true,
@@ -65,7 +171,17 @@ const session = await composio.create("user_123", {
enable: true,
},
});
+
+const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
+// COMPOSIO_MANAGE_CONNECTIONS
+// COMPOSIO_REMOTE_WORKBENCH
+// COMPOSIO_REMOTE_BASH_TOOL
```
+</Tab>
+</Tabs>
See [Preloading tools](/docs/configuring-sessions#preloading-tools),
[Direct tools preset](/docs/configuring-sessions#direct-tools-preset), and
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 013d2f41d..524449262 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -116,16 +116,21 @@ Requires `@composio/core` ≥ `0.9.0` (TypeScript) or `composio` ≥ `0.13.0`
```python
session = composio.create(
user_id="user_123",
- toolkits=["granola_mcp"],
+ toolkits=["gmail"],
preload={
"tools": [
- "GRANOLA_MCP_LIST_MEETINGS",
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
+ "GMAIL_FETCH_EMAILS",
+ "GMAIL_CREATE_EMAIL_DRAFT",
],
},
)
tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
+# COMPOSIO_SEARCH_TOOLS
+# ... other default meta tools
```
</Tab>
<Tab value="TypeScript">
@@ -134,27 +139,29 @@ import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+ toolkits: ["gmail"],
preload: {
- tools: [
- "GRANOLA_MCP_LIST_MEETINGS",
- "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
- ],
+ tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
},
});
const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
+// COMPOSIO_SEARCH_TOOLS
+// ... other default meta tools
```
</Tab>
</Tabs>
-For SDK custom tools, set `preload: true` on the custom tool or custom toolkit
-instead of listing `LOCAL_*` slugs in `preload.tools`. See
+For SDK custom tools, set `preload: true` on the custom tool or custom toolkit. See
[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools).
Use the `preload.tools = "all"` shortcut (`preload={"tools": "all"}` in Python,
-`preload: { tools: "all" }` in TypeScript) to preload every Composio-managed
-tool allowed by the session filters.
+`preload: { tools: "all" }` in TypeScript) to preload every tool allowed by the
+session filters. The `all` shorthand works for both Composio tools and SDK
+custom tools.
### Direct tools preset
@@ -174,11 +181,22 @@ from composio import SESSION_PRESET_DIRECT_TOOLS
session = composio.create(
user_id="user_123",
- toolkits=["granola_mcp"],
+ toolkits=["gmail"],
+ tools={
+ "gmail": {
+ "enable": [
+ "GMAIL_FETCH_EMAILS",
+ "GMAIL_CREATE_EMAIL_DRAFT",
+ ],
+ },
+ },
session_preset=SESSION_PRESET_DIRECT_TOOLS,
)
tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
```
</Tab>
<Tab value="TypeScript">
@@ -187,11 +205,19 @@ import { Composio, SessionPreset } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+ toolkits: ["gmail"],
+ tools: {
+ gmail: {
+ enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
+ },
+ },
sessionPreset: SessionPreset.DIRECT_TOOLS,
});
const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
```
</Tab>
</Tabs>
@@ -199,9 +225,9 @@ const tools = await session.tools();
**Enable selected meta tools**
When using the direct tools preset, you can selectively re-enable supported meta
-tool groups that your agent still needs. For example, this session loads Granola
-tools upfront while keeping connection management and workbench support
-available:
+tool groups that your agent still needs. For example, this session loads Gmail
+reply-drafting tools upfront while keeping connection management and workbench
+support available:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
@@ -210,7 +236,15 @@ from composio import SESSION_PRESET_DIRECT_TOOLS
session = composio.create(
user_id="user_123",
- toolkits=["granola_mcp"],
+ toolkits=["gmail"],
+ tools={
+ "gmail": {
+ "enable": [
+ "GMAIL_FETCH_EMAILS",
+ "GMAIL_CREATE_EMAIL_DRAFT",
+ ],
+ },
+ },
session_preset=SESSION_PRESET_DIRECT_TOOLS,
manage_connections={
"enable": True,
@@ -221,6 +255,12 @@ session = composio.create(
)
tools = session.tools()
+print([tool.name for tool in tools])
+# GMAIL_FETCH_EMAILS
+# GMAIL_CREATE_EMAIL_DRAFT
+# COMPOSIO_MANAGE_CONNECTIONS
+# COMPOSIO_REMOTE_WORKBENCH
+# COMPOSIO_REMOTE_BASH_TOOL
```
</Tab>
<Tab value="TypeScript">
@@ -229,7 +269,12 @@ import { Composio, SessionPreset } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
- toolkits: ["granola_mcp"],
+ toolkits: ["gmail"],
+ tools: {
+ gmail: {
+ enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
+ },
+ },
sessionPreset: SessionPreset.DIRECT_TOOLS,
manageConnections: {
enable: true,
@@ -240,6 +285,12 @@ const session = await composio.create("user_123", {
});
const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// GMAIL_FETCH_EMAILS
+// GMAIL_CREATE_EMAIL_DRAFT
+// COMPOSIO_MANAGE_CONNECTIONS
+// COMPOSIO_REMOTE_WORKBENCH
+// COMPOSIO_REMOTE_BASH_TOOL
```
</Tab>
</Tabs>
diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
index f1c656a56..e6e74cdb8 100644
--- a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
@@ -489,61 +489,39 @@ tools = session.tools()
## Preloading custom tools
Custom tools are searchable by default. Set `preload: true` / `preload=True` on a
-custom tool when it should be returned directly from `session.tools()`. For a
-custom toolkit, set preload on the toolkit to expose all of its tools, then use a
-tool-level `preload: false` / `preload=False` to opt out a specific tool.
+custom tool when it should be returned directly from `session.tools()`. Toolkit
+preload applies to all tools in that toolkit; set `preload: false` /
+`preload=False` on one tool to opt it out.
<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
<Tab value="TypeScript">
```typescript
-import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
+import { Composio, experimental_createTool } from "@composio/core";
import { z } from "zod/v3";
const composio = new Composio({ apiKey: "your_api_key" });
-const lookupAccount = experimental_createTool("LOOKUP_ACCOUNT", {
- name: "Lookup account",
- description: "Look up an account by email",
+const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {
+ name: "Get reply style guide",
+ description: "Return the team's email reply style guide",
preload: true,
inputParams: z.object({
- email: z.string().describe("Customer email address"),
+ topic: z.string().describe("Email topic"),
}),
- execute: async ({ email }) => ({ email, status: "active" }),
-});
-
-const supportTools = experimental_createToolkit("SUPPORT_TOOLS", {
- name: "Support tools",
- description: "Internal support workflows",
- preload: true,
- tools: [
- experimental_createTool("GET_TICKET", {
- name: "Get ticket",
- description: "Fetch an internal support ticket",
- inputParams: z.object({
- ticketId: z.string().describe("Ticket ID"),
- }),
- execute: async ({ ticketId }) => ({ ticketId, priority: "high" }),
- }),
- experimental_createTool("ARCHIVE_TICKET", {
- name: "Archive ticket",
- description: "Archive an internal support ticket",
- preload: false,
- inputParams: z.object({
- ticketId: z.string().describe("Ticket ID"),
- }),
- execute: async ({ ticketId }) => ({ ticketId, archived: true }),
- }),
- ],
+ execute: async ({ topic }) => ({ topic, tone: "concise and helpful" }),
});
const session = await composio.create("user_1", {
experimental: {
- customTools: [lookupAccount],
- customToolkits: [supportTools],
+ customTools: [replyGuide],
},
});
const tools = await session.tools();
+console.log(tools.map((tool) => tool.name));
+// LOCAL_GET_REPLY_STYLE_GUIDE
+// COMPOSIO_SEARCH_TOOLS
+// ... other default meta tools
```
</Tab>
<Tab value="Python">
@@ -555,49 +533,28 @@ from composio import Composio
composio = Composio(api_key="your_api_key")
-class EmailInput(BaseModel):
- email: str = Field(description="Customer email address")
+class ReplyGuideInput(BaseModel):
+ topic: str = Field(description="Email topic")
@composio.experimental.tool(preload=True)
-def lookup_account(input: EmailInput, ctx):
- """Look up an account by email."""
- return {"email": input.email, "status": "active"}
-
-
-support_tools = composio.experimental.Toolkit(
- slug="SUPPORT_TOOLS",
- name="Support tools",
- description="Internal support workflows",
- preload=True,
-)
-
-
-class TicketInput(BaseModel):
- ticket_id: str = Field(description="Ticket ID")
-
-
-@support_tools.tool()
-def get_ticket(input: TicketInput, ctx):
- """Fetch an internal support ticket."""
- return {"ticket_id": input.ticket_id, "priority": "high"}
-
-
-@support_tools.tool(preload=False)
-def archive_ticket(input: TicketInput, ctx):
- """Archive an internal support ticket."""
- return {"ticket_id": input.ticket_id, "archived": True}
+def get_reply_style_guide(input: ReplyGuideInput, ctx):
+ """Return the team's email reply style guide."""
+ return {"topic": input.topic, "tone": "concise and helpful"}
session = composio.create(
user_id="user_1",
experimental={
- "custom_tools": [lookup_account],
- "custom_toolkits": [support_tools],
+ "custom_tools": [get_reply_style_guide],
},
)
tools = session.tools()
+print([tool.name for tool in tools])
+# LOCAL_GET_REPLY_STYLE_GUIDE
+# COMPOSIO_SEARCH_TOOLS
+# ... other default meta tools
```
</Tab>
</Tabs>