Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | | composio | v0.11.4 | |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## What's New |
| 19 | |
| 20 | Custom tools support three patterns — standalone tools for internal logic, extension tools that wrap Composio toolkit APIs with business logic, and custom toolkits that group related tools. TypeScript uses builder functions with Zod schemas; Python uses decorators with Pydantic annotations. |
| 21 | |
| 22 | <Tabs groupId="language" items={['TypeScript', 'Python']} persist> |
| 23 | <Tab value="TypeScript"> |
| 24 | |
| 25 | ```typescript |
| 26 | // @noErrors |
| 27 | import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core"; |
| 28 | import { z } from "zod/v3"; |
| 29 | // ---cut--- |
| 30 | |
| 31 | // Standalone tool — internal data, no Composio auth needed |
| 32 | const getUserProfile = experimental_createTool("GET_USER_PROFILE", { |
| 33 | name: "Get user profile", |
| 34 | description: "Retrieve the current user's profile from the internal directory", |
| 35 | inputParams: z.object({}), |
| 36 | execute: async (_input, ctx) => { |
| 37 | // ctx.userId identifies which user's session is running |
| 38 | const profiles: Record<string, { name: string; tier: string }> = { |
| 39 | "user_1": { name: "Alice Johnson", tier: "enterprise" }, |
| 40 | }; |
| 41 | return profiles[ctx.userId] ?? {}; |
| 42 | }, |
| 43 | }); |
| 44 | |
| 45 | // Extension tool — wraps Gmail with preset business logic |
| 46 | // Inherits auth from the session via extendsToolkit |
| 47 | const sendPromoEmail = experimental_createTool("SEND_PROMO_EMAIL", { |
| 48 | name: "Send promo email", |
| 49 | description: "Send the standard promotional email to a recipient", |
| 50 | extendsToolkit: "gmail", |
| 51 | inputParams: z.object({ to: z.string().describe("Recipient email") }), |
| 52 | execute: async (input, ctx) => { |
| 53 | const raw = btoa(`To: ${input.to}\r\nSubject: Try MyApp Pro\r\n\r\nFree for 14 days.`); |
| 54 | const res = await ctx.proxyExecute({ |
| 55 | toolkit: "gmail", |
| 56 | endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/messages/send", |
| 57 | method: "POST", |
| 58 | body: { raw }, |
| 59 | }); |
| 60 | return { status: res.status, to: input.to }; |
| 61 | }, |
| 62 | }); |
| 63 | |
| 64 | // Custom toolkit — groups related tools under a namespace |
| 65 | const userManagement = experimental_createToolkit("USER_MANAGEMENT", { |
| 66 | name: "User scoping", |
| 67 | description: "Manage user roles and permissions", |
| 68 | tools: [ |
| 69 | experimental_createTool("ASSIGN_ROLE", { |
| 70 | name: "Assign role", |
| 71 | description: "Assign a role to a user in the internal system", |
| 72 | inputParams: z.object({ |
| 73 | user_id: z.string().describe("Target user ID"), |
| 74 | role: z.enum(["admin", "editor", "viewer"]).describe("Role to assign"), |
| 75 | }), |
| 76 | execute: async ({ user_id, role }) => ({ user_id, role, assigned: true }), |
| 77 | }), |
| 78 | ], |
| 79 | }); |
| 80 | |
| 81 | // Bind everything to a session |
| 82 | const composio = new Composio({ apiKey: "your_api_key" }); |
| 83 | const session = await composio.create("user_1", { |
| 84 | toolkits: ["gmail"], |
| 85 | experimental: { |
| 86 | customTools: [getUserProfile, sendPromoEmail], |
| 87 | customToolkits: [userManagement], |
| 88 | }, |
| 89 | }); |
| 90 | |
| 91 | const tools = await session.tools(); // Includes both remote and custom tools |
| 92 | ``` |
| 93 | |
| 94 | </Tab> |
| 95 | <Tab value="Python"> |
| 96 | |
| 97 | ```python |
| 98 | import base64 |
| 99 | |
| 100 | from pydantic import BaseModel, Field |
| 101 | |
| 102 | from composio import Composio |
| 103 | |
| 104 | |
| 105 | composio = Composio(api_key="your_api_key") |
| 106 | |
| 107 | |
| 108 | class UserLookupInput(BaseModel): |
| 109 | user_id: str = Field(description="User ID") |
| 110 | |
| 111 | |
| 112 | @composio.experimental.tool() |
| 113 | def get_user_profile(input: UserLookupInput, ctx): |
| 114 | """Retrieve the current user's profile from the internal directory.""" |
| 115 | profiles = { |
| 116 | "user_1": {"name": "Alice Johnson", "tier": "enterprise"}, |
| 117 | } |
| 118 | return profiles.get(input.user_id, {}) |
| 119 | |
| 120 | |
| 121 | class PromoEmailInput(BaseModel): |
| 122 | to: str = Field(description="Recipient email") |
| 123 | |
| 124 | |
| 125 | @composio.experimental.tool(extends_toolkit="gmail") |
| 126 | def send_promo_email(input: PromoEmailInput, ctx): |
| 127 | """Send the standard promotional email to a recipient.""" |
| 128 | raw = base64.urlsafe_b64encode( |
| 129 | ( |
| 130 | f"To: {input.to}\r\n" |
| 131 | "Subject: Try MyApp Pro\r\n" |
| 132 | "Content-Type: text/plain; charset=UTF-8\r\n\r\n" |
| 133 | "Free for 14 days." |
| 134 | ).encode() |
| 135 | ).decode().rstrip("=") |
| 136 | res = ctx.proxy_execute( |
| 137 | toolkit="gmail", |
| 138 | endpoint="https://gmail.googleapis.com/gmail/v1/users/me/messages/send", |
| 139 | method="POST", |
| 140 | body={"raw": raw}, |
| 141 | ) |
| 142 | return {"status": res.status, "to": input.to} |
| 143 | |
| 144 | |
| 145 | user_management = composio.experimental.Toolkit( |
| 146 | slug="USER_MANAGEMENT", |
| 147 | name="User scoping", |
| 148 | description="Manage user roles and permissions", |
| 149 | ) |
| 150 | |
| 151 | |
| 152 | class AssignRoleInput(BaseModel): |
| 153 | user_id: str = Field(description="Target user ID") |
| 154 | role: str = Field(description="Role to assign") |
| 155 | |
| 156 | |
| 157 | @user_management.tool() |
| 158 | def assign_role(input: AssignRoleInput, ctx): |
| 159 | """Assign a role to a user in the internal system.""" |
| 160 | return {"user_id": input.user_id, "role": input.role, "assigned": True} |
| 161 | |
| 162 | |
| 163 | session = composio.create( |
| 164 | user_id="user_1", |
| 165 | toolkits=["gmail"], |
| 166 | experimental={ |
| 167 | "custom_tools": [get_user_profile, send_promo_email], |
| 168 | "custom_toolkits": [user_management], |
| 169 | }, |
| 170 | ) |
| 171 | |
| 172 | tools = session.tools() # Includes both remote and custom tools |
| 173 | ``` |
| 174 | |
| 175 | </Tab> |
| 176 | </Tabs> |
| 177 | |
| 178 | ### SessionContext |
| 179 | |
| 180 | Every custom tool's `execute` receives `(input, ctx)`: |
| 181 | |
| 182 | - **TypeScript** — `ctx.userId`, `ctx.proxyExecute(params)`, `ctx.execute(toolSlug, args)` |
| 183 | - **Python** — `ctx.user_id`, `ctx.proxy_execute(...)`, `ctx.execute(tool_slug, arguments)` |
| 184 | |
| 185 | --- |
| 186 | |
| 187 | ## Limitations |
| 188 | |
| 189 | - **Native tools only** — custom tools work with `session.tools()`. MCP support is coming soon. |
| 190 | - **Experimental API** — the custom tool APIs and session `experimental` option may change. |
| 191 | - **SDK-specific DX is intentional** — TypeScript uses builder helpers and Zod. Python uses decorators, docstrings, and Pydantic annotations. |