ContextQMD
Back to Composio

Configuring Sessions

docs/content/docs/configuring-sessions.mdx

0.11.17.8 KB
Original Source

Creating a session

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
session = composio.create(user_id="user_123")
</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"); ``` </Tab> </Tabs>

By default, a session has access to all toolkits in the Composio catalog. Your agent can discover and use any of them through COMPOSIO_SEARCH_TOOLS. Use the options below to restrict or customize what's available.

Enabling toolkits

Restrict the session to specific toolkits:

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
# Using array format
session = composio.create(
    user_id="user_123",
    toolkits=["github", "gmail", "slack"]
)

# Using object format with enable key
session = composio.create(
    user_id="user_123",
    toolkits={"enable": ["github", "gmail", "slack"]}
)
</Tab> <Tab value="TypeScript"> ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); // ---cut--- // Using array format const session = await composio.create("user_123", { toolkits: ["github", "gmail", "slack"], });

// Using object format with enable key const session2 = await composio.create("user_123", { toolkits: { enable: ["github", "gmail", "slack"] }, });

</Tab>
</Tabs>

## Disabling toolkits

Keep all toolkits enabled except specific ones:

<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
session = composio.create(
    user_id="user_123",
    toolkits={"disable": ["exa", "firecrawl"]}
)
</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", { toolkits: { disable: ["exa", "firecrawl"] }, }); ``` </Tab> </Tabs>

Custom auth configs

Use your own OAuth credentials instead of Composio's defaults:

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config"
    }
)
</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", { authConfigs: { github: "ac_your_github_config", slack: "ac_your_slack_config", }, }); ``` </Tab> </Tabs>

See White-labeling authentication for branding, or Using custom auth configs for toolkits that require your own credentials.

Account selection

If a user has multiple connected accounts for the same toolkit, you can specify which one to use:

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
session = composio.create(
    user_id="user_123",
    connected_accounts={
        "gmail": "ca_work_gmail",
        "github": "ca_personal_github"
    }
)
</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", { connectedAccounts: { gmail: "ca_work_gmail", github: "ca_personal_github", }, }); ``` </Tab> </Tabs>

Precedence

When executing a tool, the connected account is selected 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 for this toolkit
  4. Creates new auth config using Composio managed auth
  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.

Session methods

mcp

Get the MCP server URL to use with any MCP-compatible client.

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
mcp_url = session.mcp.url
</Tab> <Tab value="TypeScript"> ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123"); // ---cut--- const { mcp } = session; console.log(mcp.url); ``` </Tab> </Tabs>

For framework examples, see provider-specific documentation like OpenAI Agents or Vercel AI SDK.

tools()

Get native tools from the session for use with AI frameworks.

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
tools = session.tools()
</Tab> <Tab value="TypeScript"> ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123"); // ---cut--- const tools = await session.tools(); ``` </Tab> </Tabs>

authorize()

Manually authenticate a user to a toolkit outside of the chat flow.

<Tabs groupId="language" items={['Python', 'TypeScript']} persist> <Tab value="Python">

python
connection_request = session.authorize("github")

print(connection_request.redirect_url)

connected_account = connection_request.wait_for_connection()
</Tab> <Tab value="TypeScript"> ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123"); // ---cut--- const connectionRequest = await session.authorize("github", { callbackUrl: "https://myapp.com/callback", });

console.log(connectionRequest.redirectUrl);

const connectedAccount = await connectionRequest.waitForConnection();

</Tab>
</Tabs>

For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).

### toolkits()

List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.

<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
toolkits = session.toolkits()

for toolkit in toolkits.items:
    status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
    print(f"{toolkit.name}: {status}")
</Tab> <Tab value="TypeScript"> ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123"); // ---cut--- const toolkits = await session.toolkits();

toolkits.items.forEach((toolkit) => { console.log(${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}); });

</Tab>
</Tabs>

Returns the first 20 toolkits by default.

## What to read next

<Cards>
  <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to connect accounts during conversation" />
  <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Pre-authenticate users before chat using Connect Links and session.authorize()" />
  <Card icon={<Wrench />} title="Enable & disable toolkits" href="/docs/toolkits/enable-and-disable-toolkits" description="Control which toolkits and individual tools are available in sessions" />
  <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth apps so users see your branding on consent screens" />
</Cards>