@devries-cameron20 / composio Mirror · read-only / commits / b44fe816f
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 02:00 UTC

docs: move custom tools to toolkits/ as dedicated page

Reverts configuring-sessions.mdx to original state and creates a new custom-tools-and-toolkits.mdx under toolkits/ section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dhawal Upadhyay committed Mar 19, 2026 at 08:59 UTC b44fe816f6183f266c217e4d6d956ae382f5a789
3 files changed +129 -119
docs/content/docs/configuring-sessions.mdx
+2 -118
@@ -1,7 +1,7 @@
1 ---
2 title: Configuring Sessions
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]
3 +description: Enable toolkits, set auth configs, and select connected accounts
4 +keywords: [session, toolkits, auth configs, connected accounts]
5 ---
6
7 ## Creating a session
@@ -163,122 +163,6 @@ 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 -// @noErrors
180 -import { experimental_createTool } from "@composio/core";
181 -import { z } from "zod";
182 -
183 -const getUser = experimental_createTool("GET_USER", {
184 - name: "Get user",
185 - description: "Look up an internal user by ID",
186 - inputParams: z.object({
187 - user_id: z.string().describe("User ID"),
188 - }),
189 - execute: async ({ user_id }) => {
190 - // Your logic here — just return the result
191 - return { name: "Alice", email: "alice@acme.com" };
192 - },
193 -});
194 -```
195 -
196 -### Extension tool
197 -
198 -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()`:
199 -
200 -```ts
201 -// @noErrors
202 -import { experimental_createTool } from "@composio/core";
203 -import { z } from "zod";
204 -
205 -const createDraft = experimental_createTool("CREATE_DRAFT", {
206 - name: "Create Gmail draft",
207 - description: "Create a Gmail draft via the Gmail API",
208 - extendsToolkit: "gmail",
209 - inputParams: z.object({
210 - to: z.string().describe("Recipient email"),
211 - subject: z.string().describe("Email subject"),
212 - body: z.string().describe("Email body"),
213 - }),
214 - execute: async (input, ctx) => {
215 - // proxyExecute routes through the session's Gmail auth
216 - const res = await ctx.proxyExecute({
217 - toolkit: "gmail",
218 - endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
219 - method: "POST",
220 - body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
221 - });
222 - return res.data as Record<string, unknown>;
223 - },
224 -});
225 -```
226 -
227 -The `SessionContext` (`ctx`) provides:
228 -- **`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 }`).
229 -- **`ctx.execute(toolSlug, args)`** — Execute any Composio native tool from within your custom tool.
230 -
231 -### Custom toolkit
232 -
233 -Group related tools under a namespace using `experimental_createToolkit`:
234 -
235 -```ts
236 -// @noErrors
237 -import { experimental_createTool, experimental_createToolkit } from "@composio/core";
238 -import { z } from "zod";
239 -
240 -const setRole = experimental_createTool("SET_ROLE", {
241 - name: "Set role",
242 - description: "Set a user's role",
243 - inputParams: z.object({
244 - user_id: z.string().describe("User ID"),
245 - role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
246 - }),
247 - execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
248 -});
249 -
250 -const roleManager = experimental_createToolkit("ROLE_MANAGER", {
251 - name: "Role Manager",
252 - description: "Manage user roles",
253 - tools: [setRole],
254 -});
255 -```
256 -
257 -Tools inside a toolkit must **not** have `extendsToolkit` set — they inherit the toolkit identity instead.
258 -
259 -### Binding to a session
260 -
261 -Pass custom tools and toolkits via the `experimental` option:
262 -
263 -```ts
264 -// @noErrors
265 -import { Composio } from "@composio/core";
266 -
267 -const composio = new Composio();
268 -
269 -const session = await composio.create("user_123", {
270 - toolkits: ["gmail"],
271 - experimental: {
272 - customTools: [getUser, createDraft],
273 - customToolkits: [roleManager],
274 - },
275 -});
276 -
277 -const tools = await session.tools(); // Includes both remote and custom tools
278 -```
279 -
280 -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_`.
281 -
166 ## Session methods
167
168 ### mcp
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx new
+125
@@ -0,0 +1,125 @@
1 +---
2 +title: "Custom Tools and Toolkits (Beta)"
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]
5 +---
6 +
7 +<Callout type="warn">
8 +Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
9 +</Callout>
10 +
11 +Custom tools let you define local tools that run in-process alongside remote Composio tools within a session.
12 +
13 +## Standalone tool
14 +
15 +A tool with no Composio-managed authentication — just input and an execute function:
16 +
17 +```ts
18 +// @noErrors
19 +import { experimental_createTool } from "@composio/core";
20 +import { z } from "zod";
21 +
22 +const getUser = experimental_createTool("GET_USER", {
23 + name: "Get user",
24 + description: "Look up an internal user by ID",
25 + inputParams: z.object({
26 + user_id: z.string().describe("User ID"),
27 + }),
28 + execute: async ({ user_id }) => {
29 + return { name: "Alice", email: "alice@acme.com" };
30 + },
31 +});
32 +```
33 +
34 +## Extension tool
35 +
36 +A tool that inherits authentication from an existing Composio toolkit via `extendsToolkit`. The second argument to `execute` is a `SessionContext` that lets you make authenticated API calls or invoke other tools:
37 +
38 +```ts
39 +// @noErrors
40 +import { experimental_createTool } from "@composio/core";
41 +import { z } from "zod";
42 +
43 +const createDraft = experimental_createTool("CREATE_DRAFT", {
44 + name: "Create Gmail draft",
45 + description: "Create a Gmail draft via the Gmail API",
46 + extendsToolkit: "gmail",
47 + inputParams: z.object({
48 + to: z.string().describe("Recipient email"),
49 + subject: z.string().describe("Email subject"),
50 + body: z.string().describe("Email body"),
51 + }),
52 + execute: async (input, ctx) => {
53 + const res = await ctx.proxyExecute({
54 + toolkit: "gmail",
55 + endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
56 + method: "POST",
57 + body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
58 + });
59 + return res.data as Record<string, unknown>;
60 + },
61 +});
62 +```
63 +
64 +### SessionContext
65 +
66 +The `ctx` object passed to extension tools provides:
67 +
68 +| Method | Description |
69 +|--------|-------------|
70 +| `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 }`). |
71 +| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |
72 +
73 +## Custom toolkit
74 +
75 +Group related tools under a namespace with `experimental_createToolkit`. Tools inside a toolkit must **not** use `extendsToolkit` — they inherit the toolkit identity instead:
76 +
77 +```ts
78 +// @noErrors
79 +import { experimental_createTool, experimental_createToolkit } from "@composio/core";
80 +import { z } from "zod";
81 +
82 +const setRole = experimental_createTool("SET_ROLE", {
83 + name: "Set role",
84 + description: "Set a user's role",
85 + inputParams: z.object({
86 + user_id: z.string().describe("User ID"),
87 + role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
88 + }),
89 + execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
90 +});
91 +
92 +const roleManager = experimental_createToolkit("ROLE_MANAGER", {
93 + name: "Role Manager",
94 + description: "Manage user roles",
95 + tools: [setRole],
96 +});
97 +```
98 +
99 +## Binding to a session
100 +
101 +Pass custom tools and toolkits via the `experimental` option when creating a session:
102 +
103 +```ts
104 +// @noErrors
105 +import { Composio } from "@composio/core";
106 +
107 +const composio = new Composio();
108 +
109 +const session = await composio.create("user_123", {
110 + toolkits: ["gmail"],
111 + experimental: {
112 + customTools: [getUser, createDraft],
113 + customToolkits: [roleManager],
114 + },
115 +});
116 +
117 +const tools = await session.tools(); // Includes both remote and custom tools
118 +```
119 +
120 +## Slug rules
121 +
122 +- Tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` becomes `LOCAL_GET_USER`)
123 +- Toolkit tools get both prefixes (e.g. `LOCAL_ROLE_MANAGER_SET_ROLE`)
124 +- Final slug must not exceed 60 characters
125 +- Slugs cannot start with `LOCAL_` or `COMPOSIO_`
docs/content/docs/toolkits/meta.json
+2 -1
@@ -2,6 +2,7 @@
2 "title": "Toolkits",
3 "pages": [
4 "fetching-tools-and-toolkits",
5 - "enable-and-disable-toolkits"
5 + "enable-and-disable-toolkits",
6 + "custom-tools-and-toolkits"
7 ]
8 }