@devries-cameron20 / composio-1 / commits / 26b9d1f35
Fork 0

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",