Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 191 lines 5.88 KB
Raw
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.