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: add Custom Tools (Beta) section to configuring-sessions
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Dhawal Upadhyay committed
Mar 19, 2026 at 08:37 UTC
7266213a4a356fa6d5306f985510cc93155680e7
1 file changed
+114
-2
docs/content/docs/configuring-sessions.mdx
+114
-2
@@ -1,7 +1,7 @@
1
---
2
title: Configuring Sessions
3
-description: Enable toolkits, set auth configs, and select connected accounts
4
-keywords: [session, toolkits, auth configs, connected accounts]
3
+description: Enable toolkits, set auth configs, select connected accounts, and add custom tools
4
+keywords: [session, toolkits, auth configs, connected accounts, custom tools, beta]
5
---
6
7
## Creating a session
@@ -163,6 +163,118 @@ When executing a tool, the connected account is selected in this order:
163
164
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
165
166
+## Custom tools (Beta)
167
+
168
+<Callout type="warn">
169
+Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
170
+</Callout>
171
+
172
+Custom tools let you define local tools that run in-process alongside remote Composio tools. There are three patterns:
173
+
174
+### Standalone tool
175
+
176
+A tool that doesn't need any Composio-managed authentication:
177
+
178
+```ts
179
+import { experimental_createTool } from "@composio/core";
180
+import { z } from "zod/v3";
181
+
182
+const getUser = experimental_createTool("GET_USER", {
183
+ name: "Get user",
184
+ description: "Look up an internal user by ID",
185
+ inputParams: z.object({
186
+ user_id: z.string().describe("User ID"),
187
+ }),
188
+ execute: async ({ user_id }) => {
189
+ // Your logic here — just return the result
190
+ return { name: "Alice", email: "alice@acme.com" };
191
+ },
192
+});
193
+```
194
+
195
+### Extension tool
196
+
197
+A tool that inherits authentication from an existing Composio toolkit. Use `extendsToolkit` to specify which toolkit, then call APIs through `ctx.proxyExecute()` or invoke other tools via `ctx.execute()`:
198
+
199
+```ts
200
+import { experimental_createTool } from "@composio/core";
201
+import { z } from "zod/v3";
202
+
203
+const createDraft = experimental_createTool("CREATE_DRAFT", {
204
+ name: "Create Gmail draft",
205
+ description: "Create a Gmail draft via the Gmail API",
206
+ extendsToolkit: "gmail",
207
+ inputParams: z.object({
208
+ to: z.string().describe("Recipient email"),
209
+ subject: z.string().describe("Email subject"),
210
+ body: z.string().describe("Email body"),
211
+ }),
212
+ execute: async (input, ctx) => {
213
+ // proxyExecute routes through the session's Gmail auth
214
+ const res = await ctx.proxyExecute({
215
+ toolkit: "gmail",
216
+ endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
217
+ method: "POST",
218
+ body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
219
+ });
220
+ return res.data as Record<string, unknown>;
221
+ },
222
+});
223
+```
224
+
225
+The `SessionContext` (`ctx`) provides:
226
+- **`ctx.proxyExecute(params)`** — Make authenticated HTTP requests through Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body?`, `parameters?` (array of `{ in: "query" | "header", name, value }`).
227
+- **`ctx.execute(toolSlug, args)`** — Execute any Composio native tool from within your custom tool.
228
+
229
+### Custom toolkit
230
+
231
+Group related tools under a namespace using `experimental_createToolkit`:
232
+
233
+```ts
234
+import { experimental_createTool, experimental_createToolkit } from "@composio/core";
235
+import { z } from "zod/v3";
236
+
237
+const setRole = experimental_createTool("SET_ROLE", {
238
+ name: "Set role",
239
+ description: "Set a user's role",
240
+ inputParams: z.object({
241
+ user_id: z.string().describe("User ID"),
242
+ role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
243
+ }),
244
+ execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
245
+});
246
+
247
+const roleManager = experimental_createToolkit("ROLE_MANAGER", {
248
+ name: "Role Manager",
249
+ description: "Manage user roles",
250
+ tools: [setRole],
251
+});
252
+```
253
+
254
+Tools inside a toolkit must **not** have `extendsToolkit` set — they inherit the toolkit identity instead.
255
+
256
+### Binding to a session
257
+
258
+Pass custom tools and toolkits via the `experimental` option:
259
+
260
+```ts
261
+import { Composio } from "@composio/core";
262
+
263
+const composio = new Composio();
264
+
265
+const session = await composio.create("user_123", {
266
+ toolkits: ["gmail"],
267
+ experimental: {
268
+ customTools: [getUser, createDraft],
269
+ customToolkits: [roleManager],
270
+ },
271
+});
272
+
273
+const tools = await session.tools(); // Includes both remote and custom tools
274
+```
275
+
276
+Custom tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` → `LOCAL_GET_USER`, toolkit tools get `LOCAL_ROLE_MANAGER_SET_ROLE`). The final slug must not exceed 60 characters. Slugs cannot start with `LOCAL_` or `COMPOSIO_`.
277
+
278
## Session methods
279
280
### mcp