@devries-cameron20 / composio Mirror · read-only / commits / 7266213a4
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: 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