@devries-cameron20 / composio Mirror · read-only / commits / be5f7183c
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 13:15 UTC

docs: add session methods, delete temporary file

- Add session methods section to users-and-sessions.mdx - Add detailed session methods to configuring-sessions.mdx - Move Configuring Sessions card to end of page - Delete users-and-sessions-temporary.mdx - Fix broken guides/ links Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Jan 24, 2026 at 00:52 UTC be5f7183c78c2533580f73a0286b15c28cd853a1
4 files changed +154 -289
docs/content/docs/configuring-sessions.mdx
+112 -1
@@ -116,7 +116,7 @@ const session = await composio.create("user_123", {
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.
119 +See [White-labeling authentication](/docs/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/using-custom-auth-configuration) for toolkits that require your own credentials.
120
121 ## Account selection
122
@@ -160,3 +160,114 @@ When executing a tool, the connected account is selected in this order:
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.
163 +
164 +## Session methods
165 +
166 +### mcp
167 +
168 +Get the MCP server URL to use with any MCP-compatible client.
169 +
170 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
171 +<Tab value="Python">
172 +```python
173 +mcp_url = session.mcp.url
174 +```
175 +</Tab>
176 +<Tab value="TypeScript">
177 +```typescript
178 +import { Composio } from '@composio/core';
179 +const composio = new Composio({ apiKey: 'your_api_key' });
180 +const session = await composio.create("user_123");
181 +// ---cut---
182 +const { mcp } = session;
183 +console.log(mcp.url);
184 +```
185 +</Tab>
186 +</Tabs>
187 +
188 +For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
189 +
190 +### tools()
191 +
192 +Get native tools from the session for use with AI frameworks.
193 +
194 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
195 +<Tab value="Python">
196 +```python
197 +tools = session.tools()
198 +```
199 +</Tab>
200 +<Tab value="TypeScript">
201 +```typescript
202 +import { Composio } from '@composio/core';
203 +const composio = new Composio({ apiKey: 'your_api_key' });
204 +const session = await composio.create("user_123");
205 +// ---cut---
206 +const tools = await session.tools();
207 +```
208 +</Tab>
209 +</Tabs>
210 +
211 +### authorize()
212 +
213 +Manually authenticate a user to a toolkit outside of the chat flow.
214 +
215 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
216 +<Tab value="Python">
217 +```python
218 +connection_request = session.authorize("github")
219 +
220 +print(connection_request.redirect_url)
221 +
222 +connected_account = connection_request.wait_for_connection()
223 +```
224 +</Tab>
225 +<Tab value="TypeScript">
226 +```typescript
227 +import { Composio } from '@composio/core';
228 +const composio = new Composio({ apiKey: 'your_api_key' });
229 +const session = await composio.create("user_123");
230 +// ---cut---
231 +const connectionRequest = await session.authorize("github", {
232 + callbackUrl: "https://myapp.com/callback",
233 +});
234 +
235 +console.log(connectionRequest.redirectUrl);
236 +
237 +const connectedAccount = await connectionRequest.waitForConnection();
238 +```
239 +</Tab>
240 +</Tabs>
241 +
242 +For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
243 +
244 +### toolkits()
245 +
246 +List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
247 +
248 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
249 +<Tab value="Python">
250 +```python
251 +toolkits = session.toolkits()
252 +
253 +for toolkit in toolkits.items:
254 + status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
255 + print(f"{toolkit.name}: {status}")
256 +```
257 +</Tab>
258 +<Tab value="TypeScript">
259 +```typescript
260 +import { Composio } from '@composio/core';
261 +const composio = new Composio({ apiKey: 'your_api_key' });
262 +const session = await composio.create("user_123");
263 +// ---cut---
264 +const toolkits = await session.toolkits();
265 +
266 +toolkits.items.forEach((toolkit) => {
267 + console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
268 +});
269 +```
270 +</Tab>
271 +</Tabs>
272 +
273 +Returns the first 20 toolkits by default.
docs/content/docs/meta.json
-1
@@ -6,7 +6,6 @@
6 "quickstart-tool-router",
7 "providers",
8 "---Core Concepts---",
9 - "users-and-sessions-temporary",
9 "users-and-sessions",
10 "authentication",
11 "tools-and-toolkits",
docs/content/docs/users-and-sessions-temporary.mdx deleted
-286
@@ -1,286 +0,0 @@
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
+42 -1
@@ -53,6 +53,47 @@ const session = await composio.create("user_123");
53 </Tab>
54 </Tabs>
55
56 -For details on enabling toolkits, setting auth configs, and selecting connected accounts:
56 +### Session methods
57 +
58 +Once created, a session provides methods to get tools and manage connections:
59 +
60 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
61 +<Tab value="Python">
62 +```python
63 +# Get tools for your AI framework
64 +tools = session.tools()
65 +
66 +# Get MCP server URL
67 +mcp_url = session.mcp.url
68 +
69 +# Authenticate a user to a toolkit
70 +connection_request = session.authorize("github")
71 +
72 +# List available toolkits and their connection status
73 +toolkits = session.toolkits()
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 +const session = await composio.create("user_123");
81 +// ---cut---
82 +// Get tools for your AI framework
83 +const tools = await session.tools();
84 +
85 +// Get MCP server URL
86 +const mcpUrl = session.mcp.url;
87 +
88 +// Authenticate a user to a toolkit
89 +const connectionRequest = await session.authorize("github");
90 +
91 +// List available toolkits and their connection status
92 +const toolkits = await session.toolkits();
93 +```
94 +</Tab>
95 +</Tabs>
96 +
97 +For details on enabling toolkits, setting auth configs, and using session methods:
98
99 <Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />