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: type-checked code blocks, changelog, bump core to 0.6.6
- Remove // @noErrors, use proper Twoslash setup with ---cut--- - Use zod/v3 imports consistent with SDK internals - Bump @composio/core to ^0.6.6 (has experimental_createTool exports) - Add changelog entry for custom tools feature - Rename Beta -> Experimental Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Dhawal Upadhyay committed
Mar 23, 2026 at 13:57 UTC
26b9d1f35bb0239c9e5a8466b676a9a5c18953d2
3 files changed
+134
-20
docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx
new
+114
@@ -0,0 +1,114 @@
1
+---
2
+title: "Custom Tools and Toolkits (Experimental)"
3
+description: "Define local tools that run in-process alongside remote Composio tools in sessions"
4
+date: "2026-03-23"
5
+---
6
+
7
+You can now create custom tools and toolkits that run locally alongside remote Composio tools within a session.
8
+
9
+### SDK Version
10
+
11
+| Package | Version |
12
+|---------|---------|
13
+| @composio/core | v0.6.6 |
14
+
15
+---
16
+
17
+## What's New
18
+
19
+### Standalone Tools
20
+
21
+Define tools with no Composio-managed authentication using `experimental_createTool`. Just provide a slug, input schema, and an execute function:
22
+
23
+```ts
24
+// @noErrors
25
+import { experimental_createTool } from "@composio/core";
26
+import { z } from "zod/v3";
27
+
28
+const getUser = experimental_createTool("GET_USER", {
29
+ name: "Get user",
30
+ description: "Look up an internal user by ID",
31
+ inputParams: z.object({ user_id: z.string() }),
32
+ execute: async ({ user_id }) => ({ name: "Alice", email: "alice@acme.com" }),
33
+});
34
+```
35
+
36
+### Extension Tools
37
+
38
+Tools that inherit authentication from an existing Composio toolkit via `extendsToolkit`. The execute function receives a `SessionContext` with two methods:
39
+
40
+- **`ctx.proxyExecute()`** — make authenticated HTTP requests through Composio's auth layer
41
+- **`ctx.execute()`** — call any Composio native tool from within your custom tool
42
+
43
+```ts
44
+// @noErrors
45
+import { experimental_createTool } from "@composio/core";
46
+import { z } from "zod/v3";
47
+
48
+const createDraft = experimental_createTool("CREATE_DRAFT", {
49
+ name: "Create Gmail draft",
50
+ description: "Create a Gmail draft via the Gmail API",
51
+ extendsToolkit: "gmail",
52
+ inputParams: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
53
+ execute: async (input, ctx) => {
54
+ const res = await ctx.proxyExecute({
55
+ toolkit: "gmail",
56
+ endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
57
+ method: "POST",
58
+ body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
59
+ });
60
+ return res.data as Record<string, unknown>;
61
+ },
62
+});
63
+```
64
+
65
+### Custom Toolkits
66
+
67
+Group related tools under a namespace with `experimental_createToolkit`:
68
+
69
+```ts
70
+// @noErrors
71
+import { experimental_createTool, experimental_createToolkit } from "@composio/core";
72
+import { z } from "zod/v3";
73
+
74
+const roleManager = experimental_createToolkit("ROLE_MANAGER", {
75
+ name: "Role Manager",
76
+ description: "Manage user roles",
77
+ tools: [
78
+ experimental_createTool("SET_ROLE", {
79
+ name: "Set role",
80
+ description: "Set a user's role",
81
+ inputParams: z.object({ user_id: z.string(), role: z.enum(["admin", "developer", "viewer"]) }),
82
+ execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
83
+ }),
84
+ ],
85
+});
86
+```
87
+
88
+### Binding to a Session
89
+
90
+Pass custom tools and toolkits via the `experimental` option when creating a session:
91
+
92
+```ts
93
+// @noErrors
94
+import { Composio } from "@composio/core";
95
+
96
+const session = await new Composio().create("user_123", {
97
+ toolkits: ["gmail"],
98
+ experimental: {
99
+ customTools: [getUser, createDraft],
100
+ customToolkits: [roleManager],
101
+ },
102
+});
103
+
104
+const tools = await session.tools(); // Includes both remote and custom tools
105
+```
106
+
107
+---
108
+
109
+## Limitations
110
+
111
+- **Native tools only** — custom tools work with `session.tools()`. MCP support is coming soon.
112
+- **TypeScript only** — Python support is not yet available.
113
+- **Experimental API** — the `experimental_` prefix and session option may change.
114
+- Tool slugs are auto-prefixed with `LOCAL_` (max 60 characters).
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+19
-19
@@ -1,7 +1,7 @@
1
---
2
-title: "Custom Tools and Toolkits (Beta)"
2
+title: "Custom Tools and Toolkits (Experimental)"
3
description: Define local tools that run in-process alongside remote Composio tools
4
-keywords: [custom tools, custom toolkits, beta, experimental, local tools, proxy execute]
4
+keywords: [custom tools, custom toolkits, experimental, local tools, proxy execute]
5
---
6
7
<Callout type="warn">
@@ -18,11 +18,10 @@ Custom tools let you define local tools that run in-process alongside remote Com
18
19
A tool with no Composio-managed authentication:
20
21
-```ts
22
-// @noErrors
21
+```typescript
22
import { experimental_createTool } from "@composio/core";
24
-import { z } from "zod";
25
-
23
+import { z } from "zod/v3";
24
+// ---cut---
25
const getUser = experimental_createTool("GET_USER", {
26
name: "Get user",
27
description: "Look up an internal user by ID",
@@ -39,11 +38,10 @@ const getUser = experimental_createTool("GET_USER", {
38
39
Inherits authentication from an existing Composio toolkit via `extendsToolkit`. The second argument to `execute` is a `SessionContext` for authenticated API calls:
40
42
-```ts
43
-// @noErrors
41
+```typescript
42
import { experimental_createTool } from "@composio/core";
45
-import { z } from "zod";
46
-
43
+import { z } from "zod/v3";
44
+// ---cut---
45
const createDraft = experimental_createTool("CREATE_DRAFT", {
46
name: "Create Gmail draft",
47
description: "Create a Gmail draft via the Gmail API",
@@ -76,11 +74,10 @@ const createDraft = experimental_createTool("CREATE_DRAFT", {
74
75
Group related tools under a namespace. Tools inside a toolkit must **not** use `extendsToolkit` — they inherit the toolkit identity instead:
76
79
-```ts
80
-// @noErrors
77
+```typescript
78
import { experimental_createTool, experimental_createToolkit } from "@composio/core";
82
-import { z } from "zod";
83
-
79
+import { z } from "zod/v3";
80
+// ---cut---
81
const setRole = experimental_createTool("SET_ROLE", {
82
name: "Set role",
83
description: "Set a user's role",
@@ -102,12 +99,15 @@ const roleManager = experimental_createToolkit("ROLE_MANAGER", {
99
100
Pass custom tools and toolkits via the `experimental` option:
101
105
-```ts
106
-// @noErrors
107
-import { Composio } from "@composio/core";
108
-
109
-const composio = new Composio();
102
+```typescript
103
+import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
104
+import { z } from "zod/v3";
105
106
+const getUser = experimental_createTool("GET_USER", { name: "Get user", description: "Look up user", inputParams: z.object({ user_id: z.string() }), execute: async () => ({ name: "Alice" }) });
107
+const createDraft = experimental_createTool("CREATE_DRAFT", { name: "Create draft", description: "Create draft", extendsToolkit: "gmail", inputParams: z.object({ to: z.string() }), execute: async (input, ctx) => { const res = await ctx.proxyExecute({ toolkit: "gmail", endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts", method: "POST", body: {} }); return res.data as Record<string, unknown>; } });
108
+const roleManager = experimental_createToolkit("ROLE_MANAGER", { name: "Role Manager", description: "Manage roles", tools: [experimental_createTool("SET_ROLE", { name: "Set role", description: "Set role", inputParams: z.object({ user_id: z.string() }), execute: async () => ({ updated: true }) })] });
109
+const composio = new Composio({ apiKey: 'your_api_key' });
110
+// ---cut---
111
const session = await composio.create("user_123", {
112
toolkits: ["gmail"],
113
experimental: {
docs/package.json
+1
-1
@@ -44,7 +44,7 @@
44
"@anthropic-ai/sdk": "^0.71.2",
45
"@composio/anthropic": "^0.5.5",
46
"@composio/claude-agent-sdk": "^0.6.3",
47
- "@composio/core": "^0.6.3",
47
+ "@composio/core": "^0.6.6",
48
"@composio/google": "^0.5.5",
49
"@composio/langchain": "^0.5.5",
50
"@composio/llamaindex": "^0.5.5",