Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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 workbenchBy 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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);