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

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);