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 proxyExecute on session create and update (PLEN-4324)
Sessions expose the COMPOSIO_PROXY_EXECUTE meta tool only when created with proxy_execute.enable: true, and neither SDK could send that field. Add proxyExecute (TypeScript) and proxy_execute (Python) to sessions.create() and session.update(). The block is passed to the generated client as given and omitted when not set; null on update removes the stored block. enable is required inside the block, matching the API. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
David Tejuosho committed
Oct 9, 2026 at 10:55 UTC
58bcde84547113c8460b2548ec542fc207dc6e64
10 files changed
+129
.changeset/session-proxy-execute-option.md
new
+5
@@ -0,0 +1,5 @@
1
+---
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`.
python/composio/core/models/tool_router.py
+13
@@ -50,6 +50,7 @@ from composio.core.models.tool_router_constants import (
50
)
51
from composio.core.models.tool_router_session import (
52
ToolRouterInstantConfig,
53
+ ToolRouterProxyExecuteConfig,
54
ToolRouterSession,
55
ToolRouterSessionConfig,
56
ToolRouterSessionPreloadConfig,
@@ -725,6 +726,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
726
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
727
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
728
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
729
+ proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
730
preload: t.Optional[ToolRouterPreloadConfig] = None,
731
session_preset: t.Optional[SessionPreset] = None,
732
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -754,6 +756,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
756
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
757
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
758
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
759
+ proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
760
preload: t.Optional[ToolRouterPreloadConfig] = None,
761
session_preset: t.Optional[SessionPreset] = None,
762
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -782,6 +785,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
785
sandbox: t.Optional[ToolRouterSandboxConfig] = None,
786
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
787
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
788
+ proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
789
preload: t.Optional[ToolRouterPreloadConfig] = None,
790
session_preset: t.Optional[SessionPreset] = None,
791
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -893,6 +897,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
897
it directly from session.tools(); otherwise custom tools
898
remain search-only.
899
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.
907
:param instant: Experimental Instant usage policy. The project
908
must allow Instant usage. ``False`` disables it for this
909
Session; a policy can restrict eligible toolkits and tools.
@@ -1091,6 +1102,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1102
}
1103
if instant is not None:
1104
create_params["instant"] = instant
1105
+ if proxy_execute is not None:
1106
+ create_params["proxy_execute"] = proxy_execute
1107
1108
# Build connections config
1109
connections_config: t.Dict[str, t.Any] = {
python/composio/core/models/tool_router_session.py
+18
@@ -156,6 +156,18 @@ class ToolRouterInstantConfig(te.TypedDict, total=False):
156
return_instant_charge: bool
157
158
159
+class ToolRouterProxyExecuteConfig(te.TypedDict):
160
+ """Proxy execute settings for a Session.
161
+
162
+ ``enable=True`` exposes the ``COMPOSIO_PROXY_EXECUTE`` meta tool and
163
+ ``enable=False`` also turns off the sandbox ``proxy_execute()`` helper.
164
+ Leaving the block out keeps the meta tool off while
165
+ ``sandbox.enable_proxy_execution`` controls the helper.
166
+ """
167
+
168
+ enable: bool
169
+
170
+
171
ToolRouterSessionExecuteResponse = SessionExecuteResponse
172
"""Result of :meth:`ToolRouterSession.execute`. ``instant_charge`` is present
173
only when the Session sets ``instant.return_instant_charge`` and a charge is
@@ -1086,6 +1098,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1098
t.Optional[ToolRouterUpdateMultiAccountConfig],
1099
"Omit",
1100
] = omit,
1101
+ proxy_execute: t.Union[t.Optional[ToolRouterProxyExecuteConfig], "Omit"] = omit,
1102
preload: t.Union[t.Optional[session_patch_params.Preload], "Omit"] = omit,
1103
search: t.Union[t.Optional[session_patch_params.Search], "Omit"] = omit,
1104
execute: t.Union[t.Optional[session_patch_params.Execute], "Omit"] = omit,
@@ -1109,6 +1122,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1122
access or an object to set its filters; it does not accept ``None``.
1123
Any object, even one that only sets ``return_instant_charge``,
1124
re-enables Instant usage on a Session set to ``False``.
1125
+ ``proxy_execute`` is sent as given: ``{"enable": True}`` exposes the
1126
+ ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``{"enable": False}`` also turns
1127
+ off the sandbox ``proxy_execute()`` helper, and ``None`` removes the
1128
+ stored block.
1129
1130
By default the request carries no precondition: the last writer wins.
1131
Pass ``expected_config_version`` (for example this object's
@@ -1200,6 +1217,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1217
t.Union[t.Optional[session_patch_params.MultiAccount], "Omit"],
1218
multi_account,
1219
),
1220
+ proxy_execute=proxy_execute,
1221
preload=t.cast(t.Union[session_patch_params.Preload, "Omit"], preload),
1222
search=t.cast(t.Union[session_patch_params.Search, "Omit"], search),
1223
execute=t.cast(t.Union[session_patch_params.Execute, "Omit"], execute),
python/composio/types.py
+2
@@ -3,6 +3,7 @@ from composio.core.models.connected_accounts import auth_scheme
3
from composio.core.models.experimental import UsageSummaryResponse
4
from composio.core.models.tool_router_session import (
5
ToolRouterInstantConfig,
6
+ ToolRouterProxyExecuteConfig,
7
ToolRouterSessionConfig,
8
ToolRouterSessionSearchResponse,
9
)
@@ -28,6 +29,7 @@ __all__ = [
29
"TToolCollection",
30
"InstantCharge",
31
"ToolRouterInstantConfig",
32
+ "ToolRouterProxyExecuteConfig",
33
"ToolRouterSessionConfig",
34
"ToolRouterSessionSearchResponse",
35
"ToolExecuteParams",
python/tests/test_tool_router.py
+26
@@ -183,6 +183,19 @@ class TestToolRouter:
183
# Verify API was called
184
mock_client.tool_router.session.create.assert_called_once()
185
186
+ @pytest.mark.parametrize("proxy_execute", [{"enable": True}, {"enable": False}])
187
+ def test_create_sends_proxy_execute_as_given(
188
+ self, tool_router, mock_client, proxy_execute
189
+ ):
190
+ tool_router.create(user_id="user_123", proxy_execute=proxy_execute)
191
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
192
+ assert kwargs["proxy_execute"] == proxy_execute
193
+
194
+ def test_create_omits_proxy_execute_by_default(self, tool_router, mock_client):
195
+ tool_router.create(user_id="user_123")
196
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
197
+ assert "proxy_execute" not in kwargs
198
+
199
def test_create_with_instant_policy(self, tool_router, mock_client):
200
policy = {"toolkits": {"enable": ["exa"]}, "return_instant_charge": True}
201
tool_router.create(user_id="user_123", instant=policy)
@@ -3185,6 +3198,19 @@ class TestSessionUpdateContract:
3198
def test_session_tracks_config_version(self, session):
3199
assert session.config_version == 7
3200
3201
+ @pytest.mark.parametrize(
3202
+ "proxy_execute", [{"enable": True}, {"enable": False}, None]
3203
+ )
3204
+ def test_proxy_execute_is_sent_as_given(self, session, mock_client, proxy_execute):
3205
+ session.update(proxy_execute=proxy_execute)
3206
+ kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3207
+ assert kwargs["proxy_execute"] == proxy_execute
3208
+
3209
+ def test_proxy_execute_is_omitted_by_default(self, session, mock_client):
3210
+ session.update(toolkits={"enable": ["gmail"]})
3211
+ kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3212
+ assert kwargs["proxy_execute"] is omit
3213
+
3214
def test_instant_policy_is_sent(self, session, mock_client):
3215
session.update(
3216
instant={
ts/packages/core/src/lib/toolRouterParams.ts
+3
@@ -391,6 +391,9 @@ export const transformToolRouterUpdateParams = (
391
params.multi_account = ma;
392
}
393
}
394
+ if (config.proxyExecute !== undefined) {
395
+ params.proxy_execute = config.proxyExecute;
396
+ }
397
if (config.preload !== undefined) {
398
params.preload = config.preload;
399
}
ts/packages/core/src/models/ToolRouter.ts
+3
@@ -282,6 +282,9 @@ export class ToolRouter<
282
),
283
workbench: sandboxPayload,
284
multi_account: multiAccountPayload,
285
+ ...(routerConfig.proxyExecute !== undefined && {
286
+ proxy_execute: routerConfig.proxyExecute,
287
+ }),
288
preload: routerConfig.preload,
289
...(isDirectToolsPreset && {
290
search: { enable: false },
ts/packages/core/src/types/toolRouter.types.ts
+26
@@ -233,6 +233,23 @@ export const ToolRouterConfigToolsSchema = z
233
});
234
export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;
235
236
+/**
237
+ * Proxy execute settings for a session. `enable: true` exposes the
238
+ * `COMPOSIO_PROXY_EXECUTE` meta tool and `enable: false` also turns off the
239
+ * sandbox `proxy_execute()` helper. Leaving the block out keeps the meta tool
240
+ * off while `sandbox.enableProxyExecution` controls the helper.
241
+ */
242
+export const ToolRouterProxyExecuteConfigSchema = z
243
+ .object({
244
+ enable: z
245
+ .boolean()
246
+ .describe(
247
+ 'true exposes the COMPOSIO_PROXY_EXECUTE meta tool. false also turns off the sandbox proxy_execute() helper.'
248
+ ),
249
+ })
250
+ .strict();
251
+export type ToolRouterProxyExecuteConfig = z.infer<typeof ToolRouterProxyExecuteConfigSchema>;
252
+
253
const ToolRouterCreateSessionConfigBaseSchema = z
254
.object({
255
sessionPreset: z
@@ -319,6 +336,10 @@ const ToolRouterCreateSessionConfigBaseSchema = z
336
.optional()
337
.describe('Multi-account configuration for this session'),
338
339
+ proxyExecute: ToolRouterProxyExecuteConfigSchema.optional().describe(
340
+ 'Proxy execute configuration for this session. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
341
+ ),
342
+
343
preload: z
344
.object({
345
tools: z
@@ -440,6 +461,8 @@ export const ToolRouterCreateSessionConfigSchema = z
461
* @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
462
* @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
463
* @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
464
+ * @param {object} [proxyExecute] - Proxy execute configuration for this session
465
+ * @param {boolean} proxyExecute.enable - `true` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool. `false` also turns off the sandbox `proxy_execute()` helper.
466
* @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
467
* @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.
468
* @param {object} [experimental] - Experimental features configuration. Not stable; may change or be removed.
@@ -927,6 +950,9 @@ export const ToolRouterUpdateSessionConfigSchema = z
950
.nullable()
951
.optional()
952
.describe('`null` removes the session override; the mode then resolves to disabled'),
953
+ proxyExecute: ToolRouterProxyExecuteConfigSchema.nullable()
954
+ .optional()
955
+ .describe('Replaces the proxy execute block; `null` removes it'),
956
preload: z
957
.object({
958
tools: z.union([z.array(z.string()), z.literal('all')]).optional(),
ts/packages/core/test/lib/toolRouterParams.test.ts
+12
@@ -194,6 +194,18 @@ describe('transformToolRouterUpdateParams', () => {
194
});
195
});
196
197
+ it('maps proxyExecute as given, 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: null })).toEqual({
205
+ proxy_execute: null,
206
+ });
207
+ });
208
+
209
it('keeps an empty toolkit allowlist in the request', () => {
210
expect(transformToolRouterUpdateParams({ toolkits: [] })).toEqual({
211
toolkits: { enable: [] },
ts/packages/core/test/models/toolRouter.test.ts
+21
@@ -221,6 +221,27 @@ describe('ToolRouter', () => {
221
expect(mockClient.toolRouter.session.create.mock.calls[2]?.[0]).not.toHaveProperty('instant');
222
});
223
224
+ it('sends proxyExecute.enable as given and omits the block otherwise', async () => {
225
+ mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
226
+
227
+ await toolRouter.create(userId, { proxyExecute: { enable: true } });
228
+ await toolRouter.create(userId, { proxyExecute: { enable: false } });
229
+ await toolRouter.create(userId);
230
+
231
+ const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
232
+ expect(bodies[0]).toMatchObject({ proxy_execute: { enable: true } });
233
+ expect(bodies[1]).toMatchObject({ proxy_execute: { enable: false } });
234
+ expect(bodies[2]).not.toHaveProperty('proxy_execute');
235
+ });
236
+
237
+ it('rejects a proxyExecute block without enable', async () => {
238
+ await expect(
239
+ // @ts-expect-error enable is required
240
+ toolRouter.create(userId, { proxyExecute: {} })
241
+ ).rejects.toThrow();
242
+ expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
243
+ });
244
+
245
describe('basic session creation', () => {
246
it('should create a session with minimal configuration', async () => {
247
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);