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.

test: add tests for multi-account support and update docs

Abir Taheer8aa93cf33d99
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 04b7c29ad..5919fd968 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -165,6 +165,75 @@ When executing a tool, the connected account is selected in this order:
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
+## Multi-account mode
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ multi_account={
+ "enable": True,
+ "max_accounts_per_toolkit": 3,
+ "require_explicit_selection": True
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ multiAccount: {
+ enable: true,
+ maxAccountsPerToolkit: 3,
+ requireExplicitSelection: true,
+ },
+});
+```
+</Tab>
+</Tabs>
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enable` | `boolean` | org/project default | Enable multi-account mode for this session |
+| `maxAccountsPerToolkit` | `number` (2-10) | 5 | Maximum connected accounts per toolkit |
+| `requireExplicitSelection` | `boolean` | `false` | Require explicit account selection when multiple accounts are connected |
+
+### Account aliases
+
+Set human-readable aliases on connected accounts so users and agents can distinguish between them:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Set an alias
+composio.connected_accounts.update("ca_abc123", alias="work-gmail")
+
+# Clear an alias
+composio.connected_accounts.update("ca_abc123", alias="")
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Set an alias
+await composio.connectedAccounts.update("ca_abc123", { alias: "work-gmail" });
+
+// Clear an alias
+await composio.connectedAccounts.update("ca_abc123", { alias: "" });
+```
+</Tab>
+</Tabs>
+
+Aliases must be unique per entity and toolkit within a project.
+
## Disabling workbench
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:
diff --git a/ts/examples/tool-router/src/multi-account.ts b/ts/examples/tool-router/src/multi-account.ts
new file mode 100644
index 000000000..85b20bd1f
--- /dev/null
+++ b/ts/examples/tool-router/src/multi-account.ts
@@ -0,0 +1,37 @@
+import { openai } from '@ai-sdk/openai';
+import { Composio } from '@composio/core';
+import { VercelProvider } from '@composio/vercel';
+import { stepCountIs, streamText } from 'ai';
+
+const composio = new Composio({
+ provider: new VercelProvider(),
+});
+
+// Enable multi-account mode so the user can connect multiple accounts
+// per toolkit (e.g. two Gmail accounts).
+const session = await composio.create('user_123', {
+ toolkits: ['gmail'],
+ multiAccount: {
+ enable: true,
+ maxAccountsPerToolkit: 3,
+ requireExplicitSelection: true,
+ },
+});
+
+// Set an alias on a connected account for easier identification
+await composio.connectedAccounts.update('ca_abc123', {
+ alias: 'work-gmail',
+});
+
+const tools = await session.tools();
+
+const stream = await streamText({
+ model: openai('gpt-4o-mini'),
+ prompt: 'Find my last email from my work Gmail account',
+ stopWhen: stepCountIs(10),
+ tools,
+});
+
+for await (const textPart of stream.textStream) {
+ process.stdout.write(textPart);
+}
diff --git a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
index 784b32e15..121fee675 100644
--- a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+++ b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
@@ -871,6 +871,44 @@ describe('ConnectedAccounts', () => {
});
});
+ describe('update', () => {
+ it('should set an alias on a connected account', async () => {
+ const nanoid = 'conn_abc123';
+ const mockResponse = { success: true, id: nanoid, status: 'ACTIVE' };
+
+ (extendedMockClient as any).patch = vi.fn().mockResolvedValueOnce(mockResponse);
+
+ const result = await connectedAccounts.update(nanoid, { alias: 'work-gmail' });
+
+ expect((extendedMockClient as any).patch).toHaveBeenCalledWith(
+ `/api/v3/connected_accounts/${nanoid}`,
+ { body: { alias: 'work-gmail' } }
+ );
+ expect(result).toEqual({ success: true, id: nanoid, status: 'ACTIVE' });
+ });
+
+ it('should clear an alias by passing an empty string', async () => {
+ const nanoid = 'conn_abc123';
+ const mockResponse = { success: true };
+
+ (extendedMockClient as any).patch = vi.fn().mockResolvedValueOnce(mockResponse);
+
+ const result = await connectedAccounts.update(nanoid, { alias: '' });
+
+ expect((extendedMockClient as any).patch).toHaveBeenCalledWith(
+ `/api/v3/connected_accounts/${nanoid}`,
+ { body: { alias: '' } }
+ );
+ expect(result).toEqual({ success: true });
+ });
+
+ it('should throw ValidationError for invalid params', async () => {
+ await expect(
+ connectedAccounts.update('conn_abc123', { alias: 123 } as any)
+ ).rejects.toThrow('Failed to parse connected account update params');
+ });
+ });
+
describe('link', () => {
it('should create a connected account link without options and return a ConnectionRequest', async () => {
const userId = 'user_123';
diff --git a/ts/packages/core/test/lib/toolRouterParams.test.ts b/ts/packages/core/test/lib/toolRouterParams.test.ts
index 7362bf07c..7b0ae0b21 100644
--- a/ts/packages/core/test/lib/toolRouterParams.test.ts
+++ b/ts/packages/core/test/lib/toolRouterParams.test.ts
@@ -1,7 +1,53 @@
import { describe, it, expect } from 'vitest';
-import { transformToolRouterTagsParams } from '../../src/lib/toolRouterParams';
+import { transformToolRouterTagsParams, transformToolRouterMultiAccountParams } from '../../src/lib/toolRouterParams';
import { ToolRouterConfigTags } from '../../src/types/toolRouter.types';
+describe('transformToolRouterMultiAccountParams', () => {
+ it('should return undefined when params is undefined', () => {
+ expect(transformToolRouterMultiAccountParams(undefined)).toBeUndefined();
+ });
+
+ it('should transform enable only', () => {
+ const result = transformToolRouterMultiAccountParams({ enable: true });
+ expect(result).toEqual({
+ enable: true,
+ max_accounts_per_toolkit: undefined,
+ require_explicit_selection: undefined,
+ });
+ });
+
+ it('should transform all fields', () => {
+ const result = transformToolRouterMultiAccountParams({
+ enable: true,
+ maxAccountsPerToolkit: 3,
+ requireExplicitSelection: true,
+ });
+ expect(result).toEqual({
+ enable: true,
+ max_accounts_per_toolkit: 3,
+ require_explicit_selection: true,
+ });
+ });
+
+ it('should transform with enable false', () => {
+ const result = transformToolRouterMultiAccountParams({ enable: false });
+ expect(result).toEqual({
+ enable: false,
+ max_accounts_per_toolkit: undefined,
+ require_explicit_selection: undefined,
+ });
+ });
+
+ it('should transform maxAccountsPerToolkit only', () => {
+ const result = transformToolRouterMultiAccountParams({ maxAccountsPerToolkit: 7 });
+ expect(result).toEqual({
+ enable: undefined,
+ max_accounts_per_toolkit: 7,
+ require_explicit_selection: undefined,
+ });
+ });
+});
+
describe('transformToolRouterTagsParams', () => {
describe('with undefined input', () => {
it('should return undefined when params is undefined', () => {
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index df7c03d2e..ad40ddb73 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -1211,6 +1211,91 @@ describe('ToolRouter', () => {
// });
// });
+ describe('multiAccount configuration', () => {
+ it('should create a session with multiAccount enable only', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
+
+ const config: ToolRouterCreateSessionConfig = {
+ multiAccount: {
+ enable: true,
+ },
+ };
+
+ await toolRouter.create(userId, config);
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ user_id: userId,
+ multi_account: {
+ enable: true,
+ max_accounts_per_toolkit: undefined,
+ require_explicit_selection: undefined,
+ },
+ })
+ );
+ });
+
+ it('should create a session with full multiAccount configuration', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
+
+ const config: ToolRouterCreateSessionConfig = {
+ multiAccount: {
+ enable: true,
+ maxAccountsPerToolkit: 3,
+ requireExplicitSelection: true,
+ },
+ };
+
+ await toolRouter.create(userId, config);
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ user_id: userId,
+ multi_account: {
+ enable: true,
+ max_accounts_per_toolkit: 3,
+ require_explicit_selection: true,
+ },
+ })
+ );
+ });
+
+ it('should not include multi_account when multiAccount is not provided', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
+
+ await toolRouter.create(userId, {});
+
+ const callArgs = mockClient.toolRouter.session.create.mock.calls[0][0];
+ expect(callArgs).not.toHaveProperty('multi_account');
+ });
+
+ it('should create a session with multiAccount combined with other options', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
+
+ const config: ToolRouterCreateSessionConfig = {
+ toolkits: ['gmail', 'slack'],
+ multiAccount: {
+ enable: true,
+ maxAccountsPerToolkit: 5,
+ },
+ };
+
+ await toolRouter.create(userId, config);
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ user_id: userId,
+ toolkits: { enable: ['gmail', 'slack'] },
+ multi_account: {
+ enable: true,
+ max_accounts_per_toolkit: 5,
+ require_explicit_selection: undefined,
+ },
+ })
+ );
+ });
+ });
+
describe('experimental configuration', () => {
it('should create a session with experimental assistivePrompt userTimezone', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);