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

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