Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(core): accept a boolean proxyExecute shorthand on sessions
jkomyno committed
Oct 13, 2026 at 18:26 UTC
d66e5ded270073bf71a66141fb5459c1c8621c71
9 files changed
+126
-33
.changeset/session-proxy-execute-option.md
+1
-1
@@ -2,4 +2,4 @@
2
'@composio/core': patch
3
---
4
5
-Add a `proxyExecute` session option. `composio.sessions.create(userId, { proxyExecute: { enable: true } })` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, which lets the agent call a toolkit's API directly with the user's connected account. `session.update()` accepts the same option, and `null` removes the stored value. `enable: false` also turns off the sandbox `proxy_execute()` helper, and the API rejects it at creation together with `sandbox.enableProxyExecution: true`.
5
+Add a `proxyExecute` session option. `composio.sessions.create(userId, { proxyExecute: true })` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, which lets the agent call a toolkit's API directly with the user's connected account. A boolean is shorthand for `{ enable: boolean }`. `session.update()` accepts the same option, and `null` removes the stored value. `proxyExecute: false` also turns off the sandbox `proxy_execute()` helper, and the API rejects it at creation together with `sandbox.enableProxyExecution: true`.
python/composio/core/models/tool_router.py
+20
-11
@@ -337,6 +337,15 @@ def _preloads_all_custom_tools(
337
return tools == PRELOAD_TOOLS_ALL
338
339
340
+def _proxy_execute_payload(
341
+ proxy_execute: t.Union[bool, ToolRouterProxyExecuteConfig],
342
+) -> ToolRouterProxyExecuteConfig:
343
+ """Expand the ``proxy_execute`` bool shorthand to the API block."""
344
+ if isinstance(proxy_execute, bool):
345
+ return {"enable": proxy_execute}
346
+ return proxy_execute
347
+
348
+
349
def _apply_session_preset_defaults(
350
session_preset: t.Optional[SessionPreset],
351
manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],
@@ -726,7 +735,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
735
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
736
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
737
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
729
- proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
738
+ proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
739
preload: t.Optional[ToolRouterPreloadConfig] = None,
740
session_preset: t.Optional[SessionPreset] = None,
741
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -756,7 +765,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
765
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
766
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
767
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
759
- proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
768
+ proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
769
preload: t.Optional[ToolRouterPreloadConfig] = None,
770
session_preset: t.Optional[SessionPreset] = None,
771
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -785,7 +794,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
794
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
795
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
796
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
788
- proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
797
+ proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
798
preload: t.Optional[ToolRouterPreloadConfig] = None,
799
session_preset: t.Optional[SessionPreset] = None,
800
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -897,13 +906,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
906
it directly from session.tools(); otherwise custom tools
907
remain search-only.
908
Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}
900
- :param proxy_execute: Optional proxy execute configuration
901
- (ToolRouterProxyExecuteConfig). ``{"enable": True}`` exposes
902
- the ``COMPOSIO_PROXY_EXECUTE`` meta tool. ``{"enable": False}``
903
- also turns off the sandbox ``proxy_execute()`` helper, and the
904
- API rejects it together with
905
- ``sandbox={"enable_proxy_execution": True}``. Leaving it
906
- out keeps the meta tool off.
909
+ :param proxy_execute: Optional proxy execute configuration: a bool or
910
+ ``ToolRouterProxyExecuteConfig``; ``True`` is shorthand for
911
+ ``{"enable": True}``. ``True`` exposes the
912
+ ``COMPOSIO_PROXY_EXECUTE`` meta tool. ``False`` also turns off
913
+ the sandbox ``proxy_execute()`` helper, and the API rejects it
914
+ together with ``sandbox={"enable_proxy_execution": True}``.
915
+ Leaving it out keeps the meta tool off.
916
:param instant: Experimental Instant usage policy. The project
917
must allow Instant usage. ``False`` disables it for this
918
Session; a policy can restrict eligible toolkits and tools.
@@ -1103,7 +1112,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1112
if instant is not None:
1113
create_params["instant"] = instant
1114
if proxy_execute is not None:
1106
- create_params["proxy_execute"] = proxy_execute
1115
+ create_params["proxy_execute"] = _proxy_execute_payload(proxy_execute)
1116
1117
# Build connections config
1118
connections_config: t.Dict[str, t.Any] = {
python/composio/core/models/tool_router_session.py
+10
-4
@@ -1158,7 +1158,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1158
t.Optional[ToolRouterUpdateMultiAccountConfig],
1159
"Omit",
1160
] = omit,
1161
- proxy_execute: t.Union[t.Optional[ToolRouterProxyExecuteConfig], "Omit"] = omit,
1161
+ proxy_execute: t.Union[
1162
+ t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]], "Omit"
1163
+ ] = omit,
1164
preload: t.Union[t.Optional[session_patch_params.Preload], "Omit"] = omit,
1165
search: t.Union[t.Optional[session_patch_params.Search], "Omit"] = omit,
1166
execute: t.Union[t.Optional[session_patch_params.Execute], "Omit"] = omit,
@@ -1182,8 +1184,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1184
access or an object to set its filters; it does not accept ``None``.
1185
Any object, even one that only sets ``return_instant_charge``,
1186
re-enables Instant usage on a Session set to ``False``.
1185
- ``proxy_execute`` is sent as given: ``{"enable": True}`` exposes the
1186
- ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``{"enable": False}`` also turns
1187
+ ``proxy_execute`` takes a bool or ``{"enable": bool}``; ``True``
1188
+ exposes the ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``False`` also turns
1189
off the sandbox ``proxy_execute()`` helper, and ``None`` removes the
1190
stored block.
1191
@@ -1277,7 +1279,11 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1279
t.Union[t.Optional[session_patch_params.MultiAccount], "Omit"],
1280
multi_account,
1281
),
1280
- proxy_execute=proxy_execute,
1282
+ proxy_execute=(
1283
+ {"enable": proxy_execute}
1284
+ if isinstance(proxy_execute, bool)
1285
+ else proxy_execute
1286
+ ),
1287
preload=t.cast(t.Union[session_patch_params.Preload, "Omit"], preload),
1288
search=t.cast(t.Union[session_patch_params.Search, "Omit"], search),
1289
execute=t.cast(t.Union[session_patch_params.Execute, "Omit"], execute),
python/tests/test_tool_router.py
+24
-7
@@ -185,13 +185,21 @@ class TestToolRouter:
185
# Verify API was called
186
mock_client.tool_router.session.create.assert_called_once()
187
188
- @pytest.mark.parametrize("proxy_execute", [{"enable": True}, {"enable": False}])
189
- def test_create_sends_proxy_execute_as_given(
190
- self, tool_router, mock_client, proxy_execute
188
+ @pytest.mark.parametrize(
189
+ ("proxy_execute", "expected"),
190
+ [
191
+ ({"enable": True}, {"enable": True}),
192
+ ({"enable": False}, {"enable": False}),
193
+ (True, {"enable": True}),
194
+ (False, {"enable": False}),
195
+ ],
196
+ )
197
+ def test_create_sends_proxy_execute_block(
198
+ self, tool_router, mock_client, proxy_execute, expected
199
):
200
tool_router.create(user_id="user_123", proxy_execute=proxy_execute)
201
kwargs = mock_client.tool_router.session.create.call_args.kwargs
194
- assert kwargs["proxy_execute"] == proxy_execute
202
+ assert kwargs["proxy_execute"] == expected
203
204
def test_create_omits_proxy_execute_by_default(self, tool_router, mock_client):
205
tool_router.create(user_id="user_123")
@@ -3209,12 +3217,21 @@ class TestSessionUpdateContract:
3217
assert session.config_version == 7
3218
3219
@pytest.mark.parametrize(
3212
- "proxy_execute", [{"enable": True}, {"enable": False}, None]
3220
+ ("proxy_execute", "expected"),
3221
+ [
3222
+ ({"enable": True}, {"enable": True}),
3223
+ ({"enable": False}, {"enable": False}),
3224
+ (True, {"enable": True}),
3225
+ (False, {"enable": False}),
3226
+ (None, None),
3227
+ ],
3228
)
3214
- def test_proxy_execute_is_sent_as_given(self, session, mock_client, proxy_execute):
3229
+ def test_proxy_execute_is_sent_as_block(
3230
+ self, session, mock_client, proxy_execute, expected
3231
+ ):
3232
session.update(proxy_execute=proxy_execute)
3233
kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3217
- assert kwargs["proxy_execute"] == proxy_execute
3234
+ assert kwargs["proxy_execute"] == expected
3235
3236
def test_proxy_execute_is_omitted_by_default(self, session, mock_client):
3237
session.update(toolkits={"enable": ["gmail"]})
ts/packages/core/src/lib/toolRouterParams.ts
+11
-1
@@ -18,6 +18,7 @@ import {
18
ToolRouterUpdateExperimentalConfig,
19
ToolRouterSandboxConfig,
20
ToolRouterInstant,
21
+ ToolRouterProxyExecute,
22
} from '../types/toolRouter.types';
23
import { ValidationError } from '../errors';
24
import { z } from 'zod';
@@ -203,6 +204,12 @@ export type SessionPatchBody = Omit<
204
expected_config_version?: number;
205
};
206
207
+/** `proxy_execute` as sent on create and update: a boolean becomes `{ enable }`. */
208
+export const transformToolRouterProxyExecuteParams = (
209
+ config: ToolRouterProxyExecute
210
+): NonNullable<SessionCreateParams['proxy_execute']> =>
211
+ typeof config === 'boolean' ? { enable: config } : config;
212
+
213
export const transformToolRouterInstantParams = (
214
config: ToolRouterInstant
215
): NonNullable<SessionCreateParams['instant']> => {
@@ -392,7 +399,10 @@ export const transformToolRouterUpdateParams = (
399
}
400
}
401
if (config.proxyExecute !== undefined) {
395
- params.proxy_execute = config.proxyExecute;
402
+ params.proxy_execute =
403
+ config.proxyExecute === null
404
+ ? null
405
+ : transformToolRouterProxyExecuteParams(config.proxyExecute);
406
}
407
if (config.preload !== undefined) {
408
params.preload = config.preload;
ts/packages/core/src/models/ToolRouter.ts
+2
-1
@@ -51,6 +51,7 @@ import {
51
transformToolRouterToolkitsParams,
52
transformToolRouterMultiAccountParams,
53
transformToolRouterInstantParams,
54
+ transformToolRouterProxyExecuteParams,
55
resolveToolRouterSandboxConfig,
56
} from '../lib/toolRouterParams';
57
import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
@@ -283,7 +284,7 @@ export class ToolRouter<
284
workbench: sandboxPayload,
285
multi_account: multiAccountPayload,
286
...(routerConfig.proxyExecute !== undefined && {
286
- proxy_execute: routerConfig.proxyExecute,
287
+ proxy_execute: transformToolRouterProxyExecuteParams(routerConfig.proxyExecute),
288
}),
289
preload: routerConfig.preload,
290
...(isDirectToolsPreset && {
ts/packages/core/src/types/toolRouter.types.ts
+17
-5
@@ -251,6 +251,16 @@ export const ToolRouterProxyExecuteConfigSchema = z
251
.strict();
252
export type ToolRouterProxyExecuteConfig = z.infer<typeof ToolRouterProxyExecuteConfigSchema>;
253
254
+/**
255
+ * `proxyExecute` as accepted by `sessions.create()` and `session.update()`:
256
+ * a boolean is shorthand for `{ enable: boolean }`.
257
+ */
258
+export const ToolRouterProxyExecuteSchema = z.union([
259
+ z.boolean(),
260
+ ToolRouterProxyExecuteConfigSchema,
261
+]);
262
+export type ToolRouterProxyExecute = z.infer<typeof ToolRouterProxyExecuteSchema>;
263
+
264
const ToolRouterCreateSessionConfigBaseSchema = z
265
.object({
266
sessionPreset: z
@@ -337,8 +347,8 @@ const ToolRouterCreateSessionConfigBaseSchema = z
347
.optional()
348
.describe('Multi-account configuration for this session'),
349
340
- proxyExecute: ToolRouterProxyExecuteConfigSchema.optional().describe(
341
- 'Proxy execute configuration for this session. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
350
+ proxyExecute: ToolRouterProxyExecuteSchema.optional().describe(
351
+ 'Proxy execute configuration for this session; a boolean is shorthand for `{ enable }`. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
352
),
353
354
preload: z
@@ -462,7 +472,7 @@ export const ToolRouterCreateSessionConfigSchema = z
472
* @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
473
* @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
474
* @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
465
- * @param {object} [proxyExecute] - Proxy execute configuration for this session
475
+ * @param {boolean | object} [proxyExecute] - Proxy execute configuration for this session. A boolean is shorthand for `{ enable }`.
476
* @param {boolean} proxyExecute.enable - `true` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool. `false` also turns off the sandbox `proxy_execute()` helper.
477
* @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
478
* @param {string[] | 'all'} [preload.tools] - Tool slugs to preload, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.
@@ -963,9 +973,11 @@ export const ToolRouterUpdateSessionConfigSchema = z
973
.nullable()
974
.optional()
975
.describe('`null` removes the session override; the mode then resolves to disabled'),
966
- proxyExecute: ToolRouterProxyExecuteConfigSchema.nullable()
976
+ proxyExecute: ToolRouterProxyExecuteSchema.nullable()
977
.optional()
968
- .describe('Replaces the proxy execute block; `null` removes it'),
978
+ .describe(
979
+ 'Replaces the proxy execute block; a boolean is shorthand for `{ enable }` and `null` removes it'
980
+ ),
981
preload: z
982
.object({
983
tools: z.union([z.array(z.string()), z.literal('all')]).optional(),
ts/packages/core/test/lib/toolRouterParams.test.ts
+7
-1
@@ -194,13 +194,19 @@ describe('transformToolRouterUpdateParams', () => {
194
});
195
});
196
197
- it('maps proxyExecute as given, and null clears it', () => {
197
+ it('maps proxyExecute as given, expands a boolean, and null clears it', () => {
198
expect(transformToolRouterUpdateParams({ proxyExecute: { enable: true } })).toEqual({
199
proxy_execute: { enable: true },
200
});
201
expect(transformToolRouterUpdateParams({ proxyExecute: { enable: false } })).toEqual({
202
proxy_execute: { enable: false },
203
});
204
+ expect(transformToolRouterUpdateParams({ proxyExecute: true })).toEqual({
205
+ proxy_execute: { enable: true },
206
+ });
207
+ expect(transformToolRouterUpdateParams({ proxyExecute: false })).toEqual({
208
+ proxy_execute: { enable: false },
209
+ });
210
expect(transformToolRouterUpdateParams({ proxyExecute: null })).toEqual({
211
proxy_execute: null,
212
});
ts/packages/core/test/models/toolRouter.test.ts
+34
-2
@@ -222,17 +222,21 @@ describe('ToolRouter', () => {
222
expect(mockClient.toolRouter.session.create.mock.calls[2]?.[0]).not.toHaveProperty('instant');
223
});
224
225
- it('sends proxyExecute.enable as given and omits the block otherwise', async () => {
225
+ it('sends proxyExecute as given, expands the boolean shorthand, and omits the block otherwise', async () => {
226
mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
227
228
await toolRouter.create(userId, { proxyExecute: { enable: true } });
229
await toolRouter.create(userId, { proxyExecute: { enable: false } });
230
+ await toolRouter.create(userId, { proxyExecute: true });
231
+ await toolRouter.create(userId, { proxyExecute: false });
232
await toolRouter.create(userId);
233
234
const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
235
expect(bodies[0]).toMatchObject({ proxy_execute: { enable: true } });
236
expect(bodies[1]).toMatchObject({ proxy_execute: { enable: false } });
235
- expect(bodies[2]).not.toHaveProperty('proxy_execute');
237
+ expect(bodies[2]).toMatchObject({ proxy_execute: { enable: true } });
238
+ expect(bodies[3]).toMatchObject({ proxy_execute: { enable: false } });
239
+ expect(bodies[4]).not.toHaveProperty('proxy_execute');
240
});
241
242
it('rejects a proxyExecute block without enable', async () => {
@@ -4381,6 +4385,34 @@ describe('ToolRouter', () => {
4385
expect(patchCall().body.manage_connections).toEqual({ callback_url: null });
4386
});
4387
4388
+ it('sends proxyExecute as given, expands the boolean shorthand, and null removes the block', async () => {
4389
+ const session = await toolRouter.use(sessionId);
4390
+
4391
+ await session.update({ proxyExecute: { enable: true } });
4392
+ await session.update({ proxyExecute: { enable: false } });
4393
+ await session.update({ proxyExecute: true });
4394
+ await session.update({ proxyExecute: false });
4395
+ await session.update({ proxyExecute: null });
4396
+ await session.update({ toolkits: ['gmail'] });
4397
+
4398
+ expect(patchCall(0).body.proxy_execute).toEqual({ enable: true });
4399
+ expect(patchCall(1).body.proxy_execute).toEqual({ enable: false });
4400
+ expect(patchCall(2).body.proxy_execute).toEqual({ enable: true });
4401
+ expect(patchCall(3).body.proxy_execute).toEqual({ enable: false });
4402
+ expect(patchCall(4).body.proxy_execute).toBeNull();
4403
+ expect(patchCall(5).body).not.toHaveProperty('proxy_execute');
4404
+ });
4405
+
4406
+ it('rejects a proxyExecute block without enable', async () => {
4407
+ const session = await toolRouter.use(sessionId);
4408
+
4409
+ await expect(
4410
+ // @ts-expect-error enable is required
4411
+ session.update({ proxyExecute: {} })
4412
+ ).rejects.toThrow();
4413
+ expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4414
+ });
4415
+
4416
it('preserves an empty toolkit allowlist instead of omitting it', async () => {
4417
const session = await toolRouter.use(sessionId);
4418