Skip to content

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

abirfbbc40329f1f
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index 7eb8fdeb5..e3f30acc5 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -356,6 +356,39 @@ class ConnectedAccounts:
enabled=False,
)
+ def update(
+ self,
+ nanoid: str,
+ *,
+ alias: str,
+ ) -> t.Dict[str, t.Any]:
+ """
+ Update a connected account's alias.
+
+ :param nanoid: The unique identifier of the connected account.
+ :param alias: Human-readable alias for the account. Must be unique per entity
+ and toolkit within the project. Pass an empty string to clear.
+ :return: Dict with ``success``, and optionally ``id`` and ``status``.
+
+ Example:
+ # Set an alias
+ composio.connected_accounts.update('ca_abc123', alias='work-gmail')
+
+ # Clear an alias
+ composio.connected_accounts.update('ca_abc123', alias='')
+ """
+ if not nanoid:
+ raise ValueError(
+ f"Expected a non-empty value for `nanoid` but received {nanoid!r}"
+ )
+ # The composio_client doesn't yet have a typed method for this endpoint,
+ # so we call the raw client patch method directly.
+ return self._client.patch( # type: ignore[no-any-return]
+ f"/api/v3/connected_accounts/{nanoid}",
+ body={"alias": alias},
+ cast_to=dict, # type: ignore[arg-type]
+ )
+
def initiate(
self,
user_id: str,
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index 1f6438054..2add7a9a7 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -170,6 +170,23 @@ class ToolRouterManageConnectionsConfig(te.TypedDict, total=False):
wait_for_connections: bool
+class ToolRouterMultiAccountConfig(te.TypedDict, total=False):
+ """Configuration for multi-account mode in tool router session.
+
+ Attributes:
+ enable: When True, enables multi-account mode. When not set, falls back to
+ org/project-level configuration.
+ max_accounts_per_toolkit: Maximum connected accounts allowed per toolkit (2-10).
+ Defaults to 5 when multi-account is enabled.
+ require_explicit_selection: When True, require explicit account selection when
+ multiple accounts are connected. Defaults to False.
+ """
+
+ enable: bool
+ max_accounts_per_toolkit: int
+ require_explicit_selection: bool
+
+
class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):
"""Configuration for assistive prompt generation.
@@ -434,6 +451,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
auth_configs: t.Optional[t.Dict[str, str]] = None,
connected_accounts: t.Optional[t.Dict[str, str]] = None,
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
+ multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
) -> ToolRouterSession[TTool, TToolCollection]:
"""
@@ -502,6 +520,15 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
offload to workbench.
Example: {'enable': False}
Example: {'enable_proxy_execution': False, 'auto_offload_threshold': 300}
+ :param multi_account: Optional multi-account configuration (ToolRouterMultiAccountConfig).
+ Dict with:
+ - 'enable' (bool): When True, enables multi-account mode.
+ Falls back to org/project-level config when not set.
+ - 'max_accounts_per_toolkit' (int): Max connected accounts per
+ toolkit (2-10). Defaults to 5.
+ - 'require_explicit_selection' (bool): When True, require explicit
+ account selection when multiple accounts are connected.
+ Example: {'enable': True, 'max_accounts_per_toolkit': 3}
:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).
Note: These features are experimental and may change.
Dict with:
@@ -707,6 +734,22 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
if execution_payload:
create_params["workbench"] = execution_payload
+ # Build multi_account config
+ if multi_account is not None:
+ multi_account_payload: t.Dict[str, t.Any] = {}
+ if "enable" in multi_account:
+ multi_account_payload["enable"] = multi_account["enable"]
+ if "max_accounts_per_toolkit" in multi_account:
+ multi_account_payload["max_accounts_per_toolkit"] = multi_account[
+ "max_accounts_per_toolkit"
+ ]
+ if "require_explicit_selection" in multi_account:
+ multi_account_payload["require_explicit_selection"] = multi_account[
+ "require_explicit_selection"
+ ]
+ if multi_account_payload:
+ create_params["multi_account"] = multi_account_payload
+
# Build experimental config
# Map SDK's experimental.assistive_prompt.user_timezone to API's
# experimental.assistive_prompt_config.user_timezone
@@ -851,6 +894,7 @@ __all__ = [
"ToolRouterConfigTags",
"ToolRouterManageConnectionsConfig",
"ToolRouterWorkbenchConfig",
+ "ToolRouterMultiAccountConfig",
"ToolRouterExperimentalConfig",
"ToolRouterAssistivePromptConfig",
"ToolkitConnectionState",
diff --git a/ts/packages/core/src/lib/toolRouterParams.ts b/ts/packages/core/src/lib/toolRouterParams.ts
index 186ff3287..1b11a13a6 100644
--- a/ts/packages/core/src/lib/toolRouterParams.ts
+++ b/ts/packages/core/src/lib/toolRouterParams.ts
@@ -125,6 +125,20 @@ export const transformToolRouterWorkbenchParams = (
};
};
+export const transformToolRouterMultiAccountParams = (
+ params?: ToolRouterCreateSessionConfig['multiAccount']
+): { enable?: boolean; max_accounts_per_toolkit?: number; require_explicit_selection?: boolean } | undefined => {
+ if (!params) {
+ return undefined;
+ }
+
+ return {
+ enable: params.enable,
+ max_accounts_per_toolkit: params.maxAccountsPerToolkit,
+ require_explicit_selection: params.requireExplicitSelection,
+ };
+};
+
export const transformToolRouterToolkitsParams = (
params?: ToolRouterCreateSessionConfig['toolkits']
): SessionCreateParams.Enable | SessionCreateParams.Disable | undefined => {
diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.ts
index 7c8f2f542..e118d8538 100644
--- a/ts/packages/core/src/models/ConnectedAccounts.ts
+++ b/ts/packages/core/src/models/ConnectedAccounts.ts
@@ -26,6 +26,10 @@ import {
ConnectedAccountStatuses,
ConnectedAccountRefreshOptions,
ConnectedAccountRefreshOptionsSchema,
+ UpdateConnectedAccountParams,
+ UpdateConnectedAccountParamsSchema,
+ UpdateConnectedAccountResponse,
+ UpdateConnectedAccountResponseSchema,
} from '../types/connectedAccounts.types';
import { ConnectionRequest } from '../types/connectionRequest.types';
import { createConnectionRequest } from './ConnectionRequest';
@@ -461,4 +465,42 @@ export class ConnectedAccounts {
async disable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse> {
return this.client.connectedAccounts.updateStatus(nanoid, { enabled: false });
}
+
+ /**
+ * Update a connected account's alias.
+ *
+ * @param {string} nanoid - The unique identifier of the connected account
+ * @param {UpdateConnectedAccountParams} params - The update parameters
+ * @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.
+ * @returns {Promise<UpdateConnectedAccountResponse>} The update response
+ *
+ * @example
+ * ```typescript
+ * // Set an alias
+ * await composio.connectedAccounts.update('conn_abc123', { alias: 'work-gmail' });
+ *
+ * // Clear an alias
+ * await composio.connectedAccounts.update('conn_abc123', { alias: '' });
+ * ```
+ */
+ async update(
+ nanoid: string,
+ params: UpdateConnectedAccountParams
+ ): Promise<UpdateConnectedAccountResponse> {
+ const parsedParams = UpdateConnectedAccountParamsSchema.safeParse(params);
+ if (!parsedParams.success) {
+ throw new ValidationError('Failed to parse connected account update params', {
+ cause: parsedParams.error,
+ });
+ }
+
+ // The @composio/client doesn't yet have a typed method for this endpoint,
+ // so we call the raw client patch method directly.
+ const response = await (this.client as unknown as { patch: (path: string, opts: unknown) => Promise<unknown> }).patch(
+ `/api/v3/connected_accounts/${nanoid}`,
+ { body: { alias: parsedParams.data.alias } }
+ );
+
+ return UpdateConnectedAccountResponseSchema.parse(response);
+ }
}
diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.ts
index 68791711e..d536419d4 100644
--- a/ts/packages/core/src/models/ToolRouter.ts
+++ b/ts/packages/core/src/models/ToolRouter.ts
@@ -39,6 +39,7 @@ import {
transformToolRouterManageConnectionsParams,
transformToolRouterWorkbenchParams,
transformToolRouterToolkitsParams,
+ transformToolRouterMultiAccountParams,
} from '../lib/toolRouterParams';
import { ToolRouterSession } from './ToolRouterSession';
import { buildCustomToolsMapFromResponse, serializeCustomTools, serializeCustomToolkits } from './CustomTool';
@@ -121,7 +122,15 @@ export class ToolRouter<
experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);
}
- const payload: SessionCreateParams = {
+ const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
+
+ const payload: SessionCreateParams & {
+ multi_account?: {
+ enable?: boolean;
+ max_accounts_per_toolkit?: number;
+ require_explicit_selection?: boolean;
+ };
+ } = {
user_id: userId,
auth_configs: routerConfig.authConfigs,
connected_accounts: routerConfig.connectedAccounts,
@@ -132,6 +141,7 @@ export class ToolRouter<
routerConfig.manageConnections
),
workbench: transformToolRouterWorkbenchParams(routerConfig.workbench),
+ ...(multiAccountPayload ? { multi_account: multiAccountPayload } : {}),
experimental: Object.keys(experimentalPayload).length > 0
? experimentalPayload
: undefined,
diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.ts
index 5207605ed..2a2c113ec 100644
--- a/ts/packages/core/src/types/connectedAccounts.types.ts
+++ b/ts/packages/core/src/types/connectedAccounts.types.ts
@@ -204,3 +204,19 @@ export const ConnectedAccountRefreshOptionsSchema = z.object({
validateCredentials: z.boolean().optional(),
});
export type ConnectedAccountRefreshOptions = z.infer<typeof ConnectedAccountRefreshOptionsSchema>;
+
+export const UpdateConnectedAccountParamsSchema = z.object({
+ alias: z
+ .string()
+ .describe(
+ 'Human-readable alias for the account. Must be unique per entity and toolkit within the project. Pass an empty string to clear the alias.'
+ ),
+});
+export type UpdateConnectedAccountParams = z.infer<typeof UpdateConnectedAccountParamsSchema>;
+
+export const UpdateConnectedAccountResponseSchema = z.object({
+ success: z.boolean(),
+ id: z.string().optional(),
+ status: z.string().optional(),
+});
+export type UpdateConnectedAccountResponse = z.infer<typeof UpdateConnectedAccountResponseSchema>;
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index 31c3765e0..9a9c005aa 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -206,6 +206,33 @@ export const ToolRouterCreateSessionConfigSchema = z
})
.optional()
.describe('The workbench config for the tool router session'),
+ multiAccount: z
+ .object({
+ enable: z
+ .boolean()
+ .optional()
+ .describe(
+ 'When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.'
+ ),
+ maxAccountsPerToolkit: z
+ .number()
+ .int()
+ .min(2)
+ .max(10)
+ .optional()
+ .describe(
+ 'Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled.'
+ ),
+ requireExplicitSelection: z
+ .boolean()
+ .optional()
+ .describe(
+ 'When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account.'
+ ),
+ })
+ .optional()
+ .describe('Multi-account configuration for this session'),
+
experimental: z
.object({
assistivePrompt: z
@@ -252,6 +279,10 @@ export const ToolRouterCreateSessionConfigSchema = z
* @param {boolean} [workbench.enable] - Whether to enable the workbench entirely. Defaults to true. When false, no code execution tools are available.
* @param {boolean} [workbench.enableProxyExecution] - Whether to enable proxy execution
* @param {number} [workbench.autoOffloadThreshold] - Auto offload threshold in characters for moving execution to workbench
+ * @param {object} [multiAccount] - Multi-account configuration for this session
+ * @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
+ * @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
+ * @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
*/
export type ToolRouterCreateSessionConfig = z.infer<typeof ToolRouterCreateSessionConfigSchema>;