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

docs: restructure Users & Sessions, flatten guides, add Configuring Sessions

- Rewrite users-and-sessions.mdx with cleaner conceptual content - Create configuring-sessions.mdx guide for session configuration - Flatten guides folder structure (move files to docs root) - Update Anthropic provider page with Claude Agents SDK section - Delete user-management.mdx (redirect to users-and-sessions#users) - Delete multitenancy.mdx - Update redirects in next.config.mjs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Jan 24, 2026 at 00:40 UTC ade05f2060baaa0670e70a4995430f87d8f0c65e
11 files changed +825 -579
docs/content/docs/configuring-sessions.mdx new
+162
@@ -0,0 +1,162 @@
1 +---
2 +title: Configuring Sessions
3 +description: Enable toolkits, set auth configs, and select connected accounts
4 +keywords: [session, toolkits, auth configs, connected accounts]
5 +---
6 +
7 +## Creating a session
8 +
9 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
10 +<Tab value="Python">
11 +```python
12 +session = composio.create(user_id="user_123")
13 +```
14 +</Tab>
15 +<Tab value="TypeScript">
16 +```typescript
17 +import { Composio } from '@composio/core';
18 +const composio = new Composio({ apiKey: 'your_api_key' });
19 +// ---cut---
20 +const session = await composio.create("user_123");
21 +```
22 +</Tab>
23 +</Tabs>
24 +
25 +## Enabling toolkits
26 +
27 +Restrict the session to specific toolkits:
28 +
29 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
30 +<Tab value="Python">
31 +```python
32 +# Using array format
33 +session = composio.create(
34 + user_id="user_123",
35 + toolkits=["github", "gmail", "slack"]
36 +)
37 +
38 +# Using object format with enable key
39 +session = composio.create(
40 + user_id="user_123",
41 + toolkits={"enable": ["github", "gmail", "slack"]}
42 +)
43 +```
44 +</Tab>
45 +<Tab value="TypeScript">
46 +```typescript
47 +import { Composio } from '@composio/core';
48 +const composio = new Composio({ apiKey: 'your_api_key' });
49 +// ---cut---
50 +// Using array format
51 +const session = await composio.create("user_123", {
52 + toolkits: ["github", "gmail", "slack"],
53 +});
54 +
55 +// Using object format with enable key
56 +const session2 = await composio.create("user_123", {
57 + toolkits: { enable: ["github", "gmail", "slack"] },
58 +});
59 +```
60 +</Tab>
61 +</Tabs>
62 +
63 +## Disabling toolkits
64 +
65 +Keep all toolkits enabled except specific ones:
66 +
67 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
68 +<Tab value="Python">
69 +```python
70 +session = composio.create(
71 + user_id="user_123",
72 + toolkits={"disable": ["exa", "firecrawl"]}
73 +)
74 +```
75 +</Tab>
76 +<Tab value="TypeScript">
77 +```typescript
78 +import { Composio } from '@composio/core';
79 +const composio = new Composio({ apiKey: 'your_api_key' });
80 +// ---cut---
81 +const session = await composio.create("user_123", {
82 + toolkits: { disable: ["exa", "firecrawl"] },
83 +});
84 +```
85 +</Tab>
86 +</Tabs>
87 +
88 +## Custom auth configs
89 +
90 +Use your own OAuth credentials instead of Composio's defaults:
91 +
92 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
93 +<Tab value="Python">
94 +```python
95 +session = composio.create(
96 + user_id="user_123",
97 + auth_configs={
98 + "github": "ac_your_github_config",
99 + "slack": "ac_your_slack_config"
100 + }
101 +)
102 +```
103 +</Tab>
104 +<Tab value="TypeScript">
105 +```typescript
106 +import { Composio } from '@composio/core';
107 +const composio = new Composio({ apiKey: 'your_api_key' });
108 +// ---cut---
109 +const session = await composio.create("user_123", {
110 + authConfigs: {
111 + github: "ac_your_github_config",
112 + slack: "ac_your_slack_config",
113 + },
114 +});
115 +```
116 +</Tab>
117 +</Tabs>
118 +
119 +See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
120 +
121 +## Account selection
122 +
123 +If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
124 +
125 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
126 +<Tab value="Python">
127 +```python
128 +session = composio.create(
129 + user_id="user_123",
130 + connected_accounts={
131 + "gmail": "ca_work_gmail",
132 + "github": "ca_personal_github"
133 + }
134 +)
135 +```
136 +</Tab>
137 +<Tab value="TypeScript">
138 +```typescript
139 +import { Composio } from '@composio/core';
140 +const composio = new Composio({ apiKey: 'your_api_key' });
141 +// ---cut---
142 +const session = await composio.create("user_123", {
143 + connectedAccounts: {
144 + gmail: "ca_work_gmail",
145 + github: "ca_personal_github",
146 + },
147 +});
148 +```
149 +</Tab>
150 +</Tabs>
151 +
152 +### Precedence
153 +
154 +When executing a tool, the connected account is selected in this order:
155 +
156 +1. `connectedAccounts` override if provided in session config
157 +2. `authConfigs` override - finds or creates connection on that config
158 +3. Auth config previously created for this toolkit
159 +4. Creates new auth config using Composio managed auth
160 +5. Error if no Composio managed auth scheme exists for the toolkit
161 +
162 +If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
docs/content/docs/guides/multitenancy.mdx deleted
-5
@@ -1,5 +0,0 @@
1 ----
2 -title: Multitenancy
3 -description: Build multi-tenant applications with Composio
4 ----
5 -
docs/content/docs/managing-multiple-connected-accounts.mdx renamed
docs/content/docs/meta.json
+5 -5
@@ -6,17 +6,18 @@
6 "quickstart-tool-router",
7 "providers",
8 "---Core Concepts---",
9 + "users-and-sessions-temporary",
10 "users-and-sessions",
11 "authentication",
12 "tools-and-toolkits",
13 "---Getting Started---",
14 + "configuring-sessions",
15 "authenticating-users",
16 "toolkits",
17 "---Guides---",
16 - "guides/white-labeling-authentication",
17 - "guides/managing-multiple-connected-accounts",
18 - "guides/using-custom-auth-configuration",
19 - "guides/multitenancy",
18 + "white-labeling-authentication",
19 + "managing-multiple-connected-accounts",
20 + "using-custom-auth-configuration",
21 "---Tools---",
22 "fetching-tools",
23 "authenticating-tools",
@@ -29,7 +30,6 @@
30 "programmatic-auth-configs",
31 "custom-auth-params",
32 "connected-accounts",
32 - "user-management",
33 "---Features---",
34 "triggers",
35 "cli",
docs/content/docs/providers/anthropic.mdx
+335 -167
@@ -4,261 +4,422 @@ description: Use Composio tools with Claude
4 keywords: [claude]
5 ---
6
7 -The Anthropic Provider transforms Composio tools into a format compatible with Anthropic's function calling capabilities through its Messages API.
7 +## Claude Agents SDK
8
9 -## Usage with MCP
9 +<ToolTypeFlow>
10
11 -Use Composio Tool Router with the Claude Agent SDK for a fully managed MCP experience.
12 -
13 -### Installation
11 +<ToolTypeOption id="native" name="Native Tools" icon="native">
12 +<Steps>
13 +<Step>
14 +**Install**
15
16 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
17 <Tab value="Python">
18 ```bash
18 -pip install python-dotenv composio claude-agent-sdk
19 +pip install composio composio-claude-agent-sdk claude-agent-sdk
20 ```
21 </Tab>
22 <Tab value="TypeScript">
23 ```bash
23 -npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
24 +npm install dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
25 ```
26 </Tab>
27 </Tabs>
28 +</Step>
29
28 -### Usage
29 -
30 -Create a Tool Router session and execute tasks with Claude:
30 +<Step>
31 +**Configure API Keys**
32
33 <Callout type="info">
33 -- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
34 -- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
34 +Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `ANTHROPIC_API_KEY` with your [Anthropic API key](https://console.anthropic.com/settings/keys).
35 </Callout>
36
37 +```txt title=".env"
38 +COMPOSIO_API_KEY=xxxxxxxxx
39 +ANTHROPIC_API_KEY=xxxxxxxxx
40 +```
41 +</Step>
42 +
43 +<Step>
44 +**Create session and run agent**
45 +
46 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
47 <Tab value="Python">
48 ```python
49 import asyncio
50 from dotenv import load_dotenv
42 -from claude_agent_sdk.client import ClaudeSDKClient
43 -from claude_agent_sdk.types import (
44 - ClaudeAgentOptions,
45 - AssistantMessage,
46 - TextBlock,
47 - ToolUseBlock,
48 -)
51 +load_dotenv()
52 +
53 from composio import Composio
54 +from composio_claude_agent_sdk import ClaudeAgentSDKProvider
55 +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server
56 +
57 +# Initialize Composio with Claude Agent SDK provider
58 +composio = Composio(provider=ClaudeAgentSDKProvider())
59 +
60 +external_user_id = "user_2nFh83Hde"
61 +recipient_email = "soham.g@composio.dev"
62 +
63 +# Create a session
64 +session = composio.create(user_id=external_user_id)
65 +
66 +# Get tools from the session
67 +tools = session.tools()
68 +custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
69 +
70 +# Run the agent
71 +async def main():
72 + options = ClaudeAgentOptions(
73 + system_prompt="You are a helpful assistant.",
74 + permission_mode="bypassPermissions",
75 + mcp_servers={"composio": custom_server},
76 + )
77 +
78 + async with ClaudeSDKClient(options=options) as client:
79 + await client.query(f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'")
80 + async for msg in client.receive_response():
81 + print(msg)
82 +
83 +asyncio.run(main())
84 +```
85 +</Tab>
86 +<Tab value="TypeScript">
87 +```typescript
88 +import "dotenv/config";
89 +import { Composio } from "@composio/core";
90 +import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
91 +import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
92 +
93 +// Initialize Composio with Claude Agent SDK provider
94 +const composio = new Composio({
95 + provider: new ClaudeAgentSDKProvider(),
96 +});
97 +
98 +const externalUserId = "user_2nFh83Hde";
99 +const recipientEmail = "soham.g@composio.dev";
100 +
101 +// Create a session
102 +const session = await composio.create(externalUserId);
103 +
104 +// Get tools from the session
105 +const tools = await session.tools();
106 +
107 +const customServer = createSdkMcpServer({
108 + name: "composio",
109 + version: "1.0.0",
110 + tools: tools,
111 +});
112 +
113 +// Run the agent
114 +console.log("Running agent...");
115 +for await (const content of query({
116 + prompt: `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`,
117 + options: {
118 + mcpServers: { composio: customServer },
119 + permissionMode: "bypassPermissions",
120 + },
121 +})) {
122 + if (content.type === "assistant") {
123 + console.log("Claude:", content.message);
124 + }
125 +}
126 +
127 +console.log("Received response from Claude");
128 +```
129 +</Tab>
130 +</Tabs>
131 +</Step>
132 +</Steps>
133 +</ToolTypeOption>
134 +
135 +<ToolTypeOption id="mcp" name="MCP" icon="mcp">
136 +<Steps>
137 +<Step>
138 +**Install**
139 +
140 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
141 +<Tab value="Python">
142 +```bash
143 +pip install composio claude-agent-sdk
144 +```
145 +</Tab>
146 +<Tab value="TypeScript">
147 +```bash
148 +npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
149 +```
150 +</Tab>
151 +</Tabs>
152 +</Step>
153 +
154 +<Step>
155 +**Configure API Keys**
156 +
157 +<Callout type="info">
158 +Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `ANTHROPIC_API_KEY` with your [Anthropic API key](https://console.anthropic.com/settings/keys).
159 +</Callout>
160 +
161 +```txt title=".env"
162 +COMPOSIO_API_KEY=xxxxxxxxx
163 +ANTHROPIC_API_KEY=xxxxxxxxx
164 +```
165 +</Step>
166
167 +<Step>
168 +**Create session and run agent**
169 +
170 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
171 +<Tab value="Python">
172 +```python
173 +import asyncio
174 +from dotenv import load_dotenv
175 load_dotenv()
176
53 -# Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly)
177 +from composio import Composio
178 +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
179 +
180 +# Initialize Composio
181 composio = Composio()
182
56 -# Unique identifier of the user
57 -user_id = "user_123"
58 -# Create a tool router session for the user
59 -session = composio.create(user_id=user_id)
60 -
61 -# Configure Claude with Composio MCP server
62 -options = ClaudeAgentOptions(
63 - system_prompt=(
64 - "You are a helpful assistant with access to external tools. "
65 - "Always use the available tools to complete user requests."
66 - ),
67 - mcp_servers={
68 - "composio": {
69 - "type": "http",
70 - "url": session.mcp.url,
71 - "headers": session.mcp.headers, # Authentication headers for the Composio MCP server
72 - }
73 - },
74 - permission_mode="bypassPermissions", # Auto-approve tools (demo only)
75 -)
183 +external_user_id = "user_2nFh83Hde"
184 +recipient_email = "soham.g@composio.dev"
185 +
186 +# Create a session
187 +session = composio.create(user_id=external_user_id)
188
189 +# Run the agent
190 async def main():
78 - print("""
79 -What task would you like me to help you with?
80 -I can use tools like Gmail, GitHub, Linear, Notion, and more.
81 -(Type 'exit' to exit)
82 -Example tasks:
83 - • 'Summarize my emails from today'
84 - • 'List all open issues on the composio github repository and create a notion page with the issues'
85 -""")
86 -
87 - async with ClaudeSDKClient(options) as client:
88 - # Multi-turn conversation with agentic tool calling
89 - while True:
90 - user_input = input("\nYou: ").strip()
91 - if user_input.lower() == "exit":
92 - break
93 -
94 - print("\nClaude: ", end="", flush=True)
95 - try:
96 - await client.query(user_input)
97 - async for msg in client.receive_response():
98 - if isinstance(msg, AssistantMessage):
99 - for block in msg.content:
100 - if isinstance(block, ToolUseBlock):
101 - print(f"\n[Using tool: {block.name}]", end="")
102 - elif isinstance(block, TextBlock):
103 - print(block.text, end="", flush=True)
104 - except Exception as e:
105 - print(f"\n[Error]: {e}")
106 -
107 -if __name__ == "__main__":
108 - asyncio.run(main())
191 + options = ClaudeAgentOptions(
192 + system_prompt="You are a helpful assistant.",
193 + permission_mode="bypassPermissions",
194 + mcp_servers={
195 + "composio": {
196 + "type": "http",
197 + "url": session.mcp.url,
198 + "headers": session.mcp.headers,
199 + }
200 + },
201 + )
202 +
203 + async with ClaudeSDKClient(options=options) as client:
204 + await client.query(f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'")
205 + async for msg in client.receive_response():
206 + print(msg)
207 +
208 +asyncio.run(main())
209 ```
210 </Tab>
211 <Tab value="TypeScript">
212 ```typescript
213 import "dotenv/config";
114 -import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
214 import { Composio } from "@composio/core";
116 -import { createInterface } from "readline/promises";
215 +import { query } from "@anthropic-ai/claude-agent-sdk";
216
118 -// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
217 +// Initialize Composio
218 const composio = new Composio();
219
121 -// Unique identifier of the user
122 -const userId = "user_123";
123 -
124 -// Create a tool router session for the user
125 -const session = await composio.create(userId);
126 -
127 -const options: Options = {
128 - systemPrompt: `You are a helpful assistant with access to external tools. ` +
129 - `Always use the available tools to complete user requests.`,
130 - mcpServers: {
131 - composio: {
132 - type: "http",
133 - url: session.mcp.url,
134 - headers: session.mcp.headers // Authentication headers for the Composio MCP server
220 +const externalUserId = "user_2nFh83Hde";
221 +const recipientEmail = "soham.g@composio.dev";
222 +
223 +// Create a session
224 +const session = await composio.create(externalUserId);
225 +
226 +// Run the agent
227 +console.log("Running agent...");
228 +for await (const content of query({
229 + prompt: `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`,
230 + options: {
231 + mcpServers: {
232 + composio: {
233 + type: "http",
234 + url: session.mcp.url,
235 + headers: session.mcp.headers,
236 + },
237 },
238 + permissionMode: "bypassPermissions",
239 },
137 - permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)
138 -};
139 -
140 -// Set up interactive terminal input/output for the conversation
141 -const readline = createInterface({ input: process.stdin, output: process.stdout });
142 -
143 -console.log(`
144 -What task would you like me to help you with?
145 -I can use tools like Gmail, GitHub, Linear, Notion, and more.
146 -(Type 'exit' to exit)
147 -Example tasks:
148 - • 'Summarize my emails from today'
149 - • 'List all open issues on the composio github repository and create a notion page with the issues'
150 -`);
151 -
152 -let isFirstQuery = true;
153 -
154 -// Multi-turn conversation with agentic tool calling
155 -while (true) {
156 - const answer = await readline.question('You: ');
157 - const input = answer.trim();
158 - if (input.toLowerCase() === "exit") break;
159 -
160 - process.stdout.write("Claude: ");
161 -
162 - const queryOptions = isFirstQuery ? options : { ...options, continue: true };
163 - isFirstQuery = false;
164 -
165 - try {
166 - for await (const stream of query({ prompt: input, options: queryOptions })) {
167 - // Only process assistant messages (the SDK also sends result/error messages)
168 - if (stream.type === "assistant") {
169 - const { content } = stream.message;
170 - for (const block of content) {
171 - if (block.type === "tool_use") {
172 - process.stdout.write(`\n[Using tool: ${block.name}]`);
173 - } else if (block.type === "text") {
174 - process.stdout.write(block.text);
175 - }
176 - }
177 - }
178 - }
179 - } catch (error) {
180 - console.error("\n[Error]:", error instanceof Error ? error.message : error);
240 +})) {
241 + if (content.type === "assistant") {
242 + console.log("Claude:", content.message);
243 }
182 - process.stdout.write("\n");
244 }
245
185 -readline.close();
246 +console.log("Received response from Claude");
247 ```
248 </Tab>
249 </Tabs>
250 +</Step>
251 +</Steps>
252 +</ToolTypeOption>
253
190 -## Usage with direct tools
254 +</ToolTypeFlow>
255
192 -### Setup
256 +## Anthropic API
257
194 -<Tabs items={["Python", "TypeScript"]}>
258 +<Steps>
259 +<Step>
260 +**Install**
261 +
262 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
263 <Tab value="Python">
264 ```bash
197 -pip install composio composio-anthropic
265 +pip install composio composio-anthropic anthropic
266 ```
267 </Tab>
268 <Tab value="TypeScript">
269 ```bash
202 -npm install @composio/anthropic @anthropic-ai/sdk
270 +npm install dotenv @composio/core @composio/anthropic @anthropic-ai/sdk
271 ```
272 </Tab>
273 </Tabs>
274 +</Step>
275
207 -You can specify the provider in the constructor. The constructor also takes in an optional `cacheTools` parameter.
276 +<Step>
277 +**Configure API Keys**
278
209 -<Tabs items={["Python", "TypeScript"]}>
279 +<Callout type="info">
280 +Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `ANTHROPIC_API_KEY` with your [Anthropic API key](https://console.anthropic.com/settings/keys).
281 +</Callout>
282 +
283 +```txt title=".env"
284 +COMPOSIO_API_KEY=xxxxxxxxx
285 +ANTHROPIC_API_KEY=xxxxxxxxx
286 +```
287 +</Step>
288 +
289 +<Step>
290 +**Create session and run agent**
291 +
292 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
293 <Tab value="Python">
294 ```python
295 import anthropic
296 +from dotenv import load_dotenv
297 +load_dotenv()
298
299 from composio import Composio
300 from composio_anthropic import AnthropicProvider
301
217 -# Initialize tools.
302 +# Initialize Composio with Anthropic provider
303 anthropic_client = anthropic.Anthropic()
304 composio = Composio(provider=AnthropicProvider())
305 +
306 +external_user_id = "user_2nFh83Hde"
307 +recipient_email = "soham.g@composio.dev"
308 +
309 +# Create a session
310 +session = composio.create(user_id=external_user_id)
311 +
312 +# Get tools from the session
313 +tools = session.tools()
314 +
315 +# Get response from the LLM
316 +response = anthropic_client.messages.create(
317 + model="claude-sonnet-4-5",
318 + max_tokens=1024,
319 + tools=tools,
320 + messages=[
321 + {"role": "user", "content": f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'"},
322 + ],
323 +)
324 +
325 +# Execute the function calls
326 +result = composio.provider.handle_tool_calls(user_id=external_user_id, response=response)
327 +print(result)
328 ```
329 </Tab>
330 <Tab value="TypeScript">
331 ```typescript
332 +import "dotenv/config";
333 import { Composio } from "@composio/core";
334 import { AnthropicProvider } from "@composio/anthropic";
226 -import Anthropic from '@anthropic-ai/sdk';
335 +import Anthropic from "@anthropic-ai/sdk";
336
337 +// Initialize Composio with Anthropic provider
338 const composio = new Composio({
229 - provider: new AnthropicProvider({
230 - cacheTools: false, // default
231 - }),
339 + provider: new AnthropicProvider(),
340 });
233 -
341 const anthropic = new Anthropic();
342 +
343 +const externalUserId = "user_2nFh83Hde";
344 +const recipientEmail = "soham.g@composio.dev";
345 +
346 +// Create a session
347 +const session = await composio.create(externalUserId);
348 +
349 +// Get tools from the session
350 +const tools = await session.tools();
351 +
352 +// Get response from the LLM
353 +const msg = await anthropic.messages.create({
354 + model: "claude-sonnet-4-5",
355 + messages: [
356 + {
357 + role: "user",
358 + content: `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`,
359 + },
360 + ],
361 + tools: tools,
362 + max_tokens: 1000,
363 +});
364 +
365 +// Execute the function calls
366 +const result = await composio.provider.handleToolCalls(externalUserId, msg);
367 +console.log(result);
368 +```
369 +</Tab>
370 +</Tabs>
371 +</Step>
372 +</Steps>
373 +
374 +<Accordions>
375 +<Accordion title="Direct tool usage">
376 +<Callout type="info">
377 +Only use this if you want to use a single, direct tool with your AI Agent.
378 +</Callout>
379 +
380 +**Install**
381 +
382 +<Tabs items={["Python", "TypeScript"]}>
383 +<Tab value="Python">
384 +```bash
385 +pip install composio composio-anthropic anthropic
386 +```
387 +</Tab>
388 +<Tab value="TypeScript">
389 +```bash
390 +npm install @composio/core @composio/anthropic @anthropic-ai/sdk
391 ```
392 </Tab>
393 </Tabs>
394
239 -### Usage
395 +**Usage**
396
397 <Tabs items={["Python", "TypeScript"]}>
398 <Tab value="Python">
399 ```python
244 -# Define your user ID
245 -user_id = "your-user-id"
400 +import anthropic
401 +from composio import Composio
402 +from composio_anthropic import AnthropicProvider
403
247 -# Get GitHub tool for listing stargazers
248 -tools = composio.tools.get(user_id=user_id, tools=["GITHUB_LIST_STARGAZERS"])
404 +anthropic_client = anthropic.Anthropic()
405 +composio = Composio(provider=AnthropicProvider())
406 +
407 +external_user_id = "user_2nFh83Hde"
408 +recipient_email = "soham.g@composio.dev"
409 +
410 +# Get a specific tool
411 +tools = composio.tools.get(user_id=external_user_id, tools=["GMAIL_SEND_EMAIL"])
412
250 -# Get response from the LLM
413 response = anthropic_client.messages.create(
414 model="claude-sonnet-4-5",
415 max_tokens=1024,
416 tools=tools,
417 messages=[
256 - {"role": "user", "content": "List my github stargazers. for the repo composiohq/composio"},
418 + {"role": "user", "content": f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'"},
419 ],
420 )
421
260 -# Execute the function calls.
261 -result = composio.provider.handle_tool_calls(user_id=user_id, response=response)
422 +result = composio.provider.handle_tool_calls(user_id=external_user_id, response=response)
423 print(result)
424 ```
425 </Tab>
@@ -266,30 +427,37 @@ print(result)
427 ```typescript
428 import { Composio } from "@composio/core";
429 import { AnthropicProvider } from "@composio/anthropic";
269 -import Anthropic from '@anthropic-ai/sdk';
270 -const composio = new Composio({ provider: new AnthropicProvider() });
430 +import Anthropic from "@anthropic-ai/sdk";
431 +
432 +const composio = new Composio({
433 + provider: new AnthropicProvider(),
434 +});
435 const anthropic = new Anthropic();
272 -// ---cut---
273 -const userId = "your-user-id";
274 -const tools = await composio.tools.get(userId, {
275 - tools: ["GITHUB_LIST_STARGAZERS"]
276 -})
436 +
437 +const externalUserId = "user_2nFh83Hde";
438 +const recipientEmail = "soham.g@composio.dev";
439 +
440 +// Get a specific tool
441 +const tools = await composio.tools.get(externalUserId, {
442 + tools: ["GMAIL_SEND_EMAIL"],
443 +});
444
445 const msg = await anthropic.messages.create({
446 model: "claude-sonnet-4-5",
447 messages: [
448 {
449 role: "user",
283 - content: "List my github stargazers. for the repo composiohq/composio",
450 + content: `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`,
451 },
452 ],
453 tools: tools,
454 max_tokens: 1000,
455 });
456
290 -const res = await composio.provider.handleToolCalls(userId, msg);
291 -
292 -console.log(res[0].content);
457 +const result = await composio.provider.handleToolCalls(externalUserId, msg);
458 +console.log(result);
459 ```
460 </Tab>
461 </Tabs>
462 +</Accordion>
463 +</Accordions>
docs/content/docs/user-management.mdx deleted
-142
@@ -1,142 +0,0 @@
1 ----
2 -title: User Management
3 -description: Manage users and their connected accounts
4 -keywords: [user id, multi-user]
5 ----
6 -
7 -## What are User IDs?
8 -
9 -User IDs determine whose connected accounts and data you're accessing in Composio. Every tool execution, connection authorization, and account operation requires a `userId` parameter that identifies which context to use.
10 -
11 -User IDs act as containers that group connected accounts together across toolkits. Each user connects and manages their own accounts.
12 -
13 -## Choosing User IDs
14 -
15 -**Recommended:** Database UUID or primary key (`user.id`)
16 -
17 -**Acceptable:** Unique username (`user.username`)
18 -
19 -**Avoid:** Email addresses (emails can change)
20 -
21 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22 - <Tab value="Python">
23 -```python
24 -# Use your database's user ID (UUID, primary key, etc.)
25 -user_id = user.id; # e.g., "550e8400-e29b-41d4-a716-446655440000"
26 -
27 -tools = composio.tools.get(
28 - user_id=user_id,
29 - toolkits=["GITHUB"],
30 -)
31 -
32 -result = composio.tools.execute(
33 - "GITHUB_GET_REPO",
34 - user_id=user_id,
35 - arguments={
36 - "owner": 'example',
37 - "repo": 'repo'
38 - }
39 -)
40 -```
41 - </Tab>
42 - <Tab value="TypeScript">
43 -```typescript
44 -import { Composio } from '@composio/core';
45 -const composio = new Composio({ apiKey: 'your_api_key' });
46 -declare const user: { id: string };
47 -// ---cut---
48 -// Use your database's user ID (UUID, primary key, etc.)
49 -const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"
50 -
51 -const tools = await composio.tools.get(userId, {
52 - toolkits: ['github'],
53 -});
54 -
55 -const result = await composio.tools.execute('GITHUB_GET_REPO', {
56 - userId: userId,
57 - arguments: { owner: 'example', repo: 'repo' },
58 -});
59 -```
60 - </Tab>
61 -</Tabs>
62 -
63 -<Callout type="warn">
64 -Never use 'default' as a User ID in production with users. This could expose other users' data.
65 -</Callout>
66 -
67 -## Multiple Connected Accounts
68 -
69 -A single User ID can have multiple connected accounts for the same toolkit. For example, a user might connect both their personal and work Gmail accounts.
70 -
71 -**Key concepts:**
72 -- Each connected account gets a unique Connected Account ID
73 -- Multiple accounts can exist under the same User ID for any toolkit
74 -- You can specify which account to use when executing tools
75 -
76 -**Account selection:**
77 -- **Explicit:** Specify the Connected Account ID to target a specific account
78 -- **Default:** If no Connected Account ID is provided, the most recently connected account is used
79 -
80 -## Example: Multi-User Application
81 -
82 -In applications with multiple users, each user connects and manages their own accounts. Every user goes through their own OAuth flow and their data remains completely isolated.
83 -
84 -**Key concepts:**
85 -- Each user authorizes their own accounts using their unique user ID
86 -- Connections are isolated - users can only access their own connected accounts
87 -- No permission checks needed since users only access their own data
88 -
89 -```typescript
90 -declare const app: { get: (path: string, handler: (req: any, res: any) => Promise<any>) => void };
91 -// ---cut---
92 -import { Composio } from '@composio/core';
93 -const composio = new Composio({
94 - apiKey: process.env.COMPOSIO_API_KEY,
95 -});
96 -
97 -// 1. User initiates GitHub connection
98 -async function connectUserToGitHub(userId: string) {
99 - const connectionRequest = await composio.toolkits.authorize(userId, 'github');
100 - return connectionRequest.redirectUrl;
101 -}
102 -
103 -// 2. Get user's connected GitHub tools
104 -async function getUserGitHubTools(userId: string) {
105 - return await composio.tools.get(userId, {
106 - toolkits: ['github'],
107 - });
108 -}
109 -
110 -// 3. Execute tool for specific user
111 -async function getUserRepos(userId: string) {
112 - return await composio.tools.execute('GITHUB_LIST_REPOS', {
113 - userId: userId,
114 - arguments: {
115 - per_page: 10,
116 - },
117 - });
118 -}
119 -
120 -// Usage in your API endpoint
121 -app.get('/api/github/repos', async (req, res) => {
122 - const userId = req.user.id; // Get from your auth system
123 -
124 - try {
125 - const repos = await getUserRepos(userId);
126 - res.json(repos.data);
127 - } catch (error) {
128 - res.status(500).json({ error: 'Failed to fetch repos' });
129 - }
130 -});
131 -```
132 -
133 -**Data isolation**: Composio ensures each userId's connections and data are completely separate. User A can never access User B's repositories.
134 -
135 -## Best Practices
136 -
137 -- Pass the correct User ID for each user
138 -- Never use 'default' in production with multiple users
139 -- Keep User IDs consistent across your application and Composio
140 -- Use stable identifiers that won't change over time
141 -
142 -**Data isolation:** Composio ensures complete isolation between User IDs. Users cannot access another ID's connections or data.
docs/content/docs/users-and-sessions-temporary.mdx new
+286
@@ -0,0 +1,286 @@
1 +---
2 +title: Users & Sessions Temporary
3 +description: Understand how Tool Router scopes tools and connections per user
4 +keywords: [session, user id, enable toolkits, disable toolkits]
5 +---
6 +
7 +A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. See [User Management](/docs/user-management) for best practices.
8 +
9 +A **session** is an ephemeral configuration that combines:
10 +- Which user's connected accounts to use
11 +- Which toolkits are available
12 +- Which auth configs to use
13 +
14 +Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.
15 +
16 +## Creating a session
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 +```python
21 +session = composio.create(user_id="user_123")
22 +```
23 +</Tab>
24 +<Tab value="TypeScript">
25 +```typescript
26 +import { Composio } from '@composio/core';
27 +const composio = new Composio({ apiKey: 'your_api_key' });
28 +// ---cut---
29 +const session = await composio.create("user_123");
30 +```
31 +</Tab>
32 +</Tabs>
33 +
34 +### Enabling toolkits
35 +
36 +Restrict the session to specific toolkits:
37 +
38 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
39 +<Tab value="Python">
40 +```python
41 +# Using array format
42 +session = composio.create(
43 + user_id="user_123",
44 + toolkits=["github", "gmail", "slack"]
45 +)
46 +
47 +# Using object format with enable key
48 +session = composio.create(
49 + user_id="user_123",
50 + toolkits={"enable": ["github", "gmail", "slack"]}
51 +)
52 +```
53 +</Tab>
54 +<Tab value="TypeScript">
55 +```typescript
56 +import { Composio } from '@composio/core';
57 +const composio = new Composio({ apiKey: 'your_api_key' });
58 +// ---cut---
59 +// Using array format
60 +const session = await composio.create("user_123", {
61 + toolkits: ["github", "gmail", "slack"],
62 +});
63 +
64 +// Using object format with enable key
65 +const session2 = await composio.create("user_123", {
66 + toolkits: { enable: ["github", "gmail", "slack"] },
67 +});
68 +```
69 +</Tab>
70 +</Tabs>
71 +
72 +### Disabling toolkits
73 +
74 +Keep all toolkits enabled except specific ones:
75 +
76 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
77 +<Tab value="Python">
78 +```python
79 +session = composio.create(
80 + user_id="user_123",
81 + toolkits={"disable": ["exa", "firecrawl"]}
82 +)
83 +```
84 +</Tab>
85 +<Tab value="TypeScript">
86 +```typescript
87 +import { Composio } from '@composio/core';
88 +const composio = new Composio({ apiKey: 'your_api_key' });
89 +// ---cut---
90 +const session = await composio.create("user_123", {
91 + toolkits: { disable: ["exa", "firecrawl"] },
92 +});
93 +```
94 +</Tab>
95 +</Tabs>
96 +
97 +### Custom auth configs
98 +
99 +Use your own OAuth credentials instead of Composio's defaults:
100 +
101 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102 +<Tab value="Python">
103 +```python
104 +session = composio.create(
105 + user_id="user_123",
106 + auth_configs={
107 + "github": "ac_your_github_config",
108 + "slack": "ac_your_slack_config"
109 + }
110 +)
111 +```
112 +</Tab>
113 +<Tab value="TypeScript">
114 +```typescript
115 +import { Composio } from '@composio/core';
116 +const composio = new Composio({ apiKey: 'your_api_key' });
117 +// ---cut---
118 +const session = await composio.create("user_123", {
119 + authConfigs: {
120 + github: "ac_your_github_config",
121 + slack: "ac_your_slack_config",
122 + },
123 +});
124 +```
125 +</Tab>
126 +</Tabs>
127 +
128 +See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
129 +
130 +## Connected accounts
131 +
132 +Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure *which* connections to use, but don't own the connections themselves.
133 +
134 +### Account selection
135 +
136 +If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
137 +
138 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
139 +<Tab value="Python">
140 +```python
141 +session = composio.create(
142 + user_id="user_123",
143 + connected_accounts={
144 + "gmail": "ca_work_gmail",
145 + "github": "ca_personal_github"
146 + }
147 +)
148 +```
149 +</Tab>
150 +<Tab value="TypeScript">
151 +```typescript
152 +import { Composio } from '@composio/core';
153 +const composio = new Composio({ apiKey: 'your_api_key' });
154 +// ---cut---
155 +const session = await composio.create("user_123", {
156 + connectedAccounts: {
157 + gmail: "ca_work_gmail",
158 + github: "ca_personal_github",
159 + },
160 +});
161 +```
162 +</Tab>
163 +</Tabs>
164 +
165 +### Precedence
166 +
167 +When executing a tool, Tool Router selects the connected account in this order:
168 +
169 +1. `connectedAccounts` override if provided in session config
170 +2. `authConfigs` override - finds or creates connection on that config
171 +3. Auth config previously created by Tool Router for this toolkit
172 +4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
173 +5. Error if no Composio managed auth scheme exists for the toolkit
174 +
175 +If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
176 +
177 +## Session methods
178 +
179 +### mcp
180 +
181 +Get the MCP server URL to use with any MCP-compatible client.
182 +
183 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
184 +<Tab value="Python">
185 +```python
186 +mcp_url = session.mcp.url
187 +```
188 +</Tab>
189 +<Tab value="TypeScript">
190 +```typescript
191 +import { Composio } from '@composio/core';
192 +const composio = new Composio({ apiKey: 'your_api_key' });
193 +const session = await composio.create("user_123");
194 +// ---cut---
195 +const { mcp } = session;
196 +console.log(mcp.url);
197 +```
198 +</Tab>
199 +</Tabs>
200 +
201 +For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
202 +
203 +### tools()
204 +
205 +Get native tools from the session for use with AI frameworks.
206 +
207 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
208 +<Tab value="Python">
209 +```python
210 +tools = session.tools()
211 +```
212 +</Tab>
213 +<Tab value="TypeScript">
214 +```typescript
215 +import { Composio } from '@composio/core';
216 +const composio = new Composio({ apiKey: 'your_api_key' });
217 +const session = await composio.create("user_123");
218 +// ---cut---
219 +const tools = await session.tools();
220 +```
221 +</Tab>
222 +</Tabs>
223 +
224 +### authorize()
225 +
226 +Manually authenticate a user to a toolkit outside of the chat flow.
227 +
228 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
229 +<Tab value="Python">
230 +```python
231 +connection_request = session.authorize("github")
232 +
233 +print(connection_request.redirect_url)
234 +
235 +connected_account = connection_request.wait_for_connection()
236 +```
237 +</Tab>
238 +<Tab value="TypeScript">
239 +```typescript
240 +import { Composio } from '@composio/core';
241 +const composio = new Composio({ apiKey: 'your_api_key' });
242 +const session = await composio.create("user_123");
243 +// ---cut---
244 +const connectionRequest = await session.authorize("github", {
245 + callbackUrl: "https://myapp.com/callback",
246 +});
247 +
248 +console.log(connectionRequest.redirectUrl);
249 +
250 +const connectedAccount = await connectionRequest.waitForConnection();
251 +```
252 +</Tab>
253 +</Tabs>
254 +
255 +For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
256 +
257 +### toolkits()
258 +
259 +List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
260 +
261 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
262 +<Tab value="Python">
263 +```python
264 +toolkits = session.toolkits()
265 +
266 +for toolkit in toolkits.items:
267 + status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
268 + print(f"{toolkit.name}: {status}")
269 +```
270 +</Tab>
271 +<Tab value="TypeScript">
272 +```typescript
273 +import { Composio } from '@composio/core';
274 +const composio = new Composio({ apiKey: 'your_api_key' });
275 +const session = await composio.create("user_123");
276 +// ---cut---
277 +const toolkits = await session.toolkits();
278 +
279 +toolkits.items.forEach((toolkit) => {
280 + console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
281 +});
282 +```
283 +</Tab>
284 +</Tabs>
285 +
286 +Returns the first 20 toolkits by default.
docs/content/docs/users-and-sessions.mdx
+28 -256
@@ -1,286 +1,58 @@
1 ---
2 -title: Users and sessions
3 -description: Understand how Tool Router scopes tools and connections per user
4 -keywords: [session, user id, enable toolkits, disable toolkits]
2 +title: Users & Sessions
3 +description: How Composio scopes tools and connections to your users
4 +keywords: [session, user id, concepts]
5 ---
6
7 -A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. See [User Management](/docs/user-management) for best practices.
7 +When building AI agents for multiple users, each user needs their own connections and context. This is represented through **users** and **sessions**.
8
9 -A **session** is an ephemeral configuration that combines:
10 -- Which user's connected accounts to use
11 -- Which toolkits are available
12 -- Which auth configs to use
9 +## Users
10
14 -Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.
11 +A user is an identifier from your app. When someone connects their Gmail or GitHub, that connection is stored under their user ID, so tools always run with the right authentication. Every tool execution and authorization uses the user ID to identify the context. Connections are fully isolated between user IDs.
12
16 -## Creating a session
13 +<Accordions>
14 +<Accordion title="Best practices for User IDs">
15 +- **Recommended:** Database UUID or primary key (`user.id`)
16 +- **Acceptable:** Unique username (`user.username`)
17 +- **Avoid:** Email addresses (they can change)
18 +- **Never:** `default` in production (exposes other users' data)
19 +</Accordion>
20 +</Accordions>
21
18 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 -<Tab value="Python">
20 -```python
21 -session = composio.create(user_id="user_123")
22 -```
23 -</Tab>
24 -<Tab value="TypeScript">
25 -```typescript
26 -import { Composio } from '@composio/core';
27 -const composio = new Composio({ apiKey: 'your_api_key' });
28 -// ---cut---
29 -const session = await composio.create("user_123");
30 -```
31 -</Tab>
32 -</Tabs>
33 -
34 -### Enabling toolkits
35 -
36 -Restrict the session to specific toolkits:
37 -
38 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
39 -<Tab value="Python">
40 -```python
41 -# Using array format
42 -session = composio.create(
43 - user_id="user_123",
44 - toolkits=["github", "gmail", "slack"]
45 -)
46 -
47 -# Using object format with enable key
48 -session = composio.create(
49 - user_id="user_123",
50 - toolkits={"enable": ["github", "gmail", "slack"]}
51 -)
52 -```
53 -</Tab>
54 -<Tab value="TypeScript">
55 -```typescript
56 -import { Composio } from '@composio/core';
57 -const composio = new Composio({ apiKey: 'your_api_key' });
58 -// ---cut---
59 -// Using array format
60 -const session = await composio.create("user_123", {
61 - toolkits: ["github", "gmail", "slack"],
62 -});
63 -
64 -// Using object format with enable key
65 -const session2 = await composio.create("user_123", {
66 - toolkits: { enable: ["github", "gmail", "slack"] },
67 -});
68 -```
69 -</Tab>
70 -</Tabs>
71 -
72 -### Disabling toolkits
73 -
74 -Keep all toolkits enabled except specific ones:
75 -
76 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
77 -<Tab value="Python">
78 -```python
79 -session = composio.create(
80 - user_id="user_123",
81 - toolkits={"disable": ["exa", "firecrawl"]}
82 -)
83 -```
84 -</Tab>
85 -<Tab value="TypeScript">
86 -```typescript
87 -import { Composio } from '@composio/core';
88 -const composio = new Composio({ apiKey: 'your_api_key' });
89 -// ---cut---
90 -const session = await composio.create("user_123", {
91 - toolkits: { disable: ["exa", "firecrawl"] },
92 -});
93 -```
94 -</Tab>
95 -</Tabs>
96 -
97 -### Custom auth configs
98 -
99 -Use your own OAuth credentials instead of Composio's defaults:
100 -
101 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102 -<Tab value="Python">
103 -```python
104 -session = composio.create(
105 - user_id="user_123",
106 - auth_configs={
107 - "github": "ac_your_github_config",
108 - "slack": "ac_your_slack_config"
109 - }
110 -)
111 -```
112 -</Tab>
113 -<Tab value="TypeScript">
114 -```typescript
115 -import { Composio } from '@composio/core';
116 -const composio = new Composio({ apiKey: 'your_api_key' });
117 -// ---cut---
118 -const session = await composio.create("user_123", {
119 - authConfigs: {
120 - github: "ac_your_github_config",
121 - slack: "ac_your_slack_config",
122 - },
123 -});
124 -```
125 -</Tab>
126 -</Tabs>
127 -
128 -See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
129 -
130 -## Connected accounts
131 -
132 -Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure *which* connections to use, but don't own the connections themselves.
133 -
134 -### Account selection
135 -
136 -If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
137 -
138 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
139 -<Tab value="Python">
140 -```python
141 -session = composio.create(
142 - user_id="user_123",
143 - connected_accounts={
144 - "gmail": "ca_work_gmail",
145 - "github": "ca_personal_github"
146 - }
147 -)
148 -```
149 -</Tab>
150 -<Tab value="TypeScript">
151 -```typescript
152 -import { Composio } from '@composio/core';
153 -const composio = new Composio({ apiKey: 'your_api_key' });
154 -// ---cut---
155 -const session = await composio.create("user_123", {
156 - connectedAccounts: {
157 - gmail: "ca_work_gmail",
158 - github: "ca_personal_github",
159 - },
160 -});
161 -```
162 -</Tab>
163 -</Tabs>
164 -
165 -### Precedence
166 -
167 -When executing a tool, Tool Router selects the connected account in this order:
22 +A user can have multiple connections to the same toolkit.
23 +Let's say you want to allow users to connect both their work and personal email. You can represent the user with the same user ID but differentiate between the two with the connected
24 +account ID.
25
169 -1. `connectedAccounts` override if provided in session config
170 -2. `authConfigs` override - finds or creates connection on that config
171 -3. Auth config previously created by Tool Router for this toolkit
172 -4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
173 -5. Error if no Composio managed auth scheme exists for the toolkit
26 +Here is a detailed guide on how to manage such connections:
27 +<Card title="Managing Multiple Connections" href="/docs/managing-multiple-connected-accounts" description="Handle multiple accounts per toolkit for a single user" />
28
175 -If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
29
177 -## Session methods
178 -
179 -### mcp
180 -
181 -Get the MCP server URL to use with any MCP-compatible client.
182 -
183 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
184 -<Tab value="Python">
185 -```python
186 -mcp_url = session.mcp.url
187 -```
188 -</Tab>
189 -<Tab value="TypeScript">
190 -```typescript
191 -import { Composio } from '@composio/core';
192 -const composio = new Composio({ apiKey: 'your_api_key' });
193 -const session = await composio.create("user_123");
194 -// ---cut---
195 -const { mcp } = session;
196 -console.log(mcp.url);
197 -```
198 -</Tab>
199 -</Tabs>
30 +## Sessions
31
201 -For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
32 +A session is an ephemeral configuration. You specify:
33
203 -### tools()
34 +- Which user's authorization and data the agent will access
35 +- What toolkits are enabled or disabled
36 +- What authentication method, scopes, and credentials to use
37
205 -Get native tools from the session for use with AI frameworks.
38 +### Creating a session
39
40 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
41 <Tab value="Python">
42 ```python
210 -tools = session.tools()
43 +session = composio.create(user_id="user_123")
44 ```
45 </Tab>
46 <Tab value="TypeScript">
47 ```typescript
48 import { Composio } from '@composio/core';
49 const composio = new Composio({ apiKey: 'your_api_key' });
217 -const session = await composio.create("user_123");
50 // ---cut---
219 -const tools = await session.tools();
220 -```
221 -</Tab>
222 -</Tabs>
223 -
224 -### authorize()
225 -
226 -Manually authenticate a user to a toolkit outside of the chat flow.
227 -
228 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
229 -<Tab value="Python">
230 -```python
231 -connection_request = session.authorize("github")
232 -
233 -print(connection_request.redirect_url)
234 -
235 -connected_account = connection_request.wait_for_connection()
236 -```
237 -</Tab>
238 -<Tab value="TypeScript">
239 -```typescript
240 -import { Composio } from '@composio/core';
241 -const composio = new Composio({ apiKey: 'your_api_key' });
51 const session = await composio.create("user_123");
243 -// ---cut---
244 -const connectionRequest = await session.authorize("github", {
245 - callbackUrl: "https://myapp.com/callback",
246 -});
247 -
248 -console.log(connectionRequest.redirectUrl);
249 -
250 -const connectedAccount = await connectionRequest.waitForConnection();
52 ```
53 </Tab>
54 </Tabs>
55
255 -For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
256 -
257 -### toolkits()
258 -
259 -List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
260 -
261 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
262 -<Tab value="Python">
263 -```python
264 -toolkits = session.toolkits()
265 -
266 -for toolkit in toolkits.items:
267 - status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
268 - print(f"{toolkit.name}: {status}")
269 -```
270 -</Tab>
271 -<Tab value="TypeScript">
272 -```typescript
273 -import { Composio } from '@composio/core';
274 -const composio = new Composio({ apiKey: 'your_api_key' });
275 -const session = await composio.create("user_123");
276 -// ---cut---
277 -const toolkits = await session.toolkits();
278 -
279 -toolkits.items.forEach((toolkit) => {
280 - console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
281 -});
282 -```
283 -</Tab>
284 -</Tabs>
56 +For details on enabling toolkits, setting auth configs, and selecting connected accounts:
57
286 -Returns the first 20 toolkits by default.
58 +<Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
docs/content/docs/using-custom-auth-configuration.mdx renamed
docs/content/docs/white-labeling-authentication.mdx renamed
docs/next.config.mjs
+9 -4
@@ -84,22 +84,22 @@ const config = {
84 },
85 {
86 source: '/tool-router/using-custom-auth-configs',
87 - destination: '/docs/guides/using-custom-auth-configuration',
87 + destination: '/docs/using-custom-auth-configuration',
88 permanent: true,
89 },
90 {
91 source: '/docs/authenticating-users/using-custom-auth-configs',
92 - destination: '/docs/guides/using-custom-auth-configuration',
92 + destination: '/docs/using-custom-auth-configuration',
93 permanent: true,
94 },
95 {
96 source: '/tool-router/white-labeling-authentication',
97 - destination: '/docs/guides/white-labeling-authentication',
97 + destination: '/docs/white-labeling-authentication',
98 permanent: true,
99 },
100 {
101 source: '/tool-router/managing-multiple-accounts',
102 - destination: '/docs/guides/managing-multiple-connected-accounts',
102 + destination: '/docs/managing-multiple-connected-accounts',
103 permanent: true,
104 },
105 // Provider redirects (old fern URLs -> new docs URLs)
@@ -176,6 +176,11 @@ const config = {
176 },
177 // Features section redirects
178 {
179 + source: '/docs/user-management',
180 + destination: '/docs/users-and-sessions#users',
181 + permanent: true,
182 + },
183 + {
184 source: '/docs/using-triggers',
185 destination: '/docs/triggers',
186 permanent: true,