Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
test: add tests for multi-account support and update docs
Add unit tests for transformToolRouterMultiAccountParams, ToolRouter.create with multiAccount config, and ConnectedAccounts.update(). Add multi-account example and document the feature in configuring-sessions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Abir Taheer committed
Apr 8, 2026 at 00:24 UTC
8aa93cf33d998497dadc9533550673aaf4d83043
5 files changed
+276
-1
docs/content/docs/configuring-sessions.mdx
+69
@@ -165,6 +165,75 @@ When executing a tool, the connected account is selected in this order:
165
166
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
167
168
+## Multi-account mode
169
+
170
+Allow users to connect multiple accounts for the same toolkit (e.g. personal and work Gmail). When enabled, the session can manage up to `maxAccountsPerToolkit` connections per toolkit.
171
+
172
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
173
+<Tab value="Python">
174
+```python
175
+session = composio.create(
176
+ user_id="user_123",
177
+ multi_account={
178
+ "enable": True,
179
+ "max_accounts_per_toolkit": 3,
180
+ "require_explicit_selection": True
181
+ }
182
+)
183
+```
184
+</Tab>
185
+<Tab value="TypeScript">
186
+```typescript
187
+import { Composio } from '@composio/core';
188
+const composio = new Composio({ apiKey: 'your_api_key' });
189
+// ---cut---
190
+const session = await composio.create("user_123", {
191
+ multiAccount: {
192
+ enable: true,
193
+ maxAccountsPerToolkit: 3,
194
+ requireExplicitSelection: true,
195
+ },
196
+});
197
+```
198
+</Tab>
199
+</Tabs>
200
+
201
+| Option | Type | Default | Description |
202
+|--------|------|---------|-------------|
203
+| `enable` | `boolean` | org/project default | Enable multi-account mode for this session |
204
+| `maxAccountsPerToolkit` | `number` (2-10) | 5 | Maximum connected accounts per toolkit |
205
+| `requireExplicitSelection` | `boolean` | `false` | Require explicit account selection when multiple accounts are connected |
206
+
207
+### Account aliases
208
+
209
+Set human-readable aliases on connected accounts so users and agents can distinguish between them:
210
+
211
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
212
+<Tab value="Python">
213
+```python
214
+# Set an alias
215
+composio.connected_accounts.update("ca_abc123", alias="work-gmail")
216
+
217
+# Clear an alias
218
+composio.connected_accounts.update("ca_abc123", alias="")
219
+```
220
+</Tab>
221
+<Tab value="TypeScript">
222
+```typescript
223
+import { Composio } from '@composio/core';
224
+const composio = new Composio({ apiKey: 'your_api_key' });
225
+// ---cut---
226
+// Set an alias
227
+await composio.connectedAccounts.update("ca_abc123", { alias: "work-gmail" });
228
+
229
+// Clear an alias
230
+await composio.connectedAccounts.update("ca_abc123", { alias: "" });
231
+```
232
+</Tab>
233
+</Tabs>
234
+
235
+Aliases must be unique per entity and toolkit within a project.
236
+
237
## Disabling workbench
238
239
By default, sessions include the [workbench](/docs/workbench) — a persistent sandbox that provides `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL`. If your use case doesn't need code execution, you can disable it:
ts/examples/tool-router/src/multi-account.ts
new
+37
@@ -0,0 +1,37 @@
1
+import { openai } from '@ai-sdk/openai';
2
+import { Composio } from '@composio/core';
3
+import { VercelProvider } from '@composio/vercel';
4
+import { stepCountIs, streamText } from 'ai';
5
+
6
+const composio = new Composio({
7
+ provider: new VercelProvider(),
8
+});
9
+
10
+// Enable multi-account mode so the user can connect multiple accounts
11
+// per toolkit (e.g. two Gmail accounts).
12
+const session = await composio.create('user_123', {
13
+ toolkits: ['gmail'],
14
+ multiAccount: {
15
+ enable: true,
16
+ maxAccountsPerToolkit: 3,
17
+ requireExplicitSelection: true,
18
+ },
19
+});
20
+
21
+// Set an alias on a connected account for easier identification
22
+await composio.connectedAccounts.update('ca_abc123', {
23
+ alias: 'work-gmail',
24
+});
25
+
26
+const tools = await session.tools();
27
+
28
+const stream = await streamText({
29
+ model: openai('gpt-4o-mini'),
30
+ prompt: 'Find my last email from my work Gmail account',
31
+ stopWhen: stepCountIs(10),
32
+ tools,
33
+});
34
+
35
+for await (const textPart of stream.textStream) {
36
+ process.stdout.write(textPart);
37
+}
ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+38
@@ -871,6 +871,44 @@ describe('ConnectedAccounts', () => {
871
});
872
});
873
874
+ describe('update', () => {
875
+ it('should set an alias on a connected account', async () => {
876
+ const nanoid = 'conn_abc123';
877
+ const mockResponse = { success: true, id: nanoid, status: 'ACTIVE' };
878
+
879
+ (extendedMockClient as any).patch = vi.fn().mockResolvedValueOnce(mockResponse);
880
+
881
+ const result = await connectedAccounts.update(nanoid, { alias: 'work-gmail' });
882
+
883
+ expect((extendedMockClient as any).patch).toHaveBeenCalledWith(
884
+ `/api/v3/connected_accounts/${nanoid}`,
885
+ { body: { alias: 'work-gmail' } }
886
+ );
887
+ expect(result).toEqual({ success: true, id: nanoid, status: 'ACTIVE' });
888
+ });
889
+
890
+ it('should clear an alias by passing an empty string', async () => {
891
+ const nanoid = 'conn_abc123';
892
+ const mockResponse = { success: true };
893
+
894
+ (extendedMockClient as any).patch = vi.fn().mockResolvedValueOnce(mockResponse);
895
+
896
+ const result = await connectedAccounts.update(nanoid, { alias: '' });
897
+
898
+ expect((extendedMockClient as any).patch).toHaveBeenCalledWith(
899
+ `/api/v3/connected_accounts/${nanoid}`,
900
+ { body: { alias: '' } }
901
+ );
902
+ expect(result).toEqual({ success: true });
903
+ });
904
+
905
+ it('should throw ValidationError for invalid params', async () => {
906
+ await expect(
907
+ connectedAccounts.update('conn_abc123', { alias: 123 } as any)
908
+ ).rejects.toThrow('Failed to parse connected account update params');
909
+ });
910
+ });
911
+
912
describe('link', () => {
913
it('should create a connected account link without options and return a ConnectionRequest', async () => {
914
const userId = 'user_123';
ts/packages/core/test/lib/toolRouterParams.test.ts
+47
-1
@@ -1,7 +1,53 @@
1
import { describe, it, expect } from 'vitest';
2
-import { transformToolRouterTagsParams } from '../../src/lib/toolRouterParams';
2
+import { transformToolRouterTagsParams, transformToolRouterMultiAccountParams } from '../../src/lib/toolRouterParams';
3
import { ToolRouterConfigTags } from '../../src/types/toolRouter.types';
4
5
+describe('transformToolRouterMultiAccountParams', () => {
6
+ it('should return undefined when params is undefined', () => {
7
+ expect(transformToolRouterMultiAccountParams(undefined)).toBeUndefined();
8
+ });
9
+
10
+ it('should transform enable only', () => {
11
+ const result = transformToolRouterMultiAccountParams({ enable: true });
12
+ expect(result).toEqual({
13
+ enable: true,
14
+ max_accounts_per_toolkit: undefined,
15
+ require_explicit_selection: undefined,
16
+ });
17
+ });
18
+
19
+ it('should transform all fields', () => {
20
+ const result = transformToolRouterMultiAccountParams({
21
+ enable: true,
22
+ maxAccountsPerToolkit: 3,
23
+ requireExplicitSelection: true,
24
+ });
25
+ expect(result).toEqual({
26
+ enable: true,
27
+ max_accounts_per_toolkit: 3,
28
+ require_explicit_selection: true,
29
+ });
30
+ });
31
+
32
+ it('should transform with enable false', () => {
33
+ const result = transformToolRouterMultiAccountParams({ enable: false });
34
+ expect(result).toEqual({
35
+ enable: false,
36
+ max_accounts_per_toolkit: undefined,
37
+ require_explicit_selection: undefined,
38
+ });
39
+ });
40
+
41
+ it('should transform maxAccountsPerToolkit only', () => {
42
+ const result = transformToolRouterMultiAccountParams({ maxAccountsPerToolkit: 7 });
43
+ expect(result).toEqual({
44
+ enable: undefined,
45
+ max_accounts_per_toolkit: 7,
46
+ require_explicit_selection: undefined,
47
+ });
48
+ });
49
+});
50
+
51
describe('transformToolRouterTagsParams', () => {
52
describe('with undefined input', () => {
53
it('should return undefined when params is undefined', () => {
ts/packages/core/test/models/toolRouter.test.ts
+85
@@ -1211,6 +1211,91 @@ describe('ToolRouter', () => {
1211
// });
1212
// });
1213
1214
+ describe('multiAccount configuration', () => {
1215
+ it('should create a session with multiAccount enable only', async () => {
1216
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1217
+
1218
+ const config: ToolRouterCreateSessionConfig = {
1219
+ multiAccount: {
1220
+ enable: true,
1221
+ },
1222
+ };
1223
+
1224
+ await toolRouter.create(userId, config);
1225
+
1226
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1227
+ expect.objectContaining({
1228
+ user_id: userId,
1229
+ multi_account: {
1230
+ enable: true,
1231
+ max_accounts_per_toolkit: undefined,
1232
+ require_explicit_selection: undefined,
1233
+ },
1234
+ })
1235
+ );
1236
+ });
1237
+
1238
+ it('should create a session with full multiAccount configuration', async () => {
1239
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1240
+
1241
+ const config: ToolRouterCreateSessionConfig = {
1242
+ multiAccount: {
1243
+ enable: true,
1244
+ maxAccountsPerToolkit: 3,
1245
+ requireExplicitSelection: true,
1246
+ },
1247
+ };
1248
+
1249
+ await toolRouter.create(userId, config);
1250
+
1251
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1252
+ expect.objectContaining({
1253
+ user_id: userId,
1254
+ multi_account: {
1255
+ enable: true,
1256
+ max_accounts_per_toolkit: 3,
1257
+ require_explicit_selection: true,
1258
+ },
1259
+ })
1260
+ );
1261
+ });
1262
+
1263
+ it('should not include multi_account when multiAccount is not provided', async () => {
1264
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1265
+
1266
+ await toolRouter.create(userId, {});
1267
+
1268
+ const callArgs = mockClient.toolRouter.session.create.mock.calls[0][0];
1269
+ expect(callArgs).not.toHaveProperty('multi_account');
1270
+ });
1271
+
1272
+ it('should create a session with multiAccount combined with other options', async () => {
1273
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1274
+
1275
+ const config: ToolRouterCreateSessionConfig = {
1276
+ toolkits: ['gmail', 'slack'],
1277
+ multiAccount: {
1278
+ enable: true,
1279
+ maxAccountsPerToolkit: 5,
1280
+ },
1281
+ };
1282
+
1283
+ await toolRouter.create(userId, config);
1284
+
1285
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1286
+ expect.objectContaining({
1287
+ user_id: userId,
1288
+ toolkits: { enable: ['gmail', 'slack'] },
1289
+ multi_account: {
1290
+ enable: true,
1291
+ max_accounts_per_toolkit: 5,
1292
+ require_explicit_selection: undefined,
1293
+ },
1294
+ })
1295
+ );
1296
+ });
1297
+ });
1298
+
1299
describe('experimental configuration', () => {
1300
it('should create a session with experimental assistivePrompt userTimezone', async () => {
1301
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);