1
---
2
-title: Custom Tools and Toolkits
2
+title: Local Tools and Toolkits
3
description: Define local tools that run in-process alongside remote Composio tools
4
-keywords: [custom tools, custom toolkits, experimental, local tools, proxy execute]
4
+keywords: [local tools, local toolkits, custom tools, custom toolkits, experimental, proxy execute]
5
experimental: true
6
---
7
9
10
If you already have your own tool definitions, start with [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). You can call the authenticated proxy from your code without adopting the experimental session-extension API below.
11
12
-Custom tools let you define tools that run in-process alongside remote Composio tools within a session. You have three patterns:
12
+Local tools let you define tools that run in-process alongside remote Composio tools within a session. You have three patterns:
13
14
- **Standalone tools**: internal app logic that doesn't need Composio auth (DB lookups, in-memory data, business rules).
15
- **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.
16
-- **Custom toolkits**: group related standalone tools under a namespace.
16
+- **Local toolkits**: group related standalone tools under a namespace.
17
+
18
+Local tools were previously called custom tools. The SDK options keep their names: `customTools` / `custom_tools` and `customToolkits` / `custom_toolkits`.
19
20
<IntegrationTabs tabs={[
21
{ value: "standalone", label: "Standalone Tool" },
22
{ value: "extension", label: "Extension Tool" },
21
- { value: "toolkit", label: "Custom Toolkit" },
23
+ { value: "toolkit", label: "Local Toolkit" },
24
]}>
25
26
<IntegrationContent value="standalone">
65
66
A standalone tool handles internal app logic that doesn't need Composio auth. `ctx.userId` identifies which user's session is running.
67
66
-{/* code-example: no-api reason="custom tool handlers are defined and run in-process in the SDK" */}
68
+{/* code-example: no-api reason="local tool handlers are defined and run in-process in the SDK" */}
69
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
70
<Tab value="Python">
71
```python
124
<Step>
125
**Bind to a session**
126
125
-Pass custom tools via the `experimental` option. `session.tools()` returns both remote Composio tools and your custom tools.
127
+Pass local tools via the `experimental` option. `session.tools()` returns both remote Composio tools and your local tools.
128
129
{/* code-example: no-api reason="binding custom tools needs the SDK to serialize their schemas and run their handlers locally" */}
130
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
294
<Step>
295
**Bind to a session**
296
295
-Pass custom tools via the `experimental` option. Extension tools inherit auth from the toolkit specified in `extendsToolkit`.
297
+Pass local tools via the `experimental` option. Extension tools inherit auth from the toolkit specified in `extendsToolkit`.
298
299
{/* code-example: no-api reason="binding custom tools needs the SDK to serialize their schemas and run their handlers locally" */}
300
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
379
<Step>
380
**Create the toolkit**
381
380
-A custom toolkit groups related standalone tools under a namespace. Tools inside a toolkit cannot use `extendsToolkit`.
382
+A local toolkit groups related standalone tools under a namespace. Tools inside a toolkit cannot use `extendsToolkit`.
383
382
-{/* code-example: no-api reason="custom toolkits and their tool handlers are defined in-process in the SDK" */}
384
+{/* code-example: no-api reason="local toolkits and their tool handlers are defined in-process in the SDK" */}
385
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
386
<Tab value="Python">
387
```python
444
<Step>
445
**Bind to a session**
446
445
-Pass custom toolkits via the `experimental` option. `session.tools()` returns both remote Composio tools and your custom toolkit's tools.
447
+Pass local toolkits via the `experimental` option. `session.tools()` returns both remote Composio tools and your local toolkit's tools.
448
449
{/* code-example: no-api reason="binding custom toolkits needs the SDK to serialize their schemas and run their handlers locally" */}
450
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
489
490
</IntegrationTabs>
491
490
-## Preloading custom tools
492
+## Preloading local tools
493
492
-Custom tools are searchable by default. Set `preload: true` / `preload=True` on a
493
-custom tool when it should be returned directly from `session.tools()`. Toolkit
494
+Local tools are searchable by default. Set `preload: true` / `preload=True` on a
495
+local tool when it should be returned directly from `session.tools()`. Toolkit
496
preload applies to all tools in that toolkit; set `preload: false` /
497
`preload=False` on one tool to opt it out.
498
497
-{/* code-example: no-api reason="preload is a property of SDK-defined custom tools whose handlers run in-process" */}
499
+{/* code-example: no-api reason="preload is a property of SDK-defined local tools whose handlers run in-process" */}
500
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
501
<Tab value="Python">
502
```python
573
574
## Meta tools integration
575
574
-Custom tools work automatically with Composio's meta tools:
576
+Local tools work automatically with Composio's meta tools:
577
578
| Meta tool | Behavior |
579
|-----------|----------|
578
-| `COMPOSIO_SEARCH_TOOLS` | Includes custom tools in search results, with slight priority for tools that don't require auth |
579
-| `COMPOSIO_GET_TOOL_SCHEMAS` | Returns schemas for custom tools alongside remote tools |
580
-| `COMPOSIO_MULTI_EXECUTE_TOOL` | Runs custom tools in-process while remote tools go to the backend, merging results transparently |
580
+| `COMPOSIO_SEARCH_TOOLS` | Includes local tools in search results, with slight priority for tools that don't require auth |
581
+| `COMPOSIO_GET_TOOL_SCHEMAS` | Returns schemas for local tools alongside remote tools |
582
+| `COMPOSIO_MULTI_EXECUTE_TOOL` | Runs local tools in-process while remote tools go to the backend, merging results transparently |
583
| `COMPOSIO_MANAGE_CONNECTIONS` | Handles auth for extension tools. If a tool extends `gmail`, the agent can prompt the user to connect Gmail |
584
585
<Callout type="info">
584
-Custom tools are not supported in the sandbox.
586
+Local tools are not supported in the sandbox.
587
</Callout>
588
589
## Context object (`ctx`)
590
589
-Every custom tool's `execute` function receives `(input, ctx)`. Use `ctx` to access the current user, make authenticated API requests, or call other Composio tools.
591
+Every local tool's `execute` function receives `(input, ctx)`. Use `ctx` to access the current user, make authenticated API requests, or call other Composio tools.
592
593
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
594
<Tab value="Python">
597
|-------------------|-------------|
598
| `ctx.user_id` | The userID for the current session |
599
| `ctx.proxy_execute(toolkit, endpoint, method, body=None, parameters=[])` | Make an authenticated HTTP request via Composio's auth layer |
598
-| `ctx.execute(tool_slug, arguments)` | Execute any Composio native tool from within your custom tool |
600
+| `ctx.execute(tool_slug, arguments)` | Execute any Composio native tool from within your local tool |
601
602
</Tab>
603
<Tab value="TypeScript">
606
|-------------------|-------------|
607
| `ctx.userId` | The userID for the current session |
608
| `ctx.proxyExecute({ toolkit, endpoint, method, body?, parameters? })` | Make an authenticated HTTP request via Composio's auth layer |
607
-| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool |
609
+| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your local tool |
610
611
</Tab>
612
</Tabs>
637
</Tab>
638
</Tabs>
639
638
-## Reusing a session with custom tools
640
+## Reusing a session with local tools
641
640
-When [reusing a session](/docs/how-composio-works#how-sessions-behave) via `composio.use()`, you can attach custom tools at the same time:
642
+When [reusing a session](/docs/how-composio-works#how-sessions-behave) via `composio.use()`, you can attach local tools at the same time:
643
642
-{/* code-example: no-api reason="attaching custom tools on use() needs the SDK to run their handlers locally" */}
644
+{/* code-example: no-api reason="attaching local tools on use() needs the SDK to run their handlers locally" */}
645
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
646
<Tab value="Python">
647
```python
673
674
## Programmatic execution
675
674
-Use `session.execute()` to run custom tools directly, outside of an agent loop. Custom tools execute in-process; remote tools are sent to the backend automatically.
676
+Use `session.execute()` to run local tools directly, outside of an agent loop. Local tools execute in-process; remote tools are sent to the backend automatically.
677
676
-{/* code-example: no-api reason="custom tools execute in-process in the SDK, not on the backend" */}
678
+{/* code-example: no-api reason="local tools execute in-process in the SDK, not on the backend" */}
679
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
680
<Tab value="Python">
681
```python
718
719
Your slugs cannot start with `LOCAL_`. This prefix is reserved.
720
719
-Use the final `LOCAL_*` slug when you call a custom tool directly. The original slug still works
720
-when it identifies exactly one local tool. If two custom toolkits both define `SEARCH`, call
721
+Use the final `LOCAL_*` slug when you call a local tool directly. The original slug still works
722
+when it identifies exactly one local tool. If two local toolkits both define `SEARCH`, call
723
`LOCAL_CATALOG_SEARCH` or `LOCAL_SUPPORT_SEARCH`. Calling `SEARCH` directly raises an error with the
724
qualified slugs instead of choosing one toolkit silently.
725