Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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">```typescriptimport { 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 toload every tool allowed by session filters into the session's tool list anddisable 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">```typescriptimport { 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 groupscan 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), anddiff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdxindex 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````pythonsession = 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_TOOLSsession = 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_TOOLSsession = 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.mdxindex 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 toolsCustom 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 Composiocomposio = 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>