@devries-cameron20 / composio-1 / commits / f278e6272
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.

docs: add python custom tools docs

Dhawal Upadhyay committed Mar 25, 2026 at 15:15 UTC f278e6272d1cc15f90c3670ae08cfe0bd2b9c588
2 files changed +219 -11
docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx
+93 -6
@@ -11,12 +11,16 @@ You can now create custom tools and toolkits that run locally alongside remote C
11 | Package | Version |
12 |---------|---------|
13 | @composio/core | v0.6.6 |
14 +| composio | v0.11.4 |
15
16 ---
17
18 ## What's New
19
19 -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.
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 import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
@@ -86,18 +90,101 @@ const session = await composio.create("user_1", {
90 const tools = await session.tools(); // Includes both remote and custom tools
91 ```
92
93 +</Tab>
94 +<Tab value="Python">
95 +
96 +```python
97 +import base64
98 +
99 +from pydantic import BaseModel, Field
100 +
101 +from composio import Composio
102 +
103 +
104 +composio = Composio(api_key="your_api_key")
105 +
106 +
107 +class UserLookupInput(BaseModel):
108 + user_id: str = Field(description="User ID")
109 +
110 +
111 +@composio.experimental.tool()
112 +def get_user_profile(input: UserLookupInput, ctx):
113 + """Retrieve the current user's profile from the internal directory."""
114 + profiles = {
115 + "user_1": {"name": "Alice Johnson", "tier": "enterprise"},
116 + }
117 + return profiles.get(input.user_id, {})
118 +
119 +
120 +class PromoEmailInput(BaseModel):
121 + to: str = Field(description="Recipient email")
122 +
123 +
124 +@composio.experimental.tool(extends_toolkit="gmail")
125 +def send_promo_email(input: PromoEmailInput, ctx):
126 + """Send the standard promotional email to a recipient."""
127 + raw = base64.urlsafe_b64encode(
128 + (
129 + f"To: {input.to}\r\n"
130 + "Subject: Try MyApp Pro\r\n"
131 + "Content-Type: text/plain; charset=UTF-8\r\n\r\n"
132 + "Free for 14 days."
133 + ).encode()
134 + ).decode().rstrip("=")
135 + res = ctx.proxy_execute(
136 + toolkit="gmail",
137 + endpoint="https://gmail.googleapis.com/gmail/v1/users/me/messages/send",
138 + method="POST",
139 + body={"raw": raw},
140 + )
141 + return {"status": res.status, "to": input.to}
142 +
143 +
144 +user_management = composio.experimental.Toolkit(
145 + slug="USER_MANAGEMENT",
146 + name="User management",
147 + description="Manage user roles and permissions",
148 +)
149 +
150 +
151 +class AssignRoleInput(BaseModel):
152 + user_id: str = Field(description="Target user ID")
153 + role: str = Field(description="Role to assign")
154 +
155 +
156 +@user_management.tool()
157 +def assign_role(input: AssignRoleInput, ctx):
158 + """Assign a role to a user in the internal system."""
159 + return {"user_id": input.user_id, "role": input.role, "assigned": True}
160 +
161 +
162 +session = composio.create(
163 + user_id="user_1",
164 + toolkits=["gmail"],
165 + experimental={
166 + "custom_tools": [get_user_profile, send_promo_email],
167 + "custom_toolkits": [user_management],
168 + },
169 +)
170 +
171 +tools = session.tools() # Includes both remote and custom tools
172 +```
173 +
174 +</Tab>
175 +</Tabs>
176 +
177 ### SessionContext
178
179 Every custom tool's `execute` receives `(input, ctx)`:
180
93 -- **`ctx.userId`** — the user ID for the current session
94 -- **`ctx.proxyExecute(params)`** — authenticated HTTP request via Composio's auth layer
95 -- **`ctx.execute(toolSlug, args)`** — execute any Composio native tool from within your custom tool
181 +- **TypeScript** — `ctx.userId`, `ctx.proxyExecute(params)`, `ctx.execute(toolSlug, args)`
182 +- **Python** — `ctx.user_id`, `ctx.proxy_execute(...)`, `ctx.execute(tool_slug, arguments)`
183
184 ---
185
186 ## Limitations
187
188 - **Native tools only** — custom tools work with `session.tools()`. MCP support is coming soon.
102 -- **TypeScript only** — Python support is not yet available.
103 -- **Experimental API** — the `experimental_` prefix and session option may change.
\ No newline at end of file
189 +- **Experimental API** — the custom tool APIs and session `experimental` option may change.
190 +- **SDK-specific DX is intentional** — TypeScript uses builder helpers and Zod. Python uses decorators, docstrings, and Pydantic annotations.
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+126 -5
@@ -5,7 +5,7 @@ keywords: [custom tools, custom toolkits, experimental, local tools, proxy execu
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.
8 +Custom tool APIs are experimental. TypeScript uses `experimental_createTool()` / `experimental_createToolkit()`. Python uses `@composio.experimental.tool()` / `composio.experimental.Toolkit(...)`. The session `experimental` option may change in future releases.
9 </Callout>
10
11 <Callout type="info">
@@ -15,11 +15,14 @@ Custom tools work with **native tools** (`session.tools()`). MCP support is comi
15 Custom tools let you define tools that run in-process alongside remote Composio tools within a session. There are three patterns:
16
17 - **Standalone tools** — for internal app logic that doesn't need Composio auth (DB lookups, in-memory data, business rules)
18 -- **Extension tools** — wrap a Composio toolkit's API with custom business logic via `extendsToolkit`, using `ctx.proxyExecute()` for authenticated requests
18 +- **Extension tools** — wrap a Composio toolkit's API with custom business logic via `extendsToolkit` / `extends_toolkit`, using `ctx.proxyExecute()` / `ctx.proxy_execute()` for authenticated requests
19 - **Custom toolkits** — group related standalone tools under a namespace
20
21 The example below defines one of each and binds them to a session:
22
23 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
24 +<Tab value="TypeScript">
25 +
26 ```typescript
27 import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
28 import { z } from "zod/v3";
@@ -104,6 +107,102 @@ const session = await composio.create("user_1", {
107 const tools = await session.tools();
108 ```
109
110 +</Tab>
111 +<Tab value="Python">
112 +
113 +```python
114 +import base64
115 +
116 +from pydantic import BaseModel, Field
117 +
118 +from composio import Composio
119 +
120 +
121 +composio = Composio(api_key="your_api_key")
122 +
123 +
124 +class UserLookupInput(BaseModel):
125 + user_id: str = Field(description="User ID")
126 +
127 +
128 +USERS = {
129 + "user_1": {"name": "Alice Johnson", "email": "alice@myapp.com", "tier": "enterprise"},
130 + "user_2": {"name": "Bob Smith", "email": "bob@myapp.com", "tier": "free"},
131 +}
132 +
133 +
134 +@composio.experimental.tool()
135 +def get_user_profile(input: UserLookupInput, ctx):
136 + """Retrieve the current user's profile from the internal directory."""
137 + profile = USERS.get(input.user_id)
138 + if not profile:
139 + raise ValueError(f'No profile found for user "{input.user_id}"')
140 + return profile
141 +
142 +
143 +class PromoEmailInput(BaseModel):
144 + to: str = Field(description="Recipient email address")
145 +
146 +
147 +@composio.experimental.tool(extends_toolkit="gmail")
148 +def send_promo_email(input: PromoEmailInput, ctx):
149 + """Send the standard promotional email to a recipient."""
150 + subject = "You're invited to try MyApp Pro"
151 + body = (
152 + "Hi there,\n\n"
153 + "We'd love for you to try MyApp Pro — free for 14 days.\n\n"
154 + "Best,\nThe MyApp Team"
155 + )
156 + raw_msg = (
157 + f"To: {input.to}\r\n"
158 + f"Subject: {subject}\r\n"
159 + "Content-Type: text/plain; charset=UTF-8\r\n\r\n"
160 + f"{body}"
161 + )
162 + raw = base64.urlsafe_b64encode(raw_msg.encode()).decode().rstrip("=")
163 +
164 + res = ctx.proxy_execute(
165 + toolkit="gmail",
166 + endpoint="https://gmail.googleapis.com/gmail/v1/users/me/messages/send",
167 + method="POST",
168 + body={"raw": raw},
169 + )
170 + return {"status": res.status, "to": input.to}
171 +
172 +
173 +user_management = composio.experimental.Toolkit(
174 + slug="USER_MANAGEMENT",
175 + name="User management",
176 + description="Manage user roles and permissions",
177 +)
178 +
179 +
180 +class AssignRoleInput(BaseModel):
181 + user_id: str = Field(description="Target user ID")
182 + role: str = Field(description="Role to assign")
183 +
184 +
185 +@user_management.tool()
186 +def assign_role(input: AssignRoleInput, ctx):
187 + """Assign a role to a user in the internal system."""
188 + return {"user_id": input.user_id, "role": input.role, "assigned": True}
189 +
190 +
191 +session = composio.create(
192 + user_id="user_1",
193 + toolkits=["gmail"],
194 + experimental={
195 + "custom_tools": [get_user_profile, send_promo_email],
196 + "custom_toolkits": [user_management],
197 + },
198 +)
199 +
200 +tools = session.tools()
201 +```
202 +
203 +</Tab>
204 +</Tabs>
205 +
206 ## How custom tools work with meta tools
207
208 Custom tools integrate seamlessly with Composio's meta tools:
@@ -116,16 +215,17 @@ Custom tools integrate seamlessly with Composio's meta tools:
215
216 ## Best practices
217
119 -- **Descriptive names and slugs** — The agent sees your tool's name and description to decide when to use it. Be specific: "Send weekly promo email" is better than "Send email". Slugs should be uppercase with underscores: `SEND_PROMO_EMAIL`.
218 +- **Descriptive names and slugs** — The agent sees your tool's name and description to decide when to use it. Be specific: "Send weekly promo email" is better than "Send email". In TypeScript, define uppercase slugs like `SEND_PROMO_EMAIL`. In Python, inferred slugs come from the function name, so `snake_case` function names produce the cleanest defaults; or pass `slug=` / `name=` explicitly.
219 - **Detailed descriptions** — Include what the tool does, when to use it, and what it returns. The agent relies on this to pick the right tool.
121 -- **Use `extendsToolkit` for auth** — If your tool needs Gmail/GitHub/etc. auth for `ctx.proxyExecute()` or `ctx.execute()`, set `extendsToolkit` so connection management is handled seamlessly via `COMPOSIO_MANAGE_CONNECTIONS`.
220 +- **Use `extendsToolkit` / `extends_toolkit` for auth** — If your tool needs Gmail/GitHub/etc. auth for `ctx.proxyExecute()` / `ctx.proxy_execute()` or `ctx.execute()`, set the toolkit extension so connection management is handled seamlessly via `COMPOSIO_MANAGE_CONNECTIONS`.
221 +- **In Python, annotations are the schema** — The first parameter must be a Pydantic `BaseModel`, and its field descriptions become the input schema. Docstrings are used as the default tool description unless you pass `description=`.
222 - **Tool names get prefixed** — Slugs exposed to the agent are automatically prefixed with `LOCAL_` and the toolkit name (if any). `GET_USER_PROFILE` becomes `LOCAL_GET_USER_PROFILE`, `ASSIGN_ROLE` in `USER_MANAGEMENT` becomes `LOCAL_USER_MANAGEMENT_ASSIGN_ROLE`. Your slugs cannot start with `LOCAL_` — this prefix is reserved.
223
224 For more best practices, see [How to Build Tools for AI Agents: A Field Guide](https://composio.dev/blog/how-to-build-tools-for-ai-agents-a-field-guide).
225
226 ## Verifying registration
227
128 -Use `session.customTools()` to list registered tools (with their final `LOCAL_` prefixed slugs), or filter by toolkit with `session.customTools({ toolkit: "USER_MANAGEMENT" })`. Use `session.customToolkits()` to list registered toolkits.
228 +Use `session.customTools()` / `session.customToolkits()` in TypeScript or `session.custom_tools()` / `session.custom_toolkits()` in Python to list registered tools and toolkits. Registered tool slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.
229
230 ## Programmatic execution
231
@@ -135,8 +235,29 @@ Use `session.execute()` to run custom tools directly, outside of an agent loop (
235
236 Every custom tool's `execute` function receives `(input, ctx)`. The `ctx` object provides:
237
238 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
239 +<Tab value="TypeScript">
240 +
241 | Method | Description |
242 |--------|-------------|
243 | `ctx.userId` | The user ID for the current session. |
244 | `ctx.proxyExecute(params)` | Authenticated HTTP request via Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body?`, `parameters?` (array of `{ in: "query" \| "header", name, value }`). |
245 | `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |
246 +
247 +</Tab>
248 +<Tab value="Python">
249 +
250 +| Method | Description |
251 +|--------|-------------|
252 +| `ctx.user_id` | The user ID for the current session. |
253 +| `ctx.proxy_execute(...)` | Authenticated HTTP request via Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body=None`, `parameters=[{"type": "query" \| "header", "name": ..., "value": ...}]`. |
254 +| `ctx.execute(tool_slug, arguments)` | Execute any Composio native tool from within your custom tool. |
255 +
256 +</Tab>
257 +</Tabs>
258 +
259 +## Related reference
260 +
261 +- [Tool Router API Reference](/reference/api-reference/tool-router)
262 +- [TypeScript ToolRouterSession Reference](/reference/sdk-reference/typescript/tool-router-session)
263 +- [Python SDK Reference](/reference/sdk-reference/python)