Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: move custom tools to toolkits/ as dedicated page
Dhawal Upadhyayb44fe816f618
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdxindex dfcce99e4..be79c7180 100644--- a/docs/content/docs/configuring-sessions.mdx+++ b/docs/content/docs/configuring-sessions.mdx@@ -1,7 +1,7 @@---title: Configuring Sessions-description: Enable toolkits, set auth configs, select connected accounts, and add custom tools-keywords: [session, toolkits, auth configs, connected accounts, custom tools, beta]+description: Enable toolkits, set auth configs, and select connected accounts+keywords: [session, toolkits, auth configs, connected accounts]---## Creating a session@@ -163,122 +163,6 @@ When executing a tool, the connected account is selected in this order:If a user has multiple connected accounts for a toolkit, the most recently connected one is used.-## Custom tools (Beta)--<Callout type="warn">-Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.-</Callout>--Custom tools let you define local tools that run in-process alongside remote Composio tools. There are three patterns:--### Standalone tool--A tool that doesn't need any Composio-managed authentication:--```ts-// @noErrors-import { experimental_createTool } from "@composio/core";-import { z } from "zod";--const getUser = experimental_createTool("GET_USER", {- name: "Get user",- description: "Look up an internal user by ID",- inputParams: z.object({- user_id: z.string().describe("User ID"),- }),- execute: async ({ user_id }) => {- // Your logic here — just return the result- return { name: "Alice", email: "[email protected]" };- },-});-```--### Extension tool--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()`:--```ts-// @noErrors-import { experimental_createTool } from "@composio/core";-import { z } from "zod";--const createDraft = experimental_createTool("CREATE_DRAFT", {- name: "Create Gmail draft",- description: "Create a Gmail draft via the Gmail API",- extendsToolkit: "gmail",- inputParams: z.object({- to: z.string().describe("Recipient email"),- subject: z.string().describe("Email subject"),- body: z.string().describe("Email body"),- }),- execute: async (input, ctx) => {- // proxyExecute routes through the session's Gmail auth- const res = await ctx.proxyExecute({- toolkit: "gmail",- endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",- method: "POST",- body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },- });- return res.data as Record<string, unknown>;- },-});-```--The `SessionContext` (`ctx`) provides:-- **`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 }`).-- **`ctx.execute(toolSlug, args)`** — Execute any Composio native tool from within your custom tool.--### Custom toolkit--Group related tools under a namespace using `experimental_createToolkit`:--```ts-// @noErrors-import { experimental_createTool, experimental_createToolkit } from "@composio/core";-import { z } from "zod";--const setRole = experimental_createTool("SET_ROLE", {- name: "Set role",- description: "Set a user's role",- inputParams: z.object({- user_id: z.string().describe("User ID"),- role: z.enum(["admin", "developer", "viewer"]).describe("New role"),- }),- execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),-});--const roleManager = experimental_createToolkit("ROLE_MANAGER", {- name: "Role Manager",- description: "Manage user roles",- tools: [setRole],-});-```--Tools inside a toolkit must **not** have `extendsToolkit` set — they inherit the toolkit identity instead.--### Binding to a session--Pass custom tools and toolkits via the `experimental` option:--```ts-// @noErrors-import { Composio } from "@composio/core";--const composio = new Composio();--const session = await composio.create("user_123", {- toolkits: ["gmail"],- experimental: {- customTools: [getUser, createDraft],- customToolkits: [roleManager],- },-});--const tools = await session.tools(); // Includes both remote and custom tools-```--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_`.-## Session methods### mcpdiff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdxnew file mode 100644index 000000000..214b97888--- /dev/null+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx@@ -0,0 +1,125 @@+---+title: "Custom Tools and Toolkits (Beta)"+description: Define local tools that run in-process alongside remote Composio tools+keywords: [custom tools, custom toolkits, beta, experimental, local tools, proxy execute]+---++<Callout type="warn">+Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.+</Callout>++Custom tools let you define local tools that run in-process alongside remote Composio tools within a session.++## Standalone tool++A tool with no Composio-managed authentication — just input and an execute function:++```ts+// @noErrors+import { experimental_createTool } from "@composio/core";+import { z } from "zod";++const getUser = experimental_createTool("GET_USER", {+ name: "Get user",+ description: "Look up an internal user by ID",+ inputParams: z.object({+ user_id: z.string().describe("User ID"),+ }),+ execute: async ({ user_id }) => {+ return { name: "Alice", email: "[email protected]" };+ },+});+```++## Extension tool++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:++```ts+// @noErrors+import { experimental_createTool } from "@composio/core";+import { z } from "zod";++const createDraft = experimental_createTool("CREATE_DRAFT", {+ name: "Create Gmail draft",+ description: "Create a Gmail draft via the Gmail API",+ extendsToolkit: "gmail",+ inputParams: z.object({+ to: z.string().describe("Recipient email"),+ subject: z.string().describe("Email subject"),+ body: z.string().describe("Email body"),+ }),+ execute: async (input, ctx) => {+ const res = await ctx.proxyExecute({+ toolkit: "gmail",+ endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",+ method: "POST",+ body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },+ });+ return res.data as Record<string, unknown>;+ },+});+```++### SessionContext++The `ctx` object passed to extension tools provides:++| Method | Description |+|--------|-------------|+| `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 }`). |+| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |++## Custom toolkit++Group related tools under a namespace with `experimental_createToolkit`. Tools inside a toolkit must **not** use `extendsToolkit` — they inherit the toolkit identity instead:++```ts+// @noErrors+import { experimental_createTool, experimental_createToolkit } from "@composio/core";+import { z } from "zod";++const setRole = experimental_createTool("SET_ROLE", {+ name: "Set role",+ description: "Set a user's role",+ inputParams: z.object({+ user_id: z.string().describe("User ID"),+ role: z.enum(["admin", "developer", "viewer"]).describe("New role"),+ }),+ execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),+});++const roleManager = experimental_createToolkit("ROLE_MANAGER", {+ name: "Role Manager",+ description: "Manage user roles",+ tools: [setRole],+});+```++## Binding to a session++Pass custom tools and toolkits via the `experimental` option when creating a session:++```ts+// @noErrors+import { Composio } from "@composio/core";++const composio = new Composio();++const session = await composio.create("user_123", {+ toolkits: ["gmail"],+ experimental: {+ customTools: [getUser, createDraft],+ customToolkits: [roleManager],+ },+});++const tools = await session.tools(); // Includes both remote and custom tools+```++## Slug rules++- Tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` becomes `LOCAL_GET_USER`)+- Toolkit tools get both prefixes (e.g. `LOCAL_ROLE_MANAGER_SET_ROLE`)+- Final slug must not exceed 60 characters+- Slugs cannot start with `LOCAL_` or `COMPOSIO_`diff --git a/docs/content/docs/toolkits/meta.json b/docs/content/docs/toolkits/meta.jsonindex b9790828b..4fae1be95 100644--- a/docs/content/docs/toolkits/meta.json+++ b/docs/content/docs/toolkits/meta.json@@ -2,6 +2,7 @@"title": "Toolkits","pages": ["fetching-tools-and-toolkits",- "enable-and-disable-toolkits"+ "enable-and-disable-toolkits",+ "custom-tools-and-toolkits"]}