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: add multi-account session config and connected account alias update to SDK
Adds multiAccount config to ToolRouter session creation (TS + Python) and a new update() method on ConnectedAccounts for setting/clearing aliases via the PATCH /api/v3/connected_accounts/{nanoid} endpoint. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Zen Agent <zen@composio.dev>
abir committed
Apr 8, 2026 at 07:05 UTC
fbbc40329f1ff3049f03d3feb5175050f381a3b6
7 files changed
+191
-1
python/composio/core/models/connected_accounts.py
+33
@@ -356,6 +356,39 @@ class ConnectedAccounts:
356
enabled=False,
357
)
358
359
+ def update(
360
+ self,
361
+ nanoid: str,
362
+ *,
363
+ alias: str,
364
+ ) -> t.Dict[str, t.Any]:
365
+ """
366
+ Update a connected account's alias.
367
+
368
+ :param nanoid: The unique identifier of the connected account.
369
+ :param alias: Human-readable alias for the account. Must be unique per entity
370
+ and toolkit within the project. Pass an empty string to clear.
371
+ :return: Dict with ``success``, and optionally ``id`` and ``status``.
372
+
373
+ Example:
374
+ # Set an alias
375
+ composio.connected_accounts.update('ca_abc123', alias='work-gmail')
376
+
377
+ # Clear an alias
378
+ composio.connected_accounts.update('ca_abc123', alias='')
379
+ """
380
+ if not nanoid:
381
+ raise ValueError(
382
+ f"Expected a non-empty value for `nanoid` but received {nanoid!r}"
383
+ )
384
+ # The composio_client doesn't yet have a typed method for this endpoint,
385
+ # so we call the raw client patch method directly.
386
+ return self._client.patch( # type: ignore[no-any-return]
387
+ f"/api/v3/connected_accounts/{nanoid}",
388
+ body={"alias": alias},
389
+ cast_to=dict, # type: ignore[arg-type]
390
+ )
391
+
392
def initiate(
393
self,
394
user_id: str,
python/composio/core/models/tool_router.py
+44
@@ -170,6 +170,23 @@ class ToolRouterManageConnectionsConfig(te.TypedDict, total=False):
170
wait_for_connections: bool
171
172
173
+class ToolRouterMultiAccountConfig(te.TypedDict, total=False):
174
+ """Configuration for multi-account mode in tool router session.
175
+
176
+ Attributes:
177
+ enable: When True, enables multi-account mode. When not set, falls back to
178
+ org/project-level configuration.
179
+ max_accounts_per_toolkit: Maximum connected accounts allowed per toolkit (2-10).
180
+ Defaults to 5 when multi-account is enabled.
181
+ require_explicit_selection: When True, require explicit account selection when
182
+ multiple accounts are connected. Defaults to False.
183
+ """
184
+
185
+ enable: bool
186
+ max_accounts_per_toolkit: int
187
+ require_explicit_selection: bool
188
+
189
+
190
class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):
191
"""Configuration for assistive prompt generation.
192
@@ -434,6 +451,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
451
auth_configs: t.Optional[t.Dict[str, str]] = None,
452
connected_accounts: t.Optional[t.Dict[str, str]] = None,
453
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
454
+ multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
455
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
456
) -> ToolRouterSession[TTool, TToolCollection]:
457
"""
@@ -502,6 +520,15 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
520
offload to workbench.
521
Example: {'enable': False}
522
Example: {'enable_proxy_execution': False, 'auto_offload_threshold': 300}
523
+ :param multi_account: Optional multi-account configuration (ToolRouterMultiAccountConfig).
524
+ Dict with:
525
+ - 'enable' (bool): When True, enables multi-account mode.
526
+ Falls back to org/project-level config when not set.
527
+ - 'max_accounts_per_toolkit' (int): Max connected accounts per
528
+ toolkit (2-10). Defaults to 5.
529
+ - 'require_explicit_selection' (bool): When True, require explicit
530
+ account selection when multiple accounts are connected.
531
+ Example: {'enable': True, 'max_accounts_per_toolkit': 3}
532
:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).
533
Note: These features are experimental and may change.
534
Dict with:
@@ -707,6 +734,22 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
734
if execution_payload:
735
create_params["workbench"] = execution_payload
736
737
+ # Build multi_account config
738
+ if multi_account is not None:
739
+ multi_account_payload: t.Dict[str, t.Any] = {}
740
+ if "enable" in multi_account:
741
+ multi_account_payload["enable"] = multi_account["enable"]
742
+ if "max_accounts_per_toolkit" in multi_account:
743
+ multi_account_payload["max_accounts_per_toolkit"] = multi_account[
744
+ "max_accounts_per_toolkit"
745
+ ]
746
+ if "require_explicit_selection" in multi_account:
747
+ multi_account_payload["require_explicit_selection"] = multi_account[
748
+ "require_explicit_selection"
749
+ ]
750
+ if multi_account_payload:
751
+ create_params["multi_account"] = multi_account_payload
752
+
753
# Build experimental config
754
# Map SDK's experimental.assistive_prompt.user_timezone to API's
755
# experimental.assistive_prompt_config.user_timezone
@@ -851,6 +894,7 @@ __all__ = [
894
"ToolRouterConfigTags",
895
"ToolRouterManageConnectionsConfig",
896
"ToolRouterWorkbenchConfig",
897
+ "ToolRouterMultiAccountConfig",
898
"ToolRouterExperimentalConfig",
899
"ToolRouterAssistivePromptConfig",
900
"ToolkitConnectionState",
ts/packages/core/src/lib/toolRouterParams.ts
+14
@@ -125,6 +125,20 @@ export const transformToolRouterWorkbenchParams = (
125
};
126
};
127
128
+export const transformToolRouterMultiAccountParams = (
129
+ params?: ToolRouterCreateSessionConfig['multiAccount']
130
+): { enable?: boolean; max_accounts_per_toolkit?: number; require_explicit_selection?: boolean } | undefined => {
131
+ if (!params) {
132
+ return undefined;
133
+ }
134
+
135
+ return {
136
+ enable: params.enable,
137
+ max_accounts_per_toolkit: params.maxAccountsPerToolkit,
138
+ require_explicit_selection: params.requireExplicitSelection,
139
+ };
140
+};
141
+
142
export const transformToolRouterToolkitsParams = (
143
params?: ToolRouterCreateSessionConfig['toolkits']
144
): SessionCreateParams.Enable | SessionCreateParams.Disable | undefined => {
ts/packages/core/src/models/ConnectedAccounts.ts
+42
@@ -26,6 +26,10 @@ import {
26
ConnectedAccountStatuses,
27
ConnectedAccountRefreshOptions,
28
ConnectedAccountRefreshOptionsSchema,
29
+ UpdateConnectedAccountParams,
30
+ UpdateConnectedAccountParamsSchema,
31
+ UpdateConnectedAccountResponse,
32
+ UpdateConnectedAccountResponseSchema,
33
} from '../types/connectedAccounts.types';
34
import { ConnectionRequest } from '../types/connectionRequest.types';
35
import { createConnectionRequest } from './ConnectionRequest';
@@ -461,4 +465,42 @@ export class ConnectedAccounts {
465
async disable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse> {
466
return this.client.connectedAccounts.updateStatus(nanoid, { enabled: false });
467
}
468
+
469
+ /**
470
+ * Update a connected account's alias.
471
+ *
472
+ * @param {string} nanoid - The unique identifier of the connected account
473
+ * @param {UpdateConnectedAccountParams} params - The update parameters
474
+ * @param {string} params.alias - Human-readable alias for the account. Must be unique per entity and toolkit within the project. Pass an empty string to clear.
475
+ * @returns {Promise<UpdateConnectedAccountResponse>} The update response
476
+ *
477
+ * @example
478
+ * ```typescript
479
+ * // Set an alias
480
+ * await composio.connectedAccounts.update('conn_abc123', { alias: 'work-gmail' });
481
+ *
482
+ * // Clear an alias
483
+ * await composio.connectedAccounts.update('conn_abc123', { alias: '' });
484
+ * ```
485
+ */
486
+ async update(
487
+ nanoid: string,
488
+ params: UpdateConnectedAccountParams
489
+ ): Promise<UpdateConnectedAccountResponse> {
490
+ const parsedParams = UpdateConnectedAccountParamsSchema.safeParse(params);
491
+ if (!parsedParams.success) {
492
+ throw new ValidationError('Failed to parse connected account update params', {
493
+ cause: parsedParams.error,
494
+ });
495
+ }
496
+
497
+ // The @composio/client doesn't yet have a typed method for this endpoint,
498
+ // so we call the raw client patch method directly.
499
+ const response = await (this.client as unknown as { patch: (path: string, opts: unknown) => Promise<unknown> }).patch(
500
+ `/api/v3/connected_accounts/${nanoid}`,
501
+ { body: { alias: parsedParams.data.alias } }
502
+ );
503
+
504
+ return UpdateConnectedAccountResponseSchema.parse(response);
505
+ }
506
}
ts/packages/core/src/models/ToolRouter.ts
+11
-1
@@ -39,6 +39,7 @@ import {
39
transformToolRouterManageConnectionsParams,
40
transformToolRouterWorkbenchParams,
41
transformToolRouterToolkitsParams,
42
+ transformToolRouterMultiAccountParams,
43
} from '../lib/toolRouterParams';
44
import { ToolRouterSession } from './ToolRouterSession';
45
import { buildCustomToolsMapFromResponse, serializeCustomTools, serializeCustomToolkits } from './CustomTool';
@@ -121,7 +122,15 @@ export class ToolRouter<
122
experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);
123
}
124
124
- const payload: SessionCreateParams = {
125
+ const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
126
+
127
+ const payload: SessionCreateParams & {
128
+ multi_account?: {
129
+ enable?: boolean;
130
+ max_accounts_per_toolkit?: number;
131
+ require_explicit_selection?: boolean;
132
+ };
133
+ } = {
134
user_id: userId,
135
auth_configs: routerConfig.authConfigs,
136
connected_accounts: routerConfig.connectedAccounts,
@@ -132,6 +141,7 @@ export class ToolRouter<
141
routerConfig.manageConnections
142
),
143
workbench: transformToolRouterWorkbenchParams(routerConfig.workbench),
144
+ ...(multiAccountPayload ? { multi_account: multiAccountPayload } : {}),
145
experimental: Object.keys(experimentalPayload).length > 0
146
? experimentalPayload
147
: undefined,
ts/packages/core/src/types/connectedAccounts.types.ts
+16
@@ -204,3 +204,19 @@ export const ConnectedAccountRefreshOptionsSchema = z.object({
204
validateCredentials: z.boolean().optional(),
205
});
206
export type ConnectedAccountRefreshOptions = z.infer<typeof ConnectedAccountRefreshOptionsSchema>;
207
+
208
+export const UpdateConnectedAccountParamsSchema = z.object({
209
+ alias: z
210
+ .string()
211
+ .describe(
212
+ 'Human-readable alias for the account. Must be unique per entity and toolkit within the project. Pass an empty string to clear the alias.'
213
+ ),
214
+});
215
+export type UpdateConnectedAccountParams = z.infer<typeof UpdateConnectedAccountParamsSchema>;
216
+
217
+export const UpdateConnectedAccountResponseSchema = z.object({
218
+ success: z.boolean(),
219
+ id: z.string().optional(),
220
+ status: z.string().optional(),
221
+});
222
+export type UpdateConnectedAccountResponse = z.infer<typeof UpdateConnectedAccountResponseSchema>;
ts/packages/core/src/types/toolRouter.types.ts
+31
@@ -206,6 +206,33 @@ export const ToolRouterCreateSessionConfigSchema = z
206
})
207
.optional()
208
.describe('The workbench config for the tool router session'),
209
+ multiAccount: z
210
+ .object({
211
+ enable: z
212
+ .boolean()
213
+ .optional()
214
+ .describe(
215
+ 'When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.'
216
+ ),
217
+ maxAccountsPerToolkit: z
218
+ .number()
219
+ .int()
220
+ .min(2)
221
+ .max(10)
222
+ .optional()
223
+ .describe(
224
+ 'Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled.'
225
+ ),
226
+ requireExplicitSelection: z
227
+ .boolean()
228
+ .optional()
229
+ .describe(
230
+ 'When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account.'
231
+ ),
232
+ })
233
+ .optional()
234
+ .describe('Multi-account configuration for this session'),
235
+
236
experimental: z
237
.object({
238
assistivePrompt: z
@@ -252,6 +279,10 @@ export const ToolRouterCreateSessionConfigSchema = z
279
* @param {boolean} [workbench.enable] - Whether to enable the workbench entirely. Defaults to true. When false, no code execution tools are available.
280
* @param {boolean} [workbench.enableProxyExecution] - Whether to enable proxy execution
281
* @param {number} [workbench.autoOffloadThreshold] - Auto offload threshold in characters for moving execution to workbench
282
+ * @param {object} [multiAccount] - Multi-account configuration for this session
283
+ * @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
284
+ * @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
285
+ * @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
286
*/
287
export type ToolRouterCreateSessionConfig = z.infer<typeof ToolRouterCreateSessionConfigSchema>;
288