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
user and session
Sushmithamallesh75af14185e13
diff --git a/fern/docs.yml b/fern/docs.ymlindex e30358815..2900e5c77 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -329,6 +329,9 @@ navigation:- page: Using as Native Toolspath: pages/dist/tool-router/using-as-native-tools.mdxslug: using-as-native-tools+ - page: Handling Files+ path: pages/dist/tool-router/file-upload-download.mdx+ slug: file-upload-download- tab: providerslayout:- section: Supported Providersdiff --git a/fern/pages/src/tool-router/creating-sessions.mdx b/fern/pages/src/tool-router/creating-sessions.mdxindex 3c0141ac3..d8db37091 100644--- a/fern/pages/src/tool-router/creating-sessions.mdx+++ b/fern/pages/src/tool-router/creating-sessions.mdx@@ -1,7 +1,342 @@----title: Creating Sessions+title: Creating sessionsimage: "https://og.composio.dev/api/og?title=Creating%20Sessions"-description: "Create and manage sessions for users"-keywords: "tool router"+description: "Configure toolkits, authentication, and connections for a session"+keywords: "sessions, create session, tool router, configuration"+hide-nav-links: false---+Create a session to configure what tools are available and how authentication works for a user.++## Basic session++Create a session with all available toolkits:++<CodeGroup>+```python Python+from composio import Composio++composio = Composio(api_key="your-api-key")+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")+```++```typescript TypeScript+import { Composio } from "@composio/core";++const composio = new Composio({ apiKey: "your-api-key" });+const session = await composio.create("pg-user-550e8400-e29b-41d4");+```+</CodeGroup>++## Configuration options++### toolkits++Restrict which toolkits are available in the session.++**Enable specific toolkits:**++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ toolkits=["github", "gmail", "slack"]+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ toolkits: ["github", "gmail", "slack"],+});+```+</CodeGroup>++**Disable specific toolkits:**++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ toolkits={"disable": ["exa", "firecrawl"]}+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ toolkits: { disable: ["exa", "firecrawl"] },+});+```+</CodeGroup>++### authConfigs++Override which auth configs to use for specific toolkits. Use this to:+- Use your own OAuth credentials ([white-labeling](/tool-router/white-labeling-authentication))+- Control which auth config Tool Router uses instead of auto-creating one++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ auth_configs={+ "github": "ac_your_github_config",+ "slack": "ac_your_slack_config"+ }+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ authConfigs: {+ github: "ac_your_github_config",+ slack: "ac_your_slack_config",+ },+});+```+</CodeGroup>++When an auth config override is provided, Tool Router uses it to find or create a connected account for the user on that config.++### connectedAccounts++Specify which connected account to use for a toolkit. Use this when:+- A user has multiple accounts for the same toolkit (e.g., personal and work Gmail)+- You need deterministic account selection instead of "most recent"++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ connected_accounts={+ "gmail": "ca_work_gmail",+ "github": "ca_personal_github"+ }+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ connectedAccounts: {+ gmail: "ca_work_gmail",+ github: "ca_personal_github",+ },+});+```+</CodeGroup>++This takes highest precedence when selecting which account to use for tool execution. See [connected account precedence](/tool-router/users-and-sessions#connected-account-precedence).++### manageConnections++Controls whether the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool is included in the session. This tool allows the agent to prompt users to connect accounts during chat.++- `true` (default) - Agent can prompt users to connect accounts via auth links+- `false` - Tool not included. Use `session.authorize()` for manual auth+- `{ callbackUrl: "..." }` - Agent can prompt users, redirects to your URL after OAuth++**Disable in-chat authentication:**++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ manage_connections=False+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ manageConnections: false,+});+```+</CodeGroup>++**Custom callback URL:**++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ manage_connections={"callback_url": "https://myapp.com/callback"}+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ manageConnections: { callbackUrl: "https://myapp.com/callback" },+});+```+</CodeGroup>++For more details, see [Using in-chat authentication](/tool-router/using-in-chat-authentication) and [Manually authenticating users](/tool-router/manually-authenticating-users).++## Full example++<CodeGroup>+```python Python+from composio import Composio+from composio_openai_agents import OpenAIAgentsProvider++composio = Composio(+ api_key="your-api-key",+ provider=OpenAIAgentsProvider()+)++session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ toolkits=["github", "gmail", "slack"],+ auth_configs={+ "github": "ac_your_github_config"+ },+ connected_accounts={+ "gmail": "ca_work_gmail"+ },+ manage_connections={"callback_url": "https://myapp.com/callback"}+)+```++```typescript TypeScript+import { Composio } from "@composio/core";+import { OpenAIAgentsProvider } from "@composio/openai-agents";++const composio = new Composio({+ apiKey: "your-api-key",+ provider: new OpenAIAgentsProvider(),+});++const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ toolkits: ["github", "gmail", "slack"],+ authConfigs: {+ github: "ac_your_github_config",+ },+ connectedAccounts: {+ gmail: "ca_work_gmail",+ },+ manageConnections: { callbackUrl: "https://myapp.com/callback" },+});+```+</CodeGroup>++## Session properties++### tools()++Get meta-tools to pass to your agent framework.++<CodeGroup>+```python Python+tools = session.tools()++agent = Agent(+ name="Assistant",+ instructions="You are a helpful assistant.",+ tools=tools+)+```++```typescript TypeScript+const tools = await session.tools();++const agent = new Agent({+ name: "Assistant",+ instructions: "You are a helpful assistant.",+ tools: tools,+});+```+</CodeGroup>++For framework-specific examples, see [Using as native tools](/tool-router/using-as-native-tools).++### mcp++Get the MCP server URL to use with any MCP-compatible client.++<CodeGroup>+```python Python+mcp_url = session.mcp.url+```++```typescript TypeScript+const { mcp } = session;+console.log(mcp.url);+```+</CodeGroup>++Example with OpenAI Agents SDK:++```typescript+import { Agent } from "@openai/agents";++const agent = new Agent({+ name: "Assistant",+ instructions: "You are a helpful assistant.",+ tools: [+ hostedMcpTool({+ serverLabel: "composio",+ serverUrl: mcp.url,+ }),+ ],+});+```++For more frameworks, see [Using with MCP clients](/tool-router/using-with-mcp-clients).++### authorize()++Manually authenticate a user to a toolkit outside of the chat flow. See [Manually authenticating users](/tool-router/manually-authenticating-users).++<CodeGroup>+```python Python+connection_request = session.authorize(+ "github",+ callback_url="https://myapp.com/callback"+)++print(connection_request.redirect_url)++connected_account = connection_request.wait_for_connection()+```++```typescript TypeScript+const connectionRequest = await session.authorize("github", {+ callbackUrl: "https://myapp.com/callback",+});++console.log(connectionRequest.redirectUrl);++const connectedAccount = await connectionRequest.waitForConnection();+```+</CodeGroup>++### toolkits()++List available toolkits and their connection status for the session. Use this to build a UI showing which apps are connected.++<CodeGroup>+```python Python+toolkits = session.toolkits(+ order_by="popularity",+ is_connected=True+)++for toolkit in toolkits:+ print(f"{toolkit.name}: {toolkit.connected_account.id if toolkit.connected_account else 'Not connected'}")+```++```typescript TypeScript+const toolkits = await session.toolkits({+ orderBy: "popularity",+ isConnected: true,+});++toolkits.forEach((toolkit) => {+ console.log(`${toolkit.name}: ${toolkit.connectedAccount?.id ?? "Not connected"}`);+});+```+</CodeGroup>++**Filter options:**+- `orderBy`: `"popularity"`, `"name"`, or `"connected_at"`+- `isConnected`: `true` to show only connected toolkits+- `category`: Filter by category (e.g., `"productivity"`, `"communication"`)+diff --git a/fern/pages/src/tool-router/file-upload-download.mdx b/fern/pages/src/tool-router/file-upload-download.mdxnew file mode 100644index 000000000..d9c6079e6--- /dev/null+++ b/fern/pages/src/tool-router/file-upload-download.mdx@@ -0,0 +1,9 @@+---+title: Handling files+image: "https://og.composio.dev/api/og?title=Handling%20Files"+description: "Handle file uploads and downloads with Tool Router"+keywords: "file upload, file download, tool router"+hide-nav-links: false+---++Coming soon.diff --git a/fern/pages/src/tool-router/overview.mdx b/fern/pages/src/tool-router/overview.mdxindex ec4d0de04..8074279bb 100644--- a/fern/pages/src/tool-router/overview.mdx+++ b/fern/pages/src/tool-router/overview.mdx@@ -23,7 +23,7 @@ To use Tool Router, create a session for a user:<CodeGroup>```python Pythonsession = composio.create(- user_id='user_id_123',+ user_id='pg-user-550e8400-e29b-41d4',toolkits=['github', 'slack', 'gmail'])@@ -35,7 +35,7 @@ session = composio.create(``````typescript TypeScript-const { tools, mcp, authorize, toolkits } = await composio.create('user_id_123', {+const { tools, mcp, authorize, toolkits } = await composio.create('pg-user-550e8400-e29b-41d4', {toolkits: ['github', 'slack', 'gmail'],});diff --git a/fern/pages/src/tool-router/quickstart.mdx b/fern/pages/src/tool-router/quickstart.mdxindex 45adfaa93..f8b5db3ea 100644--- a/fern/pages/src/tool-router/quickstart.mdx+++ b/fern/pages/src/tool-router/quickstart.mdx@@ -23,7 +23,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us<Info>`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).-`user_123`: The [ID of the user](/docs/user-management) in your system.+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.</Info>```pythonfrom composio import Composio@@ -35,7 +35,7 @@ composio = Composio()# Create a session for a user-session = composio.create(user_id="user_123")+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")```</Step>@@ -77,7 +77,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us<Info>`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).-`user_123`: The [ID of the user](/docs/user-management) in your system.+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.</Info>```typescriptimport { Composio } from "@composio/core";@@ -89,7 +89,7 @@ const composio = new Composio({});// Create a session for a user-const { tools } = await composio.create("user_123");+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");```</Step>@@ -131,7 +131,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us<Info>`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).-`user_123`: The [ID of the user](/docs/user-management) in your system.+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.</Info>```pythonfrom composio import Composio@@ -143,7 +143,7 @@ composio = Composio()# Create a session for a user-session = composio.create(user_id="user_123")+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")```</Step>@@ -185,7 +185,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us<Info>`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).-`user_123`: The [ID of the user](/docs/user-management) in your system.+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.</Info>```typescriptimport { Composio } from "@composio/core";@@ -197,7 +197,7 @@ const composio = new Composio({});// Create a session for a user-const { mcp } = await composio.create("user_123");+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");```</Step>@@ -239,7 +239,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us<Info>`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).-`user_123`: The [ID of the user](/docs/user-management) in your system.+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.</Info>```typescriptimport { Composio } from "@composio/core";@@ -251,7 +251,7 @@ const composio = new Composio({});// Create a session for a user-const { tools } = await composio.create("user_123");+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");```</Step>diff --git a/fern/pages/src/tool-router/users-and-sessions.mdx b/fern/pages/src/tool-router/users-and-sessions.mdxindex 057bb49aa..fa10cf7aa 100644--- a/fern/pages/src/tool-router/users-and-sessions.mdx+++ b/fern/pages/src/tool-router/users-and-sessions.mdx@@ -1,8 +1,80 @@----title: Users and Sessions+title: Users and sessionsimage: "https://og.composio.dev/api/og?title=Users%20and%20Sessions"-description: ""-keywords: ""-subtitle: ""+description: "Understand how Tool Router scopes tools and connections per user"+keywords: "sessions, users, tool router, configuration"hide-nav-links: false---++Sessions are ephemeral, user-scoped configurations that define what tools are available and how authentication works.++## Users++A user ID is an identifier from your system (database UUID, primary key) that Composio uses to scope connected accounts and tool access.++<CodeGroup>+```python Python+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4");+```+</CodeGroup>++User IDs can represent individuals, teams, or organizations depending on your application. For detailed patterns, see [User Management](/docs/user-management).++## Sessions++A session defines the execution context for Tool Router's meta-tools. It combines:+- Which user's connected accounts to use+- Which toolkits are available+- Which auth configs to use++Tool Router's meta-tools (search, execute, workbench, manage connections) are the same for everyone. The session determines the context they operate within - when the agent searches for tools, it searches within the session's allowed toolkits. When it executes a tool, it uses the session user's connected accounts.++### Creating a session++A session pulls together your user's auth state with your toolkit configuration. All options are optional - by default, all toolkits with Composio managed auth are enabled.++<CodeGroup>+```python Python+session = composio.create(+ user_id="pg-user-550e8400-e29b-41d4",+ toolkits=["github", "gmail", "slack"],+ auth_configs={+ "github": "ac_your_github_config"+ }+)+```++```typescript TypeScript+const session = await composio.create("pg-user-550e8400-e29b-41d4", {+ toolkits: ["github", "gmail", "slack"],+ authConfigs: {+ github: "ac_your_github_config",+ },+});+```+</CodeGroup>++For all configuration options, see [Creating sessions](/tool-router/creating-sessions).++### Connections persist++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.++## Connected account precedence++When executing a tool, Tool Router selects the connected account in this order:++1. `connectedAccounts` override if provided in session config+2. `authConfigs` override - finds or creates connection on that config+3. Auth config previously created by Tool Router for this toolkit+4. Creates new auth config using Composio managed auth (tagged as Tool Router created)+5. Error if no Composio managed auth scheme exists for the toolkit++If a user has multiple connected accounts for a toolkit, the most recently connected one is used.+